From d6a56f7c10074b8b2a6494af2d039fdb6c06d11b Mon Sep 17 00:00:00 2001 From: Abhishek Kekane Date: Wed, 11 Mar 2020 06:07:34 +0000 Subject: [PATCH] Community Goal: Project PTL & Contrib Docs Update This patch standardizes the CONTRIBUTING.rst file and adds the required doc/source/contributor/contributing.rst Change-Id: I3f7ee29094085f1abefacd75f44a16fb7e679a82 Story: #2007236 Task: #38523 --- CONTRIBUTING.rst | 30 ++-- doc/source/contributor/contributing.rst | 212 +++++++++++++++++++++++ doc/source/contributor/gerrit.rst | 74 ++++++++ doc/source/contributor/index.rst | 18 ++ doc/source/contributor/release-notes.rst | 2 + doc/source/contributor/releasecycle.rst | 147 ++++++++++++++++ 6 files changed, 464 insertions(+), 19 deletions(-) create mode 100644 doc/source/contributor/contributing.rst create mode 100644 doc/source/contributor/gerrit.rst create mode 100644 doc/source/contributor/releasecycle.rst diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 6e4f289b98..5158f4de63 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -1,27 +1,19 @@ -If you would like to contribute to the development of OpenStack, -you must follow the steps documented at: +The source repository for this project can be found at: - http://docs.openstack.org/infra/manual/developers.html#getting-started + https://opendev.org/openstack/glance -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. - http://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 GitHub: +Bugs should be filed on Launchpad: - https://bugs.launchpad.net/glance + https://bugs.launchpad.net/glance -Additionally, specific guidelines for contributing to Glance may be found in -Glance's Documentation: +For more specific information about contributing to this repository, see the +glance contributor guide: - https://docs.openstack.org/glance/latest/contributor/index.html - -Please read and follow these Glance-specific guidelines, particularly the -section on `Disallowed Minor Code Changes -`_. -You will thereby prevent your friendly review team from pulling out whatever -hair they have left. Thank you for your cooperation. + https://docs.openstack.org/glance/latest/contributor/index.html diff --git a/doc/source/contributor/contributing.rst b/doc/source/contributor/contributing.rst new file mode 100644 index 0000000000..6841e85c35 --- /dev/null +++ b/doc/source/contributor/contributing.rst @@ -0,0 +1,212 @@ +============================ +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 Glance project, which is responsible for the following OpenStack +deliverables: + +glance + | The OpenStack Image service. + | code: https://opendev.org/openstack/glance + | docs: https://glance.openstack.org + | api-ref: https://docs.openstack.org/api-ref/image + | Launchpad: https://launchpad.net/glance + +glance_store + | Glance's stores library. + | code: https://opendev.org/openstack/glance_store + | docs: https://docs.openstack.org/glance_store + | Launchpad: https://launchpad.net/glance_store + +python-glanceclient + | Python client library for the OpenStack Image API; includes + a CLI shell. + | code: https://opendev.org/openstack/python-glanceclient + | docs: https://docs.openstack.org/python-glanceclient + | Launchpad: https://launchpad.net/python-glanceclient + +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. + +Communication +~~~~~~~~~~~~~ + +IRC + People working on the Glance project may be found in the + ``#openstack-glance`` 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-glance/ + +weekly meeting + Thursdays at 14:00 UTC in ``#openstack-meeting-4`` on Freenode. + Meetings are logged: http://eavesdrop.openstack.org/meetings/glance/ + + 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/#Glance_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 ``[glance]`` 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 + +physical meet-ups + The Glance 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 glance-core team is an active group of contributors who are responsible +for directing and maintaining the Glance project. As a new contributor, your +interaction with this group will be mostly through code reviews, because +only members of glance-core can approve a code change to be merged into the +code repository. + +.. note:: + Although your contribution will require reviews by members of + glance-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 + `_. + +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 glance-core is maintained in gerrit: +https://review.opendev.org/#/admin/groups/13,members + +You can also find the members of the glance-core team at the Glance weekly +meetings. + + +New Feature Planning +~~~~~~~~~~~~~~~~~~~~ + +The Glance project uses both "specs" and "blueprints" to track new features. +Here's a quick rundown of what they are and how the Glance project uses them. + +specs + | Exist in the glance-specs repository. + Each spec must have a Launchpad blueprint (see below) associated with + it for tracking purposes. + + | A spec is required for any new Glance core feature, anything that + changes the Image API, or anything that entails a mass change + to existing drivers. + + | The specs repository is: https://opendev.org/openstack/glance-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/glance-specs/ + +blueprints + | Exist in Launchpad, where they can be targeted to release milestones. + | You file one at https://blueprints.launchpad.net/glance + +You can learn more about new feature planning: +https://docs.openstack.org/glance/latest/contributor/blueprints.html + + +Feel free to ask in ``#openstack-glance`` 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 Glance 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 Glance project observes the OpenStack-wide deadlines, +for example, final release of non-client libraries (glance_store), final +release for client libraries (python-glanceclient), 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 +Glance 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: + +* glance: https://bugs.launchpad.net/glance +* glance_store: https://bugs.launchpad.net/glance_store +* python-glanceclient: https://bugs.launchpad.net/python-glanceclient + +Getting Your Patch Merged +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The Glance 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. + +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 +Glance 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 Glance recently in Stackalytics: +https://www.stackalytics.com/report/activity?module=glance-group + +Project Team Lead Duties +~~~~~~~~~~~~~~~~~~~~~~~~ + +All common PTL duties are enumerated in the `PTL guide +`_. + +Additional responsibilities for the Glance PTL can be found by reading through +the :ref:`managing-development` section of the Glance documentation. diff --git a/doc/source/contributor/gerrit.rst b/doc/source/contributor/gerrit.rst new file mode 100644 index 0000000000..9e5592119c --- /dev/null +++ b/doc/source/contributor/gerrit.rst @@ -0,0 +1,74 @@ +.. _reviewing-glance: + +Code Reviews +============ + +Glance follows the same `Review guidelines`_ outlined by the OpenStack +community. This page provides additional information that is helpful for +reviewers of patches to Glance. + +Gerrit +------ + +Glance uses the `Gerrit`_ tool to review proposed code changes. The review +site is https://review.opendev.org + +Gerrit is a complete replacement for Github pull requests. `All Github pull +requests to the Cinder repository will be ignored`. + +See `Quick Reference`_ for information on quick reference for developers. +See `Getting Started`_ for information on how to get started using Gerrit. +See `Development Workflow`_ for more detailed information on how to work with +Gerrit. + +The Great Change +---------------- + +With the demise of Python 2.7 in January 2020, beginning with the Ussuri +development cycle, Glance only needs to support Python 3 runtimes (in +particular, 3.6 and 3.7). Thus we can begin to incorporate Python 3 +language features and remove Python 2 compatibility code. At the same +time, however, we are still supporting stable branches that must support +Python 2. Our biggest interaction with the stable branches is backporting +bugfixes, where in the ideal case, we're just doing a simple cherry-pick of +a commit from master to the stable branches. You can see that there's some +tension here. + +With that in mind, here are some guidelines for reviewers and developers +that the Glance community has agreed on during this phase where we want to +write pure Python 3 but still must support Python 2 code. + +.. _transition-guidelines: + +Python 2 to Python 3 transition guidelines +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* We need to be checking the code coverage of test cases very carefully so + that new code has excellent coverage. The idea is that we want these + tests to fail when a backport is proposed to a stable branch and the + tests are run under Python 2 (if the code is using any Python-3-only + language features). +* New features can use Python-3-only language constructs, but bugfixes + likely to be backported should be more conservative and write for + Python 2 compatibilty. +* The code for drivers may continue to use the six compatibility library at + their discretion. +* We will not remove six from mainline Cinder code that impacts the drivers + (for example, classes they inherit from). +* We can remove six from code that doesn't impact drivers, keeping in mind + that backports may be more problematic, and hence making sure that we have + really good test coverage. + +Unit Tests +---------- + +Glance requires unit tests with all patches that introduce a new +branch or function in the code. Changes that do not come with a +unit test change should be considered closely and usually returned +to the submitter with a request for the addition of unit test. + +.. _Review guidelines: https://docs.openstack.org/doc-contrib-guide/docs-review-guidelines.html +.. _Gerrit: https://review.opendev.org/#/q/project:openstack/glance+status:open +.. _Quick Reference: https://docs.openstack.org/infra/manual/developers.html#quick-reference +.. _Getting Started: https://docs.openstack.org/infra/manual/developers.html#getting-started +.. _Development Workflow: https://docs.openstack.org/infra/manual/developers.html#development-workflow diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst index 12d2c8adea..b68443cb08 100644 --- a/doc/source/contributor/index.rst +++ b/doc/source/contributor/index.rst @@ -10,6 +10,13 @@ This documentation is generated by the Sphinx toolkit and lives in the source tree. Additional documentation on Glance and other components of OpenStack can be found on the `OpenStack wiki `_. +Getting Started +--------------- +.. toctree:: + :maxdepth: 2 + + contributing + Development Policies -------------------- @@ -24,8 +31,10 @@ Development Practices .. toctree:: :maxdepth: 3 + gerrit blueprints release-notes + releasecycle documentation database_migrations .. bugs @@ -54,3 +63,12 @@ Development Roles release-cpl .. core-reviewers + +.. _managing-development: + +Managing the Development Cycle +------------------------------ +.. toctree:: + :maxdepth: 1 + + releasecycle diff --git a/doc/source/contributor/release-notes.rst b/doc/source/contributor/release-notes.rst index 0d366ef965..b7c4a4a5b8 100644 --- a/doc/source/contributor/release-notes.rst +++ b/doc/source/contributor/release-notes.rst @@ -1,3 +1,5 @@ +.. _release-notes: + Release Notes ============= diff --git a/doc/source/contributor/releasecycle.rst b/doc/source/contributor/releasecycle.rst new file mode 100644 index 0000000000..7e9dd5bb1a --- /dev/null +++ b/doc/source/contributor/releasecycle.rst @@ -0,0 +1,147 @@ +=================== +Release Cycle Tasks +=================== + +This document describes the relative ordering and rough timeline for +all of the steps related to tasks that need to be completed during a +release cycle for Glance. + +Before PTG (after closing previous release) +=========================================== + +#. Collect topics and prepare notes for PTG discussions in an etherpad. + Add a link to the etherpad to the list of PTG etherpads (for example: + https://wiki.openstack.org/wiki/PTG/Ussuri/Etherpads) + + +Between Summit and Milestone-1 +============================== + +#. Review output from the PTG and set Review-Priority on any high + priority items identified from those discussions. Send out recap to + the mailing list. + +#. Add any Glance-specific schedule information to the release calendar + (https://review.opendev.org/#/c/505425/) + +#. Focus on spec reviews to get them approved and updated early in + the cycle to allow enough time for implementation. + +#. Review new driver submissions and give early feedback so there isn't + a rush at the new driver deadline. + +#. Review community-wide goals and decide a plan or response to + them. + +Milestone-1 +=========== + +#. Propose library releases for glance_store or python-glanceclient if there + are merged commits ready to be released. Watch for any releases + proposed by the release team. + +#. Check progress on new drivers and specs and warn contributors if + it looks like they are at risk for making it in this cycle. + +Between Milestone-1 and Milestone-2 +=================================== + +#. Review stable backports and release status. + +#. Watch for and respond to updates to new driver patches. + +Milestone-2 +=========== + +#. Propose library releases for glance_store or python-glanceclient if there + are merged commits ready to be released. Watch for any releases + proposed by the release team. + +Between Milestone-2 and Milestone-3 +=================================== + +#. Review stable backports and release status. + +#. Set Review-Priority for any glance_store changes that are needed for + feature work to make sure they are ready by the library freeze prior + to Milestone-3. + +#. Make sure any new feature work that needs client changes are proposed + and on track to land before the client library freeze at Milestone-3. + +Milestone-3 +=========== + +#. Propose releases for unreleased changes in python-glanceclient. Watch + for releases proposed by the release team. Include branch request for + stable/$series creation. + +#. Set Review-Priority -1 for any feature work not complete in time for + inclusion in this cycle. Remind contributors that FFE will need to be + requested to still allow it in this cycle. + +#. Prepare "prelude" release notes as + summaries of the content of the release so that those are merged + before their first release candidate. + +#. Complete the responses to community-wide goals if not already done. + +#. Start assembling cycle-highlights for the team. + +Between Milestone-3 and RC1 +=========================== + +#. Add cycle-highlights in the releases deliverable file. + +RC1 week +======== + +#. Propose RC1 release for glance or watch for proposal from the release team. + Include stable/$series branching request with the release. + +#. Finalize any cycle-highlights for the release cycle. + +#. Remind contributors that ``master`` is now the next cycle but focus should + be on wrapping up the current cycle. + +#. Watch for translation and new stable branch patches and merge them quickly. + +Between RC1 and Final +===================== + +#. Propose additional RC releases as needed. + + .. note:: + + Try to avoid creating more than 3 release candidates so we are not + creating candidates that consumers are then trained to ignore. Each + release candidate should be kept for at least 1 day, so if there is a + proposal to create RCx but clearly a reason to create another one, + delay RCX to include the additional patches. + +#. Watch for translation patches and merge them quickly. + +#. Make sure final RC request is done one week before the final release date. + +#. Watch for the final release proposal from the release team to review and +1 + so team approval is included in the metadata that goes onto the signed tag. + +Final Release +============= + +#. Start planning for next release cycle. + +#. Check for bugfixes that would be good to backport to older stable branches. + +#. Propose any bugfix releases for things that did not make the freeze for + final library or service releases. + +Post-Final Release +================== + +#. Unblock any new driver submission patches that missed the previous + release cycle's deadline. + +#. Review approved glance-specs that were merged to the previous cycle + folder that did not get implemented. Revert or move those specs to the + next cycles's folder.