Add documentation for writing specifications

We have a specification template and a keystone-specs repository, but
we don't offer any documentation or guidance on the specification
process we have.

This commit aims to clarify the difference between specifications and
RFE bug reports, and why we use both. It also describes the process
someone should follow if they want to file a feature request against
the project.

Change-Id: I5dbf6f81058de3f2a64a95e4cf34a1279a49c5dd

doc/source/contributor/index.rst

@@ -24,6 +24,7 @@ Contributor Documentation
    how-can-i-help.rst
    set-up-keystone.rst
    http-api.rst
+   proposing-features.rst
    release-notes.rst
    testing-keystone.rst
    doctor-checks.rst

doc/source/contributor/proposing-features.rst

@@ -0,0 +1,100 @@
+..
+      Copyright 2011-2012 OpenStack Foundation
+      All Rights Reserved.
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+==================
+Proposing Features
+==================
+
+Requests for enhancements or new features must follow a process that requires
+using specifications and bug reports. You can find the repository
+`here <http://git.openstack.org/cgit/openstack/keystone-specs>`_. We publish
+the contents at
+`specs.openstack.org <http://specs.openstack.org/openstack/keystone-specs/>`_.
+
+Specifications
+==============
+
+We use specifications as a way to describe, in detail, the change that we're
+making and why.
+
+To write a specification, you can follow the template provided in the
+repository. To start writing a new specification, copy the template to the
+directory that fits the project and release you plan to target. For example, if
+you want to propose a feature to keystone for the Stein release, you should do
+the following:
+
+.. code-block:: bash
+
+   $ cp specs/template.rst specs/keystone/stein/feature-foobar.rst
+
+Once you have a template in place, work through each section. Specifications
+should be descriptive and include use cases that justify the work. There are
+sections dedicated to the problem statement, the proposed solution, alternative
+solutions, security concerns, among other things. These sections are meant to
+prompt you to think about how your feature impacts users, operators,
+developers, related projects, and the existing code base. The template acts as
+a guide, so if you need to inject an ad-hoc section to describe additional
+details of your feature, don't hesitate to add one. Propose your specification
+for review when you're ready for feedback:
+
+.. code-block:: bash
+
+   $ git review
+
+The process for reviewing specifications is handled using Gerrit. We don't
+restrict the specification selection process to a particular group of
+individuals, which allows for open and collaborative feedback. We encourage
+everyone to be a part of the review process. Applying a code-review methodology
+to specifications allows different people to think through the problem you're
+trying to solve. Everyone wants to ensure the best design possible, given
+various resource constraints. This process takes time. Don't be discouraged if
+it takes longer than you anticipated for your specification to get feedback. A
+specification must have support (+2) from at least two keystone-spec core
+reviewers and it is typically approved (+Workflow) by the PTL, in order to be
+formally accepted.
+
+RFE Bug Reports
+===============
+
+Once a specification is approved, we need to track the work to implement it. To
+do this, we use Launchpad bug reports. We use bug reports because the OpenStack
+review infrastructure has existing tooling that groups patches based on commit
+message syntax. When you propose a patch that is related to a bug or a feature,
+the OpenStack Infrastructure bot automatically links the patch as a comment in
+the bug report. Comments are also immutable, allowing us to track long-running
+initiatives without losing context.
+
+To create an RFE bug report, file a bug against the appropriate project. For
+example, if we were to create an RFE bug report for the example specification
+we wrote for keystone above, we'd
+`open <https://bugs.launchpad.net/keystone/+filebug>`_ that RFE against the
+keystone project.  The title should start with "RFE: ", followed by a snippet
+of the feature or enhancement. For example, "RFE: Implement a foobar API". The
+description should be short. Since we use specifications for details, we don't
+need to duplicate information in the body of the bug report. After you create
+the bug, you can tag it with the "rfe" tag, which helps people filter feature
+work from other bug reports. Finally, if your specification has already merged,
+be sure to include a link to it as a comment. If it hasn't, you can re-propose
+your specification with ``Partial-Bug:`` followed by the bug number, at the
+bottom of your commit message. The OpenStack Infrastructure bot automatically
+updates your RFE bug report with a link to the proposed specification.
+
+If your feature is broken up into multiple commits, make sure to include
+``Partial-Bug`` in your commit messages. Additionally, use ``Closes-Bug`` in
+the last commit implementing the feature. This process ensures all patches
+written for a feature are tracked in the bug report, making it easier to audit.
+If you miss the opportunity to use the ``Closes-Bug`` tag and your feature work
+is complete, set the bug status to "Fix Committed".