Merge "Add specification directory, template, and indices"

doc/source/conf.py

@@ -38,6 +38,12 @@ if not on_read_the_docs:
 # The suffix of source filenames.
 source_suffix = '.rst'
 
+# List of patterns (relative to the source directory) used to ignore matching
+# files.
+exclude_patterns = [
+    '**/template.rst',
+]
+
 # The master toctree document.
 master_doc = 'index'
 

doc/source/index.rst

@@ -19,6 +19,13 @@ Contents:
    authentication-documentation
    contributing
 
+Specifications for python-cratonclient:
+
+.. toctree::
+    :maxdepth: 1
+
+    specs/index
+
 Indices and tables
 ==================
 

doc/source/specs/approved/template.rst

@@ -0,0 +1 @@
+../template.rst

doc/source/specs/index.rst

@@ -0,0 +1,25 @@
+=========================================
+ Fleet Management Service Specifications
+=========================================
+
+All current approved Craton API specifications:
+
+.. toctree::
+    :glob:
+    :maxdepth: 1
+
+    approved/*
+
+
+All implemented Craton API specifications:
+
+.. toctree::
+    :glob:
+    :maxdepth: 1
+
+    implemented/*
+
+Indices and Tables
+==================
+
+* :ref:`search`

doc/source/specs/template.rst

@@ -0,0 +1,212 @@
+..
+ This work is licensed under a Creative Commons Attribution 3.0 Unported
+ License.
+
+ http://creativecommons.org/licenses/by/3.0/legalcode
+
+==========================================
+Example Spec - The title of your blueprint
+==========================================
+
+Include the URL of your launchpad blueprint:
+
+https://blueprints.launchpad.net/python-cratonclient/+spec/example
+
+Introduction paragraph -- why are we doing anything? A single paragraph of
+prose that operators can understand.
+
+Some notes about using this template:
+
+* Your spec should be in ReSTructured text, like this template.
+
+* Please wrap text at 79 columns.
+
+* The filename in the git repository should match the launchpad URL, for
+  example a URL of:
+  https://blueprints.launchpad.net/python-cratonclient/+spec/awesome-thing
+  should be named awesome-thing.rst
+
+* Please do not delete any of the sections in this template.  If you have
+  nothing to say for a whole section, just write: None
+
+* For help with syntax, see http://sphinx-doc.org/rest.html
+
+* To test out your formatting, build the docs using tox, or see:
+  https://www.siafoo.net/reST.xml
+
+* If you would like to provide a diagram with your spec, ascii diagrams are
+  required.  http://asciiflow.com/ is a very nice tool to assist with making
+  ascii diagrams.  The reason for this is that the tool used to review specs is
+  based purely on plain text.  Plain text will allow review to proceed without
+  having to look at additional files which can not be viewed in gerrit.  It
+  will also allow inline feedback on the diagram itself.
+
+
+Problem description
+===================
+
+A detailed description of the problem:
+
+* For a new feature this might be use cases. Ensure you are clear about the
+  actors in each use case: End User vs Deployer
+
+* For a major reworking of something existing it would describe the
+  problems in that feature that are being addressed.
+
+
+Proposed change
+===============
+
+Here is where you cover the change you propose to make in detail. How do you
+propose to solve this problem?
+
+If this is one part of a larger effort make it clear where this piece ends. In
+other words, what's the scope of this effort?
+
+Alternatives
+------------
+
+What other ways could we do this thing? Why aren't we using those? This doesn't
+have to be a full literature review, but it should demonstrate that thought has
+been put into why the proposed solution is an appropriate one.
+
+
+Security impact
+---------------
+
+Describe any potential security impact on the system.  Some of the items to
+consider include:
+
+* Does this change touch sensitive data such as tokens, keys, or user data?
+
+* Does this change involve cryptography or hashing?
+
+* Does this change require the use of sudo or any elevated privileges?
+
+* Does this change involve using or parsing user-provided data? This could
+  be directly at the API level or indirectly such as changes to a cache layer.
+
+* Can this change enable a resource exhaustion attack, such as allowing a
+  single API interaction to consume significant server resources? Some examples
+  of this include launching subprocesses for each connection, or entity
+  expansion attacks in XML.
+
+For more detailed guidance, please see the OpenStack Security Guidelines as
+a reference (https://wiki.openstack.org/wiki/Security/Guidelines).  These
+guidelines are a work in progress and are designed to help you identify
+security best practices.  For further information, feel free to reach out
+to the OpenStack Security Group at openstack-security@lists.openstack.org.
+
+Other end user impact
+---------------------
+
+Aside from the API, are there other ways a user will interact with this
+feature?
+
+Performance Impact
+------------------
+
+Describe any potential performance impact on the system. How often will new
+code be called? Is there a major change to the calling pattern of existing
+code?
+
+Examples of things to consider here include:
+
+* A small change in a utility function or a commonly used decorator can have a
+  large impact on performance.
+
+* Calls which result in database queries can have a profound impact on
+  performance when called in critical sections of the code.
+
+* Will the change include any locking, and if so what considerations are there
+  on holding the lock?
+
+Developer impact
+----------------
+
+Discuss things that will affect other developers working on OpenStack,
+such as:
+
+* If the blueprint proposes a change to the store API, discussion of how
+  stores would implement the feature is required.
+
+
+Implementation
+==============
+
+Assignee(s)
+-----------
+
+Who is leading the writing of the code? Or is this a blueprint where you're
+throwing it out there to see who picks it up?
+
+If more than one person is working on the implementation, please designate the
+primary author and contact.
+
+Primary assignee:
+- <launchpad-id or None>
+
+Other contributors:
+- <launchpad-id or None>
+
+Work Items
+----------
+
+Work items or tasks -- break the feature up into the things that need to be
+done to implement it. Those parts might end up being done by different people,
+but we're mostly trying to understand the timeline for implementation.
+
+
+Dependencies
+============
+
+* Include specific references to specs and/or blueprints in
+  python-cratonclient, or in other
+  projects, that this one either depends on or is related to.
+
+* If this requires functionality of another project that is not currently used
+  by python-cratonclient: document that fact.
+
+* Does this feature require any new library dependencies or code otherwise not
+  included in OpenStack? Or does it depend on a specific version of library?
+
+
+Testing
+=======
+
+Please discuss how the change will be tested. We especially want to know what
+tempest tests will be added. It is assumed that unit test coverage will be
+added so that doesn't need to be mentioned explicitly, but discussion of why
+you think unit tests are sufficient and we don't need to add more tempest
+tests would need to be included.
+
+Is this untestable in gate given current limitations (specific hardware /
+software configurations available)? If so, are there mitigation plans (3rd
+party testing, gate enhancements, etc).
+
+
+Documentation Impact
+====================
+
+What is the impact on the docs team of this change? Some changes might require
+donating resources to the docs team to have the documentation updated. Don't
+repeat details discussed above, but please reference them here.
+
+
+References
+==========
+
+Please add any useful references here. You are not required to have any
+reference. Moreover, this specification should still make sense when your
+references are unavailable. Examples of what you could include are:
+
+* Links to mailing list or IRC discussions
+
+* Links to notes from a summit session
+
+* Links to relevant research, if appropriate
+
+* Related specifications as appropriate (e.g., if it's an EC2 thing, link the
+  EC2 docs)
+
+* Anything else you feel it is worthwhile to refer to