Update template

Add a few sections from the nova template, and some details that are
only useful to oslo projects.

Change-Id: I7ba6bd47321dc0ba3a2806881eb0f0a886dcd65d

specs/template.rst

@@ -1,14 +1,26 @@
 ..
-  This template should be in ReSTructured text. The filename in the git
+  This template should be in ReSTructured text.  For help with syntax,
-  repository should match the launchpad URL, for example a URL of
+  see http://sphinx-doc.org/rest.html
-  https://blueprints.launchpad.net/oslo/+spec/awesome-thing should be named
+
-  awesome-thing.rst.
+  To test out your formatting, build the docs using tox, or see:
+  http://rst.ninjs.org
+
+  The filename in the git repository should match the launchpad URL,
+  for example a URL of
+  https://blueprints.launchpad.net/oslo/+spec/awesome-thing should be
+  named awesome-thing.rst.
+
+  Please wrap text at 79 columns.
 
   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
+  If you would like to provide a diagram with your spec, ascii diagrams are
-  To test out your formatting, see http://www.tele3.cz/jbar/rest/rest.html
+  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.
 
 =============================
  The title of your blueprint
@@ -16,7 +28,7 @@
 
 Include the URL of your launchpad blueprint:
 
-https://blueprints.launchpad.net//+spec/example
+https://blueprints.launchpad.net/oslo/+spec/example
 
 Introduction paragraph -- why are we doing anything?
 
@@ -25,6 +37,12 @@ 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
 ===============
 
@@ -34,13 +52,119 @@ 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?
 
-Include where in the oslo tree hierarchy this will reside.
+Include information about which oslo repository will receive the
+change, including creating new repositories for libraries being
+graduated and backports to the incubator if necessary. List the files
+to be updated or added.
 
 Alternatives
 ------------
 
-This is an optional section, where it does apply we'd just like a demonstration
+What other ways could we do this thing? Why aren't we using those? This doesn't
-that some thought has been put into why the proposed approach is the best one.
+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.
+
+Impact on Existing APIs
+-----------------------
+
+If the change requires modifying the API of an existing oslo module or
+library, summarize those changes ("add foo argument to Blah
+constructor"). Describe how the changes can be made in a
+backwards-compatible way (required for libraries) or why that is not
+needed (desired but not required for incubated code).
+
+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 alter the API in a way that may impact security, such as
+  a new way to access sensitive information or a new way to login?
+
+* 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.
+
+Performance Impact
+------------------
+
+Describe any potential performance impact on the system, for example
+how often will new code be called, and is there a major change to the calling
+pattern of existing code.
+
+Examples of things to consider here include:
+
+* A periodic task might look like a small addition but if it calls conductor or
+  another service the load is multiplied by the number of nodes in the system.
+
+* Scheduler filters get called once per host for every instance being created,
+  so any latency they introduce is linear with the size of the system.
+
+* A small change in a utility function or a commonly used decorator can have a
+  large impacts on performance.
+
+* Calls which result in database queries (whether direct or via conductor)
+  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?
+
+Configuration Impact
+--------------------
+
+Does this change introduce any new configuration options? Describe the
+possible valid settings.
+
+Will the default values work well in real deployments?
+
+Should the new options be more generic than proposed (for example a
+flag that other drivers might want to implement as well)?
+
+Why is a new configuration option needed, instead of choosing a single
+behavior?
+
+If a configuration option is being renamed, or moved into an option
+group, describe those changes.
+
+Describe plans to deprecate configuration options, including the
+upgrade/migration path for anyone doing continuous deployment.
+
+Developer Impact
+----------------
+
+Discuss things that will affect other developers working on OpenStack,
+such as:
+
+* If the blueprint proposes a change to a driver API within a library
+  like oslo.messaging, discuss how other drivers would implement the
+  feature.
+
+* If the blueprint proposes modifying an existing module being used by
+  one or more apps, what will need to change in those apps to
+  accommodate the change here? For example, when graduating a module
+  from the incubator, does the app need a new "interface module" to
+  hold global values previously held in the incubated module? Have the
+  semantics of the module changed enough to require significant
+  modifications to the consuming applications?  API changes described
+  above can be referenced here without repeating the details.
 
 Implementation
 ==============
@@ -57,8 +181,8 @@ primary author and contact.
 Primary assignee:
   <launchpad-id or None>
 
-Can optionally can list additional ids if they intend on doing
+Other contributors:
-substantial implementation work on this blueprint.
+  <launchpad-id or None>
 
 Milestones
 ----------
@@ -73,6 +197,51 @@ 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.
 
+For graduation blueprints, start with
+https://wiki.openstack.org/wiki/Oslo/CreatingANewLibrary#Checklist and
+add any additional steps necessary at the appropriate place in the
+sequence. If no extra work is needed, referencing the checklist
+without reproducing it is sufficient.
+
+Incubation
+==========
+
+If this work reflects the addition of a new module through the
+incubator process, we want to ensure that the full life-cycle for the
+module has been thought out.
+
+Adoption
+--------
+
+Which applications would like to share the modules? We usually prefer
+at least 2 applications, but if too many applications share the
+incubated version graduation becomes more difficult.
+
+Library
+-------
+
+Which library will the new module eventually graduate into? If this is
+a new library, explain why no existing library is suitable (circular
+dependencies, no existing related library, etc.) and give a brief
+description of the new library.
+
+Remember to consider the dependencies of the library. Will it depend
+on other oslo libraries that it does not already use? Will those
+dependencies introduce a cycle?
+
+Anticipated API Stabilization
+-----------------------------
+
+What API changes are anticipated before the code will be stable enough
+to graduate? How many release cycles are needed for that API to prove
+itself?
+
+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.
 
 Dependencies
 ============
@@ -83,6 +252,26 @@ Dependencies
 - 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?
 
+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
+
+
+
 .. note::
 
   This work is licensed under a Creative Commons Attribution 3.0