Browse Source

[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
changes/60/747060/1
Akihiro Motoki 1 year ago
parent
commit
e0afd0d21d
  1. 23
      CONTRIBUTING.rst
  2. 185
      doc/source/contributor/contributing.rst
  3. 2
      doc/source/contributor/index.rst
  4. 41
      doc/source/contributor/policies/core-reviewers.rst

23
CONTRIBUTING.rst

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

185
doc/source/contributor/contributing.rst

@ -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
open source works!
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.
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
* 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
* 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:
We'll start by assuming you've got a working checkout of the repository (if
not then please see the :ref:`quickstart`).
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.
Second, you'll need to take care of a couple administrative tasks:
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>`__.
#. Create an account on Launchpad.
#. 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.
* Time: http://eavesdrop.openstack.org/#Horizon_Team_Meeting
* Agenda: https://wiki.openstack.org/wiki/Meetings/Horizon
Whew! Got all that? Okay! You're good to go.
Contacting the Core Team
------------------------
.. _`OpenStack Contributor License Agreement`: https://wiki.openstack.org/CLA
.. _`Horizon Developers`: https://launchpad.net/~horizon
.. _`instructions for setting up git-review`: https://docs.openstack.org/infra/manual/developers.html#development-workflow
The list of the current core reviewers is found at
`gerrit <https://review.opendev.org/#/admin/groups/43,members>`__.
Ways To Contribute
------------------
Most core reviewers are online in the IRC channel and
you can contact them there.
The easiest way to get started with Horizon's code is to pick a bug on
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.
New Feature Planning
--------------------
If those are too big, there are lots of great ways to get involved without
plunging in head-first:
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.
* Report bugs, triage new tickets, and review old tickets on
the `bug tracker`_.
* Propose ideas for improvements via `Launchpad Blueprints`_, via the
mailing list on the project page, or on IRC.
* Write documentation!
* Write unit tests for untested code!
* Help improve the `User Experience Design`_ or contribute to the
`Persona Working Group`_.
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.
.. _`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
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
---------------
Choosing Issues To Work On
--------------------------
You found an issue and want to make sure we are aware of it?
You can do so on `Launchpad <https://bugs.launchpad.net/horizon>`__.
In general, if you want to write code, there are three cases for issues
you might want to work on:
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.
#. Confirmed bugs
#. Approved blueprints (features)
#. New bugs you've discovered
Getting Your Patch Merged
-------------------------
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.
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.
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.
In general, all changes should be proposed along with at least unit test
coverage (python or JavaScript). Integration test support would be
appreciated.
After You Write Your Patch
--------------------------
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>`__.
Once you've made your changes, there are a few things to do:
Project Team Lead Duties
------------------------
* 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.
All common PTL duties are enumerated in the `PTL guide
<https://docs.openstack.org/project-team-guide/ptl.html>`_.
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!
The horizon PTL is expected to coordinate and encourage the core reviewer team
and contributors for the success. The expectations for the core reviewer team
is documented at :doc:`policies/core-reviewers` and the PTL would play an
important role in this.
Etiquette
=========
---------
The community's guidelines for etiquette are fairly simple:

2
doc/source/contributor/index.rst

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

41
doc/source/contributor/policies/core-reviewers.rst

@ -2,14 +2,14 @@
Core Reviewer Team
==================
The Horizon Core Reviewer Team is responsible for many aspects of the
Horizon project. These include, but are not limited to:
The horizon core reviewer team is responsible for many aspects of the
horizon project. These include, but are not limited to:
- Mentor community contributors in solution design, testing, and the
review process
- Actively reviewing patch submissions, considering whether the patch:
- 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
- takes into consideration upgrade concerns from previous versions
- 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
- Answering questions and participating in mailing list discussions
- Interfacing with other OpenStack teams
- Helping horizon plugin maintenances
In essence, core reviewers share the following common ideals:
- They share responsibility in the project's success in its mission.
- 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 spend their time doing what needs to be done to ensure the
project's success, not necessarily what is the most interesting or
fun.
- They spend their time doing what needs to be done to ensure the project's
success, not necessarily what is the most interesting or fun.
- A core reviewer's responsibility doesn't end with merging code.
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)
- Monitor and participate in-channel at #openstack-horizon
- Monitor and participate in [Horizon] discussions on the mailing list
- Participate in related design summit sessions at the OpenStack
Summits and Project Team Gatherings
- Monitor and participate in ``[horizon]`` discussions on the mailing list
- Participate in related design sessions at Project Team Gatherings (PTGs)
- Review patch submissions actively and consistently
Please note in-person attendance at design summits, mid-cycles, and
other code sprints is not a requirement to be a core reviewer.
Participation can also include contributing to the design documents
discussed at the design sessions.
Please note in-person attendance at PTGs, mid-cycles, and other code sprints is
not a requirement to be a core reviewer. Participation can also include
contributing to the design documents discussed at the design sessions.
Active and consistent review of review activity, bug triage and other
activity will be performed monthly and fed back to the Core Reviewer Team
Active and consistent review of review activity, bug triage and other activity
will be performed periodically and fed back to the core reviewer team
so everyone knows how things are progressing.
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
patch you are merging is marked for the release, especially critical
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 :)

Loading…
Cancel
Save