Add specs folder and design spec template

JIRA: OVSDB-461
Change-Id: I0b6e34ea32c9e5c41df889ed66d680b0df1039f7
Signed-off-by: Nobin Mathew <nobin.mathew@ericsson.com>

diff --git a/docs/index.rst b/docs/index.rst
index 752c4ac31d6ab9ee792bad90962bc4661ca189c2..8550f0cea74026a1328b7555f27eaedc3d7becd6 100644 (file)
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -11,5 +11,7 @@ as a southbound plugin.
 Contents:
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
+
+   specs/index
 

diff --git a/docs/specs/index.rst b/docs/specs/index.rst
new file mode 100644 (file)
index 0000000..3131257
--- /dev/null
+++ b/docs/specs/index.rst
@@ -0,0 +1,13 @@
+OVSDB Design Specifications
+============================
+
+Starting from Flourine, OVSDB uses RST format Design Specification document for
+all new features. These specifications are perfect way to understand various
+OVSDB features.
+
+Contents:
+
+.. toctree::
+   :maxdepth: 1
+
+   Design Specification Template <specs-template>
\ No newline at end of file

diff --git a/docs/specs/specs-template.rst b/docs/specs/specs-template.rst
new file mode 100644 (file)
index 0000000..b963d3e
--- /dev/null
+++ b/docs/specs/specs-template.rst
@@ -0,0 +1,182 @@
+..
+ Key points to consider:
+  * Use RST format. For help with syntax refer http://sphinx-doc.org/rest.html
+  * Use http://rst.ninjs.org/ a web based WYSIWYG RST editor.
+  * For diagrams, you can use http://asciiflow.com to make ascii diagrams.
+  * MUST READ http://docs.opendaylight.org/en/latest/documentation.html and follow guidelines.
+  * Use same topic branch name for all patches related to this feature.
+  * All sections should be retained, but can be marked None or N.A.
+  * Set depth in ToC as per your doc requirements. Should be at least 2.
+
+.. contents:: Table of Contents
+      :depth: 3
+
+=====================
+Title of the feature
+=====================
+
+[link to gerrit patch]
+
+Brief introduction of the feature.
+
+
+Problem description
+===================
+
+Detailed description of the problem being solved by this feature
+
+Use Cases
+---------
+
+Use cases addressed by this feature.
+
+Proposed change
+===============
+
+Details of the proposed change.
+
+Pipeline changes
+----------------
+Any changes to pipeline must be captured explicitly in this section.
+
+Yang changes
+------------
+This should detail any changes to yang models.
+
+Configuration impact
+---------------------
+Any configuration parameters being added/deprecated for this feature?
+What will be defaults for these? How will it impact existing deployments?
+
+Note that outright deletion/modification of existing configuration
+is not allowed due to backward compatibility. They can only be deprecated
+and deleted in later release(s).
+
+Clustering considerations
+-------------------------
+This should capture how clustering will be supported. This can include but
+not limited to use of CDTCL, EOS, Cluster Singleton etc.
+
+Other Infra considerations
+--------------------------
+This should capture impact from/to different infra components like
+MDSAL Datastore, karaf, AAA etc.
+
+Security considerations
+-----------------------
+Document any security related issues impacted by this feature.
+
+Scale and Performance Impact
+----------------------------
+What are the potential scale and performance impacts of this change?
+Does it help improve scale and performance or make it worse?
+
+Targeted Release
+-----------------
+What release is this feature targeted for?
+
+Alternatives
+------------
+Alternatives considered and why they were not selected.
+
+Usage
+=====
+How will end user use this feature? Primary focus here is how this feature
+will be used in an actual deployment.
+
+This section will be primary input for Test and Documentation teams.
+Along with above this should also capture REST API and CLI.
+
+Features to Install
+-------------------
+ovsdb
+
+Identify existing karaf feature to which this change applies and/or new karaf
+features being introduced. These can be user facing features which are added
+to integration/distribution or internal features to be used by other projects.
+
+REST API
+--------
+Sample JSONS/URIs. These will be an offshoot of yang changes. Capture
+these for User Guide, CSIT, etc.
+
+CLI
+---
+Any CLI if being added.
+
+
+Implementation
+==============
+
+Assignee(s)
+-----------
+Who is implementing this feature? In case of multiple authors, designate a
+primary assignee and other contributors.
+
+Primary assignee:
+  <developer-a>
+
+Other contributors:
+  <developer-b>
+  <developer-c>
+
+
+Work Items
+----------
+Break up work into individual items. This should be a checklist on
+Trello card for this feature. Give link to trello card or duplicate it.
+
+
+Dependencies
+============
+Any dependencies being added/removed? Dependencies here refers to internal
+[other ODL projects] as well as external [OVS, karaf, JDK etc.] This should
+also capture specific versions if any of these dependencies.
+e.g. OVS version, Linux kernel version, JDK etc.
+
+This should also capture impacts on existing project that depend on OVSDB.
+Following projects currently depend on OVSDB:
+* Netvirt
+* SFC
+* Genius
+
+Testing
+=======
+Capture details of testing that will need to be added.
+
+Unit Tests
+----------
+
+Integration Tests
+-----------------
+
+CSIT
+----
+
+Documentation Impact
+====================
+What is impact on documentation for this change? If documentation
+change is needed call out one of the <contributors> who will work with
+Project Documentation Lead to get the changes done.
+
+Don't repeat details already discussed but do reference and call them out.
+
+References
+==========
+Add any useful references. Some examples:
+
+* Links to Summit presentation, discussion etc.
+* Links to mail list discussions
+* Links to patches in other projects
+* Links to external documentation
+
+[1] `OpenDaylight Documentation Guide <http://docs.opendaylight.org/en/latest/documentation.html>`__
+
+[2] https://specs.openstack.org/openstack/nova-specs/specs/kilo/template.html
+
+.. note::
+
+  This template was derived from [2], and has been modified to support our project.
+
+  This work is licensed under a Creative Commons Attribution 3.0 Unported License.
+  http://creativecommons.org/licenses/by/3.0/legalcode

diff --git a/tox.ini b/tox.ini
index 887315dbefe2618ccd8d2d6e1e39df9af6380d8b..97276f09d3c20b7b75a2a636c4dc8c9ad4da6c85 100644 (file)
--- a/tox.ini
+++ b/tox.ini
@@ -6,8 +6,8 @@ skipsdist = true
 [testenv:docs]
 deps = -rdocs/requirements.txt
 commands =
-sphinx-build -b html -n -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/html
-echo "Generated docs available in {toxinidir}/docs/_build/html"
+    sphinx-build -b html -n -d {envtmpdir}/doctrees ./docs/ {toxinidir}/docs/_build/html
+    echo "Generated docs available in {toxinidir}/docs/_build/html"
 whitelist_externals = echo
 
 [testenv:docs-linkcheck]