Ussuri contrib docs community goal

This patch standardizes the CONTRIBUTING.rst file and adds the
required doc/source/contributor/contributing.rst

Change-Id: Icee34784ede414890704a5bd8a4b56000df49e53

CONTRIBUTING.rst

@@ -1,16 +1,19 @@
-If you would like to contribute to the development of OpenStack,
+The source repository for this project can be found at:
-you must follow the steps in this page:
 
-   https://docs.openstack.org/infra/manual/developers.html
+  https://opendev.org/openstack/cinder
 
-Once those steps have been completed, changes to OpenStack
+Pull requests submitted through GitHub are not monitored.
-should be submitted for review via the Gerrit tool, following
-the workflow documented at:
 
-   https://docs.openstack.org/infra/manual/developers.html#development-workflow
+To start contributing to OpenStack, follow the steps in the contribution guide
+to set up and use Gerrit:
 
-Pull requests submitted through GitHub will be ignored.
+  https://docs.openstack.org/contributors/code-and-documentation/quick-start.html
 
-Bugs should be filed on Launchpad, not in GitHub's issue tracker:
+Bugs should be filed on Launchpad:
 
-   https://bugs.launchpad.net/cinder
+  https://bugs.launchpad.net/cinder
+
+For more specific information about contributing to this repository, see the
+cinder contributor guide:
+
+  https://docs.openstack.org/cinder/latest/contributor/contributing.html

doc/source/contributor/contributing.rst

@@ -0,0 +1,252 @@
+============================
+So You Want to Contribute...
+============================
+
+For general information on contributing to OpenStack, please check out the
+`contributor guide <https://docs.openstack.org/contributors/>`_ to get started.
+It covers all the basics that are common to all OpenStack projects: the
+accounts you need, the basics of interacting with our Gerrit review system, how
+we communicate as a community, etc.
+
+Below will cover the more project specific information you need to get started
+with the Cinder project, which is responsible for the following OpenStack
+deliverables:
+
+cinder
+    | The OpenStack Block Storage service.
+    | code: https://opendev.org/openstack/cinder
+    | docs: https://cinder.openstack.org
+    | api-ref: https://docs.openstack.org/api-ref/block-storage
+    | Launchpad: https://launchpad.net/cinder
+
+os-brick
+    | Shared library for managing local volume attaches.
+    | code: https://opendev.org/openstack/os-brick
+    | docs: https://docs.openstack.org/os-brick
+    | Launchpad: https://launchpad.net/os-brick
+
+python-cinderclient
+    | Python client library for the OpenStack Block Storage API; includes
+      a CLI shell.
+    | code: https://opendev.org/openstack/python-cinderclient
+    | docs: https://docs.openstack.org/python-cinderclient
+    | Launchpad: https://launchpad.net/python-cinderclient
+
+python-brick-cinderclient-ext
+    | Extends the python-cinderclient library so that it can handle local
+      volume attaches.
+    | code: https://opendev.org/openstack/python-brick-cinderclient-ext
+    | docs: https://docs.openstack.org/python-brick-cinderclient-ext
+    | Launchpad: (doesn't have its own space, uses python-cinderclient's)
+
+cinderlib
+    | Library that allows direct usage of Cinder backend drivers without
+      cinder services.
+    | code: https://opendev.org/openstack/cinderlib
+    | docs: https://docs.openstack.org/cinderlib
+    | Launchpad: https://launchpad.net/cinderlib
+
+cinder-tempest-plugin
+    | Contains additional Cinder tempest-based tests beyond those in the
+      main OpenStack Integration Test Suite (tempest).
+    | code: https://opendev.org/openstack/cinder-tempest-plugin
+    | Launchpad: https://launchpad.net/cinder-tempest-plugin
+
+See the ``CONTRIBUTING.rst`` file in each code repository for more
+information about contributing to that specific deliverable.  Additionally,
+you should look over the docs links above; most components have helpful
+developer information specific to that deliverable.  (The main cinder
+documentation is especially thorough in this regard and you should read
+through it, particularly :ref:`background-concepts` and
+:ref:`programming-howtos`.)
+
+Communication
+~~~~~~~~~~~~~
+
+IRC
+    People working on the Cinder project may be found in the
+    ``#openstack-cinder`` channel on Freenode during working hours
+    in their timezone.  The channel is logged, so if you ask a question
+    when no one is around, you can check the log to see if it's been
+    answered: http://eavesdrop.openstack.org/irclogs/%23openstack-cinder/
+
+weekly meeting
+    Wednesdays at 14:00 UTC in ``#openstack-meeting-4`` on Freenode.
+    Meetings are logged: http://eavesdrop.openstack.org/meetings/cinder/
+
+    More information (including a link to the Agenda, some pointers on
+    meeting etiquette, and an ICS file to put the meeting on your calendar)
+    can be found at: http://eavesdrop.openstack.org/#Cinder_Team_Meeting
+
+mailing list
+    We use the openstack-discuss@lists.openstack.org mailing list for
+    asynchronous discussions or to communicate with other OpenStack teams.
+    Use the prefix ``[cinder]`` in your subject line (it's a high-volume
+    list, so most people use email filters).
+
+    More information about the mailing list, including how to subscribe
+    and read the archives, can be found at:
+    http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-discuss
+
+virtual meet-ups
+    From time to time, the Cinder project will have video meetings to
+    address topics not easily covered by the above methods.  These are
+    announced well in advance at the weekly meeting and on the mailing
+    list.
+
+physical meet-ups
+    The Cinder project usually has a presence at the OpenDev/OpenStack
+    Project Team Gathering that takes place at the beginning of each
+    development cycle.  Planning happens on an etherpad whose URL is
+    announced at the weekly meetings and on the mailing list.
+
+Contacting the Core Team
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+The cinder-core team is an active group of contributors who are responsible
+for directing and maintaining the Cinder project.  As a new contributor, your
+interaction with this group will be mostly through code reviews, because
+only members of cinder-core can approve a code change to be merged into the
+code repository.
+
+.. note::
+   Although your contribution will require reviews by members of
+   cinder-core, these aren't the only people whose reviews matter.
+   Anyone with a gerrit account can post reviews, so you can ask
+   other developers you know to review your code ... and you can
+   review theirs.  (A good way to learn your way around the codebase
+   is to review other people's patches.)
+
+   If you're thinking, "I'm new at this, how can I possibly provide
+   a helpful review?", take a look at `How to Review Changes the
+   OpenStack Way
+   <https://docs.openstack.org/project-team-guide/review-the-openstack-way.html>`_.
+
+   There are also some Cinder project specific reviewing guidelines
+   in the :ref:`reviewing-cinder` section of the Cinder Contributor Guide.
+
+You can learn more about the role of core reviewers in the OpenStack
+governance documentation:
+https://docs.openstack.org/contributors/common/governance.html#core-reviewer
+
+The membership list of cinder-core is maintained in gerrit:
+https://review.opendev.org/#/admin/groups/83,members
+
+You can also find the members of the cinder-core team at the Cinder weekly
+meetings.
+
+
+New Feature Planning
+~~~~~~~~~~~~~~~~~~~~
+
+The Cinder project uses both "specs" and "blueprints" to track new features.
+Here's a quick rundown of what they are and how the Cinder project uses them.
+
+specs
+    | Exist in the cinder-specs repository.
+      Each spec must have a Launchpad blueprint (see below) associated with
+      it for tracking purposes.
+
+    | A spec is required for any new Cinder core feature, anything that
+      changes the Block Storage API, or anything that entails a mass change
+      to existing drivers.
+
+    | The specs repository is: https://opendev.org/openstack/cinder-specs
+    | It contains a ``README.rst`` file explaining how to file a spec.
+
+    | You can read rendered specs docs at:
+    | https://specs.openstack.org/openstack/cinder-specs/
+
+blueprints
+    | Exist in Launchpad, where they can be targeted to release milestones.
+    | You file one at https://blueprints.launchpad.net/cinder
+
+    | Examples of changes that can be covered by a blueprint only are:
+
+    * adding a new volume, backup, or target driver; or
+    * adding support for a defined capability that already exists in the
+      base volume, backup, or target drivers
+
+Feel free to ask in ``#openstack-cinder`` or at the weekly meeting if you
+have an idea you want to develop and you're not sure whether it requires
+a blueprint *and* a spec or simply a blueprint.
+
+The Cinder project observes the following deadlines.  For the current
+development cycle, the dates of each (and a more detailed description)
+may be found on the release schedule, which you can find from:
+https://releases.openstack.org/
+
+* spec freeze (all specs must be approved by this date)
+* new driver merge deadline
+* new target driver merge deadline
+* new feature status checkpoint
+* third-party CI compliance checkpoint
+
+Additionally, the Cinder project observes the OpenStack-wide deadlines,
+for example, final release of non-client libraries (os-brick), final
+release for client libraries (python-cinderclient), feature freeze,
+etc.  These are also noted and explained on the release schedule for the
+current development cycle.
+
+Task Tracking
+~~~~~~~~~~~~~
+
+We track our tasks in Launchpad.  See the top of the page for the URL of each
+Cinder project deliverable.
+
+If you're looking for some smaller, easier work item to pick up and get started
+on, search for the 'low-hanging-fruit' tag in the Bugs section.
+
+When you start working on a bug, make sure you assign it to yourself.
+Otherwise someone else may also start working on it, and we don't want to
+duplicate efforts.  Also, if you find a bug in the code and want to post a
+fix, make sure you file a bug (and assign it to yourself!) just in case someone
+else comes across the problem in the meantime.
+
+Reporting a Bug
+~~~~~~~~~~~~~~~
+
+You found an issue and want to make sure we are aware of it? You can do so in
+the Launchpad space for the affected deliverable:
+
+* cinder: https://bugs.launchpad.net/cinder
+* os-brick: https://bugs.launchpad.net/os-brick
+* python-cinderclient: https://bugs.launchpad.net/python-cinderclient
+* python-brick-cinderclient-ext: same as for python-cinderclient, but tag
+  the bug with 'brick-cinderclient-ext'
+* cinderlib: https://bugs.launchpad.net/cinderlib
+* cinder-tempest-plugin: https://bugs.launchpad.net/cinder-tempest-plugin
+
+Getting Your Patch Merged
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The Cinder project policy is that a patch must have two +2s before it can
+be merged.  (Exceptions are documentation changes, which require only a
+single +2, and specs, for which the PTL may require more than two +2s,
+depending on the complexity of the proposal.)
+
+Patches lacking unit tests are unlikely to be approved.  Check out the
+:ref:`testing-cinder` section of the Cinder Contributors Guide for a
+discussion of the kinds of testing we do with cinder.
+
+In addition, some changes may require a release note.  Any patch that
+changes functionality, adds functionality, or addresses a significant
+bug should have a release note.  You can find more information about
+how to write a release note in the :ref:`release-notes` section of the
+Cinder Contributors Guide.
+
+Keep in mind that the best way to make sure your patches are reviewed in
+a timely manner is to review other people's patches.  We're engaged in a
+cooperative enterprise here.
+
+You can see who's been doing what with Cinder recently in Stackalytics:
+https://www.stackalytics.com/report/activity?module=cinder-group
+
+Project Team Lead Duties
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+All common PTL duties are enumerated in the `PTL guide
+<https://docs.openstack.org/project-team-guide/ptl.html>`_.
+
+Additional responsibilities for the Cinder PTL can be found by reading through
+the :ref:`managing-development` section of the Cinder documentation.

doc/source/contributor/gerrit.rst

@@ -1,3 +1,5 @@
+.. _reviewing-cinder:
+
 Code Reviews
 ============
 

doc/source/contributor/index.rst

@@ -23,6 +23,15 @@ Content includes architectural overviews, tips and tricks for setting up a
 development environment, and information on Cinder's lower level programming
 APIs.
 
+Getting Started
+---------------
+.. toctree::
+    :maxdepth: 2
+
+    contributing
+
+.. _programming-howtos:
+
 Programming HowTos and Tutorials
 --------------------------------
 .. toctree::
@@ -43,6 +52,8 @@ Programming HowTos and Tutorials
     rolling.upgrades
     groups
 
+.. _managing-development:
+
 Managing the Development Cycle
 ------------------------------
 .. toctree::
@@ -57,6 +68,8 @@ Documentation Contribution
 
    documentation
 
+.. _background-concepts:
+
 Background Concepts for Cinder
 ------------------------------
 .. toctree::

doc/source/contributor/releasenotes.rst

@@ -14,6 +14,8 @@
       License for the specific language governing permissions and limitations
       under the License.
 
+.. _release-notes:
+
 Release notes
 =============
 

doc/source/contributor/testing.rst

@@ -1,3 +1,5 @@
+.. _testing-cinder:
+
 Testing
 =======
 

doc/source/index.rst

@@ -135,11 +135,6 @@ information needed to get started. This section should help get you started.
 Please feel free to also ask any questions in the **#openstack-cinder** IRC
 channel.
 
-Getting started
-~~~~~~~~~~~~~~~
-
-* `OpenStack Contributor Guide <https://docs.openstack.org/contributors/>`_
-
 Contributing to Cinder
 ~~~~~~~~~~~~~~~~~~~~~~