updated docs on specs workflow

Change-Id: Ie41f04a1666c357d912e1a9c1b464836f00efc33

CONTRIBUTING.rst

@@ -2,12 +2,18 @@
 Contributing to swift-specs
 ===========================
 
+HowToContribute
+---------------
+
 If you would like to contribute to the development of OpenStack,
 you must follow the steps in the "If you're a developer, start here"
 section of this page:
 
    http://wiki.openstack.org/HowToContribute
 
+GerritWorkFlow
+--------------
+
 Once those steps have been completed, changes to OpenStack
 should be submitted for review via the Gerrit tool, following
 the workflow documented at:

README.rst

@@ -8,22 +8,32 @@ has signed off on the approach to solving a problem early on.
 
 Repository Structure
 ====================
-The expected structure of the respository is as follows::
+The structure of the repository is as follows::
 
   specs/
-      swift/
-      swift-bench/
-      swiftclient/
+      done/
+      in_progress/
 
-Implemented specs will be moved to an ``implemented`` directory
-under the respective project directory.
+Implemented specs will be moved to :ref:`done-directory`
+once the associated code has landed.
 
-Revisiting Specifications
-=========================
-We don't always get everything right the first time. If we realize we
-need to revisit a specification because something changed, either we
-now know more, or a new idea came in which we should embrace, we'll
-manage this by proposing an update to the specification in question.
+The Flow of an Idea from your Head to Implementation
+====================================================
+First propose a spec to the ``in_progress`` directory so that it can be
+reviewed. Reviewers adding a positive +1/+2 review in gerrit are promising
+that they will review the code when it is proposed. Spec documents should be
+approved and merged as soon as possible, and spec documents in the
+``in_progress`` directory can be updated as often as needed. Iterate on it.
+
+#. Have an idea
+#. Propose a spec
+#. Reviewers review the spec. As soon as 2 core reviewers like something,
+   merge it. Iterate on the spec as often as needed, and keep it updated.
+#. Once there is agreement on the spec, write the code.
+#. As the code changes during review, keep the spec updated as needed.
+#. Once the code lands (with all necessary tests and docs), the spec can be
+   moved to the ``done`` directory. If a feature needs a spec, it needs
+   docs, and the docs must land before or with the feature (not after).
 
 Learn As We Go
 ==============

doc/source/index.rst

@@ -1,52 +1,33 @@
 Swift Design Specifications
 ===========================
 
-Swift
------
-
 .. toctree::
    :glob:
    :maxdepth: 1
 
-   specs/swift/*
-
-.. NOTE(dhellmann): Uncomment this section after the first real
-   swift-bench spec is added.
-
-   Swift Bench
-   -----------
-
-   .. toctree::
-      :glob:
-      :maxdepth: 1
-
-      specs/swift-bench/*
-
-.. NOTE(dhellmann): Uncomment this section after the first real
-   swift-client spec is added.
-
-   Swift Client
-   ------------
-
-   .. toctree::
-      :glob:
-      :maxdepth: 1
-
-      specs/swiftclient/*
-
+   specs/in_progress/*
 
 Specifications Repository Information
 =====================================
 
 .. toctree::
+   :glob:
    :maxdepth: 2
 
-   README <readme_link>
-   How to Contribute <contributing_link>
+   *
 
+Archived Specs
+==============
+
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   specs/done/*
 
 Indices and tables
 ==================
 
 * :ref:`genindex`
 * :ref:`search`
+

specs/done/README.rst

@@ -0,0 +1,15 @@
+.. _done-directory:
+
+The ``Done`` Directory
+======================
+
+This directory in the specs repo is where specs are moved once the
+associated code patch has been merged into its respective repo.
+
+Historical Reference
+--------------------
+
+A spec document in this directory is meant only for historical
+reference, it does not equate to docs for the feature.  Swift's
+documentation for implemented features is published
+`here <http://docs.openstack.org/developer/swift/>`_.

specs/swift/test.rst

@@ -1,84 +0,0 @@
-::
-
-  This work is licensed under a Creative Commons Attribution 3.0
-  Unported License.
-  http://creativecommons.org/licenses/by/3.0/legalcode
-
-==================
-Test Specification
-==================
-
-This is a test specification.  It should be removed after the first
-real specification is merged.
-
-Problem description
-===================
-
-A detailed description of the problem.
-
-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
-------------
-
-This is an optional section, where it does apply we'd just like a demonstration
-that some thought has been put into why the proposed approach is the best one.
-
-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>
-
-Can optionally list additional ids if they intend on doing substantial
-implementation work on this blueprint.
-
-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.
-
-Repositories
-------------
-
-Will any new git repositories need to be created?
-
-Servers
--------
-
-Will any new servers need to be created?  What existing servers will
-be affected?
-
-DNS Entries
------------
-
-Will any other DNS entries need to be created or updated?
-
-Dependencies
-============
-
-- Include specific references to specs and/or stories in infra, or in
-  other projects, that this one either depends on or is related to.
-
-- Does this feature require any new library or program dependencies
-  not already in use?
-
-- Does it require a new puppet module?

specs/swiftclient/test.rst

@@ -1,84 +0,0 @@
-::
-
-  This work is licensed under a Creative Commons Attribution 3.0
-  Unported License.
-  http://creativecommons.org/licenses/by/3.0/legalcode
-
-==================
-Test Specification
-==================
-
-This is a test specification.  It should be removed after the first
-real specification is merged.
-
-Problem description
-===================
-
-A detailed description of the problem.
-
-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
-------------
-
-This is an optional section, where it does apply we'd just like a demonstration
-that some thought has been put into why the proposed approach is the best one.
-
-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>
-
-Can optionally list additional ids if they intend on doing substantial
-implementation work on this blueprint.
-
-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.
-
-Repositories
-------------
-
-Will any new git repositories need to be created?
-
-Servers
--------
-
-Will any new servers need to be created?  What existing servers will
-be affected?
-
-DNS Entries
------------
-
-Will any other DNS entries need to be created or updated?
-
-Dependencies
-============
-
-- Include specific references to specs and/or stories in infra, or in
-  other projects, that this one either depends on or is related to.
-
-- Does this feature require any new library or program dependencies
-  not already in use?
-
-- Does it require a new puppet module?