openstack/glance
Code Issues Proposed changes

Community Goal: Project PTL & Contrib Docs Update

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

Change-Id: I3f7ee29094085f1abefacd75f44a16fb7e679a82
Story: #2007236
Task: #38523
This commit is contained in:
Abhishek Kekane 2020-03-11 06:07:34 +00:00
parent c7ddabb15f
commit d6a56f7c10
6 changed files with 464 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
CONTRIBUTING.rst
View File

@ -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
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
<https://docs.openstack.org/glance/latest/contributor/minor-code-changes.html>`_.
You will thereby prevent your friendly review team from pulling out whatever
hair they have left. Thank you for your cooperation.

212
doc/source/contributor/contributing.rst Normal file
View File

@ -0,0 +1,212 @@
============================
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 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
<https://docs.openstack.org/project-team-guide/review-the-openstack-way.html>`_.
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
<https://docs.openstack.org/project-team-guide/ptl.html>`_.
Additional responsibilities for the Glance PTL can be found by reading through
the :ref:`managing-development` section of the Glance documentation.

74
doc/source/contributor/gerrit.rst Normal file
View File

@ -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

18
doc/source/contributor/index.rst
View File

@ -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 <http://wiki.openstack.org>`_.
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

2
doc/source/contributor/release-notes.rst
View File

@ -1,3 +1,5 @@
.. _release-notes:
Release Notes
=============

147
doc/source/contributor/releasecycle.rst Normal file
View File

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