Browse Source

Ussuri contrib docs community goal

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

Change-Id: Icee34784ede414890704a5bd8a4b56000df49e53
changes/06/711006/7
Brian Rosmaita 2 years ago
parent
commit
98e04c7b02
  1. 23
      CONTRIBUTING.rst
  2. 252
      doc/source/contributor/contributing.rst
  3. 2
      doc/source/contributor/gerrit.rst
  4. 13
      doc/source/contributor/index.rst
  5. 2
      doc/source/contributor/releasenotes.rst
  6. 2
      doc/source/contributor/testing.rst
  7. 5
      doc/source/index.rst

23
CONTRIBUTING.rst

@ -1,16 +1,19 @@
If you would like to contribute to the development of OpenStack,
you must follow the steps in this page:
The source repository for this project can be found at:
https://docs.openstack.org/infra/manual/developers.html
https://opendev.org/openstack/cinder
Once those steps have been completed, changes to OpenStack
should be submitted for review via the Gerrit tool, following
the workflow documented at:
Pull requests submitted through GitHub are not monitored.
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

252
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.

2
doc/source/contributor/gerrit.rst

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

13
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::

2
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
=============

2
doc/source/contributor/testing.rst

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

5
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
~~~~~~~~~~~~~~~~~~~~~~

Loading…
Cancel
Save