diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 0ffb31d1a6f..c2f8ea78619 100644 --- a/CONTRIBUTING.rst +++ b/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 diff --git a/doc/source/contributor/contributing.rst b/doc/source/contributor/contributing.rst new file mode 100644 index 00000000000..da45780d723 --- /dev/null +++ b/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 `_ 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 + `_. + + 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 +`_. + +Additional responsibilities for the Cinder PTL can be found by reading through +the :ref:`managing-development` section of the Cinder documentation. diff --git a/doc/source/contributor/gerrit.rst b/doc/source/contributor/gerrit.rst index ace54115be9..645fb7e7e5c 100644 --- a/doc/source/contributor/gerrit.rst +++ b/doc/source/contributor/gerrit.rst @@ -1,3 +1,5 @@ +.. _reviewing-cinder: + Code Reviews ============ diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst index fe438330c69..941d336f7be 100644 --- a/doc/source/contributor/index.rst +++ b/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:: diff --git a/doc/source/contributor/releasenotes.rst b/doc/source/contributor/releasenotes.rst index 81e65e00039..c712759c537 100644 --- a/doc/source/contributor/releasenotes.rst +++ b/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 ============= diff --git a/doc/source/contributor/testing.rst b/doc/source/contributor/testing.rst index edca1d2538f..0593d07f8ff 100644 --- a/doc/source/contributor/testing.rst +++ b/doc/source/contributor/testing.rst @@ -1,3 +1,5 @@ +.. _testing-cinder: + Testing ======= diff --git a/doc/source/index.rst b/doc/source/index.rst index c7b4467c951..45f2836575f 100644 --- a/doc/source/index.rst +++ b/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 `_ - Contributing to Cinder ~~~~~~~~~~~~~~~~~~~~~~