Ussuri contrib docs community goal
This patch standardizes the CONTRIBUTING.rst file and adds the required doc/source/contributor/contributing.rst Task: 38514 Change-Id: I8a5d202f903e89e19106ccdda11fc30522892e7f
This commit is contained in:
Moisés Guimarães de Medeiros
parent
df194df816
commit
71bad5df06
203
doc/source/contributor/contributing.rst
Normal file
203
doc/source/contributor/contributing.rst
Normal file
@ -0,0 +1,203 @@
|
||||
Contributing to Barbican
|
||||
========================
|
||||
|
||||
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 Barbican project, which is responsible for the following OpenStack
|
||||
deliverables:
|
||||
|
||||
barbican
|
||||
| The OpenStack Key Manager service.
|
||||
| code: https://opendev.org/openstack/barbican
|
||||
| docs: https://docs.openstack.org/barbican
|
||||
| api-ref: https://docs.openstack.org/barbican/latest/api/index.html#api-reference
|
||||
| StoryBoard: https://storyboard.openstack.org/#!/project/openstack/barbican
|
||||
|
||||
barbican-ui
|
||||
| Horizon extension for the OpenStack Key Manager API.
|
||||
| code: https://opendev.org/openstack/barbican-ui
|
||||
| StoryBoard: https://storyboard.openstack.org/#!/project/openstack/barbican-ui
|
||||
|
||||
python-barbicanclient
|
||||
| Python client library for the OpenStack Key Manager API.
|
||||
| code: https://opendev.org/openstack/python-barbicanclient
|
||||
| docs: https://docs.openstack.org/python-barbicanclient
|
||||
| StoryBoard: https://storyboard.openstack.org/#!/project/openstack/python-barbicanclient
|
||||
|
||||
barbican-tempest-plugin
|
||||
| Additional Barbican tempest-based tests beyond those in the
|
||||
main OpenStack Integration Test Suite (tempest).
|
||||
| code: https://opendev.org/openstack/barbican-tempest-plugin
|
||||
| StoryBoard: https://storyboard.openstack.org/#!/project/openstack/barbican-tempest-plugin
|
||||
|
||||
ansible-role-lunasa-hsm
|
||||
| Ansible role to manage Luna SA Hardware Security Module (HSM) client software
|
||||
| code: https://opendev.org/openstack/ansible-role-lunasa-hsm
|
||||
| StoryBoard: https://storyboard.openstack.org/#!/project/openstack/ansible-role-lunasa-hsm
|
||||
|
||||
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 Barbican project may be found in the
|
||||
``#openstack-barbican`` 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-barbican/
|
||||
|
||||
weekly meeting
|
||||
Tuesdays at 13:00 UTC in ``#openstack-barbican`` on Freenode.
|
||||
Meetings are logged: http://eavesdrop.openstack.org/meetings/barbican/
|
||||
|
||||
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/#Barbican_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 ``[barbican]`` 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
|
||||
|
||||
meet-ups
|
||||
The Barbican 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 barbican-core team is an active group of contributors who are responsible
|
||||
for directing and maintaining the Barbican project. As a new contributor, your
|
||||
interaction with this group will be mostly through code reviews, because
|
||||
only members of barbican-core can approve a code change to be merged into the
|
||||
code repository.
|
||||
|
||||
.. note::
|
||||
Although your contribution will require reviews by members of
|
||||
barbican-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 barbican-core is maintained in gerrit:
|
||||
https://review.opendev.org/#/admin/groups/178,members
|
||||
|
||||
New Feature Planning
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The Barbican project uses both "specs" and "blueprints" to track new features.
|
||||
Here's a quick rundown of what they are and how the Barbican project uses them.
|
||||
|
||||
specs
|
||||
| Exist in the barbican-specs repository.
|
||||
Each spec must have a story in StoryBoard associated with it for tracking
|
||||
purposes.
|
||||
|
||||
| A spec is required for any new Barbican core feature, anything that
|
||||
changes the Key Manager API, or anything that entails a mass change
|
||||
to the existing codebase.
|
||||
|
||||
| The specs repository is: https://opendev.org/openstack/barbican-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/barbican-specs/
|
||||
|
||||
blueprints
|
||||
| Exist in StoryBoard, where they can be targeted to release milestones.
|
||||
| You file one at https://storyboard.openstack.org/#!/project/openstack/barbican-specs
|
||||
|
||||
| Examples of changes that can be covered by a blueprint only are:
|
||||
|
||||
* adding a new backend; or
|
||||
* adding support for a defined capability that already exists in one or
|
||||
more existing backends.
|
||||
|
||||
Feel free to ask in ``#openstack-barbican`` 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 Barbican project observes the OpenStack-wide deadlines,
|
||||
for example, final release of non-client libraries (barbican), final
|
||||
release for client libraries (python-barbicanclient), 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 `StoryBoard
|
||||
<https://storyboard.openstack.org/#!/project_group/barbican>`_. See the top of
|
||||
the page for the URL of each Barbican 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 StoryBoard of the affected deliverable.
|
||||
|
||||
Getting Your Patch Merged
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The Barbican 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
|
||||
testing-barbican section of the Barbican Contributors Guide for a
|
||||
discussion of the kinds of testing we do with barbican.
|
||||
|
||||
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 release-notes section of the
|
||||
Barbican 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 Barbican recently in Stackalytics:
|
||||
https://www.stackalytics.com/report/activity?module=barbican-group
|
||||
|
||||
Project Team Lead Duties
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
All common PTL duties are enumerated in the `PTL guide
|
||||
<https://docs.openstack.org/project-team-guide/ptl.html>`_.
|
||||
@ -21,6 +21,7 @@ When you're ready to dive deeper in to barbican take a look at:
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
contributing.rst
|
||||
getting_involved.rst
|
||||
architecture.rst
|
||||
structure.rst
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user