docs/specs/specs-template.rst

   1 ..
   2  Key points to consider:
   3   * Use RST format. For help with syntax refer http://sphinx-doc.org/rest.html
   4   * Use http://rst.ninjs.org/ a web based WYSIWYG RST editor.
   5   * For diagrams, you can use http://asciiflow.com to make ascii diagrams.
   6   * MUST READ http://docs.opendaylight.org/en/latest/documentation.html and follow guidelines.
   7   * Use same topic branch name for all patches related to this feature.
   8   * All sections should be retained, but can be marked None or N.A.
   9   * Set depth in ToC as per your doc requirements. Should be at least 2.
  10
  11 .. contents:: Table of Contents
  12       :depth: 3
  13
  14 =====================
  15 Title of the feature
  16 =====================
  17
  18 [link to gerrit patch]
  19
  20 Brief introduction of the feature.
  21
  22
  23 Problem description
  24 ===================
  25
  26 Detailed description of the problem being solved by this feature
  27
  28 Use Cases
  29 ---------
  30
  31 Use cases addressed by this feature.
  32
  33 Proposed change
  34 ===============
  35
  36 Details of the proposed change.
  37
  38 Pipeline changes
  39 ----------------
  40 Any changes to pipeline must be captured explicitly in this section.
  41
  42 Yang changes
  43 ------------
  44 This should detail any changes to yang models.
  45
  46 Configuration impact
  47 ---------------------
  48 Any configuration parameters being added/deprecated for this feature?
  49 What will be defaults for these? How will it impact existing deployments?
  50
  51 Note that outright deletion/modification of existing configuration
  52 is not allowed due to backward compatibility. They can only be deprecated
  53 and deleted in later release(s).
  54
  55 Clustering considerations
  56 -------------------------
  57 This should capture how clustering will be supported. This can include but
  58 not limited to use of CDTCL, EOS, Cluster Singleton etc.
  59
  60 Other Infra considerations
  61 --------------------------
  62 This should capture impact from/to different infra components like
  63 MDSAL Datastore, karaf, AAA etc.
  64
  65 Security considerations
  66 -----------------------
  67 Document any security related issues impacted by this feature.
  68
  69 Scale and Performance Impact
  70 ----------------------------
  71 What are the potential scale and performance impacts of this change?
  72 Does it help improve scale and performance or make it worse?
  73
  74 Targeted Release
  75 -----------------
  76 What release is this feature targeted for?
  77
  78 Alternatives
  79 ------------
  80 Alternatives considered and why they were not selected.
  81
  82 Usage
  83 =====
  84 How will end user use this feature? Primary focus here is how this feature
  85 will be used in an actual deployment.
  86
  87 For most Genius features users will be other projects but this
  88 should still capture any user visible CLI/API etc. e.g. ITM configuration.
  89
  90 This section will be primary input for Test and Documentation teams.
  91 Along with above this should also capture REST API and CLI.
  92
  93 Features to Install
  94 -------------------
  95 odl-genius-ui
  96
  97 Identify existing karaf feature to which this change applies and/or new karaf
  98 features being introduced. These can be user facing features which are added
  99 to integration/distribution or internal features to be used by other projects.
 100
 101 REST API
 102 --------
 103 Sample JSONS/URIs. These will be an offshoot of yang changes. Capture
 104 these for User Guide, CSIT, etc.
 105
 106 CLI
 107 ---
 108 Any CLI if being added.
 109
 110
 111 Implementation
 112 ==============
 113
 114 Assignee(s)
 115 -----------
 116 Who is implementing this feature? In case of multiple authors, designate a
 117 primary assignee and other contributors.
 118
 119 Primary assignee:
 120   <developer-a>
 121
 122 Other contributors:
 123   <developer-b>
 124   <developer-c>
 125
 126
 127 Work Items
 128 ----------
 129 Break up work into individual items. This should be a checklist on
 130 Trello card for this feature. Give link to trello card or duplicate it.
 131
 132
 133 Dependencies
 134 ============
 135 Any dependencies being added/removed? Dependencies here refers to internal
 136 [other ODL projects] as well as external [OVS, karaf, JDK etc.] This should
 137 also capture specific versions if any of these dependencies.
 138 e.g. OVS version, Linux kernel version, JDK etc.
 139
 140 This should also capture impacts on existing project that depend on Genius.
 141 Following projects currently depend on Genius:
 142 * Netvirt
 143 * SFC
 144
 145 Testing
 146 =======
 147 Capture details of testing that will need to be added.
 148
 149 Unit Tests
 150 ----------
 151
 152 Integration Tests
 153 -----------------
 154
 155 CSIT
 156 ----
 157
 158 Documentation Impact
 159 ====================
 160 What is impact on documentation for this change? If documentation
 161 change is needed call out one of the <contributors> who will work with
 162 Project Documentation Lead to get the changes done.
 163
 164 Don't repeat details already discussed but do reference and call them out.
 165
 166 References
 167 ==========
 168 Add any useful references. Some examples:
 169
 170 * Links to Summit presentation, discussion etc.
 171 * Links to mail list discussions
 172 * Links to patches in other projects
 173 * Links to external documentation
 174
 175 [1] `OpenDaylight Documentation Guide <http://docs.opendaylight.org/en/latest/documentation.html>`__
 176
 177 [2] https://specs.openstack.org/openstack/nova-specs/specs/kilo/template.html
 178
 179 .. note::
 180
 181   This template was derived from [2], and has been modified to support our project.
 182
 183   This work is licensed under a Creative Commons Attribution 3.0 Unported License.
 184   http://creativecommons.org/licenses/by/3.0/legalcode