[ussuri] [goal] Project PTL and contributor docs

This commit updates the horizon contributor docs to follow
what the community goal [1] recommended.

* Reorganize doc/source/contributor/contributing.rst to the format
  suggested in the community goal template.
* Cleanup obsolete information and topics covered by the general
  OpenStack contributor guide.
* Move contributing.rst to the top in TOC of the contributor guide
  as it is considered as the entry point for new contributors.
* Sync CONTRIBUTING.rst at the top level directory with the
  community goal template.
* Update the core reviewer expectation along with PTL expectation.

[1] https://governance.openstack.org/tc/goals/selected/ussuri/project-ptl-and-contrib-docs.html

Story: #2007236
Task: #38525

Change-Id: Idce7fc08e7fdf854d8a7bca55169d18403362c45
This commit is contained in:
Akihiro Motoki 2020-08-20 08:24:00 +09:00
parent c897a8e444
commit e0afd0d21d
4 changed files with 159 additions and 120 deletions

View File

@ -1,18 +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 documented at:
https://opendev.org/openstack/horizon
Pull requests submitted through GitHub are not monitored.
To start contributing to OpenStack, follow the steps in the contribution guide
to set up and use Gerrit:
https://docs.openstack.org/contributors/code-and-documentation/quick-start.html
Bugs should be filed on Launchpad:
https://bugs.launchpad.net/horizon
For more specific information about contributing to this repository, see the
horizon contributor guide:
https://docs.openstack.org/horizon/latest/contributor/contributing.html https://docs.openstack.org/horizon/latest/contributor/contributing.html
or https://docs.openstack.org/infra/manual/developers.html
Once those steps have been completed, changes to OpenStack
should be submitted for review via the Gerrit tool, following
the workflow documented at:
https://docs.openstack.org/infra/manual/developers.html#development-workflow
Pull requests submitted through GitHub will be ignored.
Bugs should be filed on Launchpad, not GitHub:
https://bugs.launchpad.net/horizon

View File

@ -1,111 +1,138 @@
================== ============================
Contributing Guide So You Want to Contribute...
================== ============================
First and foremost, thank you for wanting to contribute! It's the only way For general information on contributing to OpenStack, please check out the
open source works! `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.
Before you dive into writing patches, here are some of the basics: Below will cover the more project specific information you need to get started
with horizon.
Project Resources
-----------------
* Source code: https://opendev.org/openstack/horizon
* Documentation: https://docs.openstack.org/horizon/latest/
* Project page: https://launchpad.net/horizon * Project page: https://launchpad.net/horizon
* Bug tracker: https://bugs.launchpad.net/horizon * Bug tracker: https://bugs.launchpad.net/horizon
* Source code: https://github.com/openstack/horizon
* Code review: https://review.opendev.org/#/q/project:openstack/horizon+status:open * Code review: https://review.opendev.org/#/q/project:openstack/horizon+status:open
* Continuous integration:
* Jenkins: https://jenkins.openstack.org
* Zuul: http://status.openstack.org/zuul
* IRC Channel: #openstack-horizon on Freenode.
Making Contributions Communication
==================== -------------
Getting Started * IRC channel: ``#openstack-horizon`` at freenode
Most active contributors are online at IRC while they are active,
so it would be the easiest way to contact the team directly.
Note that all IRC conversations are stored
`here <http://eavesdrop.openstack.org/irclogs/%23openstack-horizon/>`__.
* Mailing list:
`openstack-discuss
<http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-discuss>`__
with ``[horizon]`` tag.
The mailing list would be a good place if you would like to discuss your
topic with the OpenStack community more broadly. Most OpenStack users,
operators and developers subscribe it and you can get useful feedbacks
from various perspectives.
* Team meeting:
The horizon team has a weekly meeting which covers all things related to
the horizon project like announcements, project priorities, community goals,
bugs and so on.
There is the "On Demand Agenda" section at the end of the meeting, where
anyone can add a topic to discuss with the team. It is suggested to add
such topic to the On-Demand agenda in the "Weekly meeting" in
`horizon release priority etherpad
<https://etherpad.opendev.org/p/horizon-release-priorities>`__.
* Time: http://eavesdrop.openstack.org/#Horizon_Team_Meeting
* Agenda: https://wiki.openstack.org/wiki/Meetings/Horizon
Contacting the Core Team
------------------------
The list of the current core reviewers is found at
`gerrit <https://review.opendev.org/#/admin/groups/43,members>`__.
Most core reviewers are online in the IRC channel and
you can contact them there.
New Feature Planning
--------------------
If you would like to add a new feature to horizon, file a blueprint
to https://blueprints.launchpad.net/horizon. You can find a template for a
blueprint at https://blueprints.launchpad.net/horizon/+spec/template.
The template is not a strict requirement but it would be nice to cover
a motivation and an approach of your blueprint. From the nature of GUI,
a discussion on UI design during a patch review could be more productive,
so there is no need to explain the detail of UI design in your blueprint
proposal.
We don't have a specific deadline during a development cycle. You can propose a
feature any time. Only thing you keep in your mind is that we do not merge
features during the feature freeze period after the milestone 3 in each cycle.
There are a number of unsupported OpenStack features in horizon.
Implementing such would be appreciated even if it is small.
Task Tracking
-------------
We track our tasks in `Launchpad <https://bugs.launchpad.net/horizon>`__.
If you're looking for some smaller, please look through the list of bugs
and find what you think you can work on. If you are not sure the status of
a bug feel free to ask to the horizon team. We can help you.
Note that we recently do not maintain 'low-hanging-fruit' tag and some of
them with this tag are not simple enough.
Reporting a Bug
--------------- ---------------
We'll start by assuming you've got a working checkout of the repository (if You found an issue and want to make sure we are aware of it?
not then please see the :ref:`quickstart`). You can do so on `Launchpad <https://bugs.launchpad.net/horizon>`__.
Second, you'll need to take care of a couple administrative tasks: Please file a bug first even if you already have a fix for it.
If you can reproduce the bug reliably and identify its cause
then it's usually safe to start working on it.
However, getting independent confirmation (and verifying that it's not a
duplicate) is always a good idea if you can be patient.
#. Create an account on Launchpad. Getting Your Patch Merged
#. Sign the `OpenStack Contributor License Agreement`_ and follow the associated -------------------------
instructions to verify your signature.
#. Join the `Horizon Developers`_ team on Launchpad.
#. Follow the `instructions for setting up git-review`_ in your
development environment.
Whew! Got all that? Okay! You're good to go. All changes proposed to horizon require two +2 votes from the horizon core
reviewers before one of the core reviewers can approve a change by giving
"Workflow +1" vote.
.. _`OpenStack Contributor License Agreement`: https://wiki.openstack.org/CLA In general, all changes should be proposed along with at least unit test
.. _`Horizon Developers`: https://launchpad.net/~horizon coverage (python or JavaScript). Integration test support would be
.. _`instructions for setting up git-review`: https://docs.openstack.org/infra/manual/developers.html#development-workflow appreciated.
Ways To Contribute More detailed guidelines for reviewers of patches are available at
------------------ `OpenDev Developer's Guide <https://docs.opendev.org/opendev/infra-manual/latest/developers.html#code-review>`__.
The easiest way to get started with Horizon's code is to pick a bug on Project Team Lead Duties
Launchpad that interests you, and start working on that. Bugs tagged as ------------------------
``low-hanging-fruit`` are a good place to start. Alternatively, if there's an
OpenStack API feature you would like to see implemented in Horizon feel free
to try building it.
If those are too big, there are lots of great ways to get involved without All common PTL duties are enumerated in the `PTL guide
plunging in head-first: <https://docs.openstack.org/project-team-guide/ptl.html>`_.
* Report bugs, triage new tickets, and review old tickets on The horizon PTL is expected to coordinate and encourage the core reviewer team
the `bug tracker`_. and contributors for the success. The expectations for the core reviewer team
* Propose ideas for improvements via `Launchpad Blueprints`_, via the is documented at :doc:`policies/core-reviewers` and the PTL would play an
mailing list on the project page, or on IRC. important role in this.
* Write documentation!
* Write unit tests for untested code!
* Help improve the `User Experience Design`_ or contribute to the
`Persona Working Group`_.
.. _`bug tracker`: https://bugs.launchpad.net/horizon
.. _`Launchpad Blueprints`: https://blueprints.launchpad.net/horizon
.. _`User Experience Design`: https://wiki.openstack.org/wiki/UX#Getting_Started
.. _`Persona Working Group`: https://wiki.openstack.org/wiki/Personas
Choosing Issues To Work On
--------------------------
In general, if you want to write code, there are three cases for issues
you might want to work on:
#. Confirmed bugs
#. Approved blueprints (features)
#. New bugs you've discovered
If you have an idea for a new feature that isn't in a blueprint yet, it's
a good idea to write the blueprint first, so you don't end up writing a bunch
of code that may not go in the direction the community wants.
For bugs, open the bug first, but if you can reproduce the bug reliably and
identify its cause then it's usually safe to start working on it. However,
getting independent confirmation (and verifying that it's not a duplicate)
is always a good idea if you can be patient.
After You Write Your Patch
--------------------------
Once you've made your changes, there are a few things to do:
* Make sure the unit tests and linting tasks pass by running ``tox``
* Take a look at your patch in API profiler, i.e. how it impacts the
performance. See :doc:`topics/profiling`.
* Make sure your code is ready for translation: See :ref:`pseudo_translation`.
* Make sure your code is up-to-date with the latest master:
``git pull --rebase``
* Finally, run ``git review`` to upload your changes to Gerrit for review.
The Horizon core developers will be notified of the new review and will examine
it in a timely fashion, either offering feedback or approving it to be merged.
If the review is approved, it is sent to Jenkins to verify the unit tests pass
and it can be merged cleanly. Once Jenkins approves it, the change will be
merged to the master repository and it's time to celebrate!
Etiquette Etiquette
========= ---------
The community's guidelines for etiquette are fairly simple: The community's guidelines for etiquette are fairly simple:

View File

@ -6,10 +6,10 @@
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2
contributing
intro intro
policies/index policies/index
quickstart quickstart
contributing
testing testing
tutorials/index tutorials/index
topics/index topics/index

View File

@ -2,14 +2,14 @@
Core Reviewer Team Core Reviewer Team
================== ==================
The Horizon Core Reviewer Team is responsible for many aspects of the The horizon core reviewer team is responsible for many aspects of the
Horizon project. These include, but are not limited to: horizon project. These include, but are not limited to:
- Mentor community contributors in solution design, testing, and the - Mentor community contributors in solution design, testing, and the
review process review process
- Actively reviewing patch submissions, considering whether the patch: - Actively reviewing patch submissions, considering whether the patch:
- is functional - is functional
- fits the use-cases and vision of the project - fits use cases and vision of the project
- is complete in terms of testing, documentation, and release notes - is complete in terms of testing, documentation, and release notes
- takes into consideration upgrade concerns from previous versions - takes into consideration upgrade concerns from previous versions
- Assist in bug triage and delivery of bug fixes - Assist in bug triage and delivery of bug fixes
@ -19,15 +19,15 @@ Horizon project. These include, but are not limited to:
features are added features are added
- Answering questions and participating in mailing list discussions - Answering questions and participating in mailing list discussions
- Interfacing with other OpenStack teams - Interfacing with other OpenStack teams
- Helping horizon plugin maintenances
In essence, core reviewers share the following common ideals: In essence, core reviewers share the following common ideals:
- They share responsibility in the project's success in its mission. - They share responsibility in the project's success in its mission.
- They value a healthy, vibrant, and active developer and user community. - They value a healthy, vibrant, and active developer and user community.
- They have made a long-term, recurring time investment to improve the project. - They have made a long-term, recurring time investment to improve the project.
- They spend their time doing what needs to be done to ensure the - They spend their time doing what needs to be done to ensure the project's
project's success, not necessarily what is the most interesting or success, not necessarily what is the most interesting or fun.
fun.
- A core reviewer's responsibility doesn't end with merging code. - A core reviewer's responsibility doesn't end with merging code.
Core Reviewer Expectations Core Reviewer Expectations
@ -37,18 +37,16 @@ Members of the core reviewer team are expected to:
- Attend and participate in the weekly IRC meetings (if your timezone allows) - Attend and participate in the weekly IRC meetings (if your timezone allows)
- Monitor and participate in-channel at #openstack-horizon - Monitor and participate in-channel at #openstack-horizon
- Monitor and participate in [Horizon] discussions on the mailing list - Monitor and participate in ``[horizon]`` discussions on the mailing list
- Participate in related design summit sessions at the OpenStack - Participate in related design sessions at Project Team Gatherings (PTGs)
Summits and Project Team Gatherings
- Review patch submissions actively and consistently - Review patch submissions actively and consistently
Please note in-person attendance at design summits, mid-cycles, and Please note in-person attendance at PTGs, mid-cycles, and other code sprints is
other code sprints is not a requirement to be a core reviewer. not a requirement to be a core reviewer. Participation can also include
Participation can also include contributing to the design documents contributing to the design documents discussed at the design sessions.
discussed at the design sessions.
Active and consistent review of review activity, bug triage and other Active and consistent review of review activity, bug triage and other activity
activity will be performed monthly and fed back to the Core Reviewer Team will be performed periodically and fed back to the core reviewer team
so everyone knows how things are progressing. so everyone knows how things are progressing.
Code Merge Responsibilities Code Merge Responsibilities
@ -63,3 +61,16 @@ testing, upgrade impacts and interactions with other projects. It also
means you pay attention to release milestones and understand if a means you pay attention to release milestones and understand if a
patch you are merging is marked for the release, especially critical patch you are merging is marked for the release, especially critical
during the feature freeze. during the feature freeze.
Horizon Plugin Maintenance
--------------------------
GUI supports for most OpenStack projects are achieved via horizon plugins.
The horizon core reviewer team has responsibility to help horizon plugin teams
from the perspective of horizon related changes as the framework,
for example, Django version bump, testing improvements, plugin interface
changes in horizon and so on. A member of the team is expected to send and
review patches related to such changes.
Note that involvements in more works in horizon plugins are up to individuals
but it would be nice to be involved if you have time :)