Re-organize the RefStack specs directory.

Change-Id: I02da57c2b7d888ae49bd4f96ba8fb46016d16e7d

specs/README.rst

@@ -1,34 +1,54 @@
-==================================
+=======================
 Refstack Specifications
-==================================
+=======================
 
 This folder is used to hold design specifications for additions
-to the Refstack project. Reviews of the specs are done in gerrit, using a similar
-workflow to how we review and merge changes to the code itself.
+to the RefStack project. Reviews of the specs are done in gerrit, using a
+similar workflow to how we review and merge changes to the code itself.
 
-Specifications are proposed by adding an .rst file to the `specs/proposed` directory and posting it for review. Not all approved blueprints will get fully implemented. You can find an example spec in `/specs/template.rst`.
+The layout of this folder is as follows::
 
-When a spec has passed the review process and discussions in our weekly meetings it will 
-be moved to 'specs/approved/'. At that time the blueprint will be marked as approved and assigned to someone.
+    specs/<release>/
+    specs/<release>/approved
+    specs/<release>/implemented
 
-Once a spec has been fully implemented, meaning a patch has landed that references the blueprint, it will be moved again to 'specs/completed'.
+The lifecycle of a specification
+--------------------------------
 
-Prior to April 2014, this method was not used for spec
-reviews. Prior reviews were completed entirely through Launchpad
-blueprints::
+Specifications are proposed by adding an .rst file to the
+``specs/<release>/approved`` directory and posting it for review. You can
+find an example specification in ``/specs/template.rst``.
 
-  http://blueprints.launchpad.net/refstack
+Once a specification has been fully implemented, meaning a patch has landed,
+it will be moved to the ``implemented`` directory and the corresponding
+blueprint will be marked as complete.
 
-Please note, Launchpad blueprints are still used for tracking the
-current status of blueprints. For more information, see::
+`Specifications are only approved for a single release`. If a specification
+was previously approved but not implemented (or not completely implemented),
+then the specification needs to be re-proposed by copying (not move) it to
+the right directory for the current release.
 
-  https://wiki.openstack.org/wiki/Blueprints
+Previously approved specifications
+----------------------------------
+
+The RefStack specs directory was re-structured during the Mitaka cycle.
+Therefore, the specs approved and implemented prior to the Mitaka cycle will be
+saved in the ``specs/prior/`` directories.
+
+Others
+------
+
+Please note, Launchpad blueprints are still used for tracking the status of the
+blueprints. For more information, see::
+
+    https://wiki.openstack.org/wiki/Blueprints
+    https://blueprints.launchpad.net/refstack
 
 For more information about working with gerrit, see::
 
-  http://docs.openstack.org/infra/manual/developers.html#development-workflow
+    http://docs.openstack.org/infra/manual/developers.html#development-workflow
 
 To validate that the specification is syntactically correct (i.e. get more
 confidence in the Jenkins result), please execute the following command::
 
-  $ tox
+    $ tox