Update Monasca contribution documentation
Change-Id: I22f6686cbba3eaa884ee406c516c4f506cc61a9d Story: 2007236 Task: 38538
This commit is contained in:
Witek Bedyk
parent
e1fe4e1324
commit
5c55909003
19
CONTRIBUTING.rst
Normal file
19
CONTRIBUTING.rst
Normal file
@ -0,0 +1,19 @@
|
|||||||
|
The source repository for this project can be found at:
|
||||||
|
|
||||||
|
https://opendev.org/openstack/monasca-api.git
|
||||||
|
|
||||||
|
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 Storyboard:
|
||||||
|
|
||||||
|
https://storyboard.openstack.org/#!/project/863
|
||||||
|
|
||||||
|
For more specific information about contributing to this repository, see the
|
||||||
|
Monasca contributor guide:
|
||||||
|
|
||||||
|
https://docs.openstack.org/monasca-api/latest/contributor/contributing.html
|
||||||
203
doc/source/contributor/contributing.rst
Normal file
203
doc/source/contributor/contributing.rst
Normal file
@ -0,0 +1,203 @@
|
|||||||
|
============================
|
||||||
|
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 Monasca.
|
||||||
|
|
||||||
|
Communication
|
||||||
|
~~~~~~~~~~~~~
|
||||||
|
.. This would be a good place to put the channel you chat in as a project; when/
|
||||||
|
where your meeting is, the tags you prepend to your ML threads, etc.
|
||||||
|
|
||||||
|
For communicating with Monasca Team, you can reach out to us on
|
||||||
|
*#openstack-monasca* IRC channel at freenode.net.
|
||||||
|
|
||||||
|
We hold weekly `team meetings`_ in our IRC channel which is a good opportunity
|
||||||
|
to ask questions, propose new features or just get in touch with the team.
|
||||||
|
|
||||||
|
You can also send us an email to the mailing list
|
||||||
|
`openstack-discuss@lists.openstack.org`_. Please use *[Monasca]* tag for
|
||||||
|
easier thread filtering.
|
||||||
|
|
||||||
|
.. _team meetings: http://eavesdrop.openstack.org/#Monasca_Team_Meeting
|
||||||
|
.. _openstack-discuss@lists.openstack.org: http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-discuss
|
||||||
|
|
||||||
|
Contacting the Core Team
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
.. This section should list the core team, their irc nicks, emails, timezones
|
||||||
|
etc. If all this info is maintained elsewhere (i.e. a wiki), you can link to
|
||||||
|
that instead of enumerating everyone here.
|
||||||
|
|
||||||
|
================== ========== =====
|
||||||
|
Name IRC nick Email
|
||||||
|
================== ========== =====
|
||||||
|
Martin Chacon Piza chaconpiza MartinDavid.ChaconPiza1@est.fujitsu.com
|
||||||
|
Witek Bedyk witek witold.bedyk@suse.com
|
||||||
|
Doug Szumski dougsz doug@stackhpc.com
|
||||||
|
Adrian Czarnecki adriancz adrian.czarnecki@ts.fujitsu.com
|
||||||
|
Joseph Davis joadavis joseph.davis@suse.com
|
||||||
|
================== ========== =====
|
||||||
|
|
||||||
|
New Feature Planning
|
||||||
|
~~~~~~~~~~~~~~~~~~~~
|
||||||
|
.. This section is for talking about the process to get a new feature in. Some
|
||||||
|
projects use blueprints, some want specs, some want both! Some projects
|
||||||
|
stick to a strict schedule when selecting what new features will be reviewed
|
||||||
|
for a release.
|
||||||
|
|
||||||
|
Our process is meant to allow users, developers, and operators to express their
|
||||||
|
desires for new features using Storyboard stories. The workflow is very simple:
|
||||||
|
|
||||||
|
* If something is clearly broken, submit a `bug report`_ in Storyboard.
|
||||||
|
* If you want to change or add a feature, submit a `story`_ in Storyboard.
|
||||||
|
* Monasca core reviewers may request that you submit a `specification`_ to
|
||||||
|
gerrit to elaborate on the feature request.
|
||||||
|
* Significant features require `release notes`_ to be included when the code is
|
||||||
|
merged.
|
||||||
|
|
||||||
|
.. _story:
|
||||||
|
|
||||||
|
Stories
|
||||||
|
-------
|
||||||
|
|
||||||
|
New features can be proposed in `Storyboard
|
||||||
|
<https://storyboard.openstack.org/#!/project_group/59>`_ as new Story.
|
||||||
|
|
||||||
|
The initial story primarily needs to express the intent of the idea with
|
||||||
|
enough details that it can be evaluated for compatibility with the project
|
||||||
|
mission and whether or not the change requires a `specification`_. It is *not*
|
||||||
|
expected to contain all of the implementation details. If the feature is very
|
||||||
|
simple and well understood by the team, then describe it simply. The story is
|
||||||
|
then used to track all the related code reviews. Team members will
|
||||||
|
request more information as needed.
|
||||||
|
|
||||||
|
.. _specification:
|
||||||
|
|
||||||
|
Specifications
|
||||||
|
--------------
|
||||||
|
|
||||||
|
We use the `monasca-specs <https://github.com/openstack/monasca-specs>`_
|
||||||
|
repository for specification reviews. Specifications:
|
||||||
|
|
||||||
|
* Provide a review tool for collaborating on feedback and reviews for complex
|
||||||
|
features.
|
||||||
|
* Collect team priorities.
|
||||||
|
* Serve as the basis for documenting the feature once implemented.
|
||||||
|
* Ensure that the overall impact on the system is considered.
|
||||||
|
|
||||||
|
.. _release notes:
|
||||||
|
|
||||||
|
Release Notes
|
||||||
|
-------------
|
||||||
|
|
||||||
|
The release notes for a patch should be included in the patch. If not, the
|
||||||
|
release notes should be in a follow-on review.
|
||||||
|
|
||||||
|
If any of the following applies to the patch, a release note is required:
|
||||||
|
|
||||||
|
* The deployer needs to take an action when upgrading
|
||||||
|
* A new feature is implemented
|
||||||
|
* Plugin API function was removed or changed
|
||||||
|
* Current behavior is changed
|
||||||
|
* A new config option is added that the deployer should consider changing from
|
||||||
|
the default
|
||||||
|
* A security bug is fixed
|
||||||
|
* Change may break previous versions of the client library(ies)
|
||||||
|
* Requirement changes are introduced for important libraries like oslo, six
|
||||||
|
requests, etc.
|
||||||
|
* Deprecation period starts or code is purged
|
||||||
|
|
||||||
|
A release note is suggested if a long-standing or important bug is fixed.
|
||||||
|
Otherwise, a release note is not required.
|
||||||
|
|
||||||
|
Database Migrations
|
||||||
|
-------------------
|
||||||
|
|
||||||
|
Monasca uses `Alembic <http://alembic.zzzcomputing.com/en/latest/>`_
|
||||||
|
migrations to set up its configuration database. If you need to change the
|
||||||
|
configuration database's schema, you need to create a migration to adjust the
|
||||||
|
database accordingly, as follows::
|
||||||
|
|
||||||
|
cd monasca_api/db/
|
||||||
|
alembic revision
|
||||||
|
|
||||||
|
This will create a new skeleton revision for you to edit. You will find
|
||||||
|
existing revisions to use for inspiration in the
|
||||||
|
``/monasca_api/db/alembic/versions/`` directory.
|
||||||
|
|
||||||
|
Task Tracking
|
||||||
|
~~~~~~~~~~~~~
|
||||||
|
.. This section is about where you track tasks- launchpad? storyboard? is there
|
||||||
|
more than one launchpad project? what's the name of the project group in
|
||||||
|
storyboard?
|
||||||
|
|
||||||
|
We track our tasks in Storyboard
|
||||||
|
|
||||||
|
https://storyboard.openstack.org/#!/project_group/monasca
|
||||||
|
|
||||||
|
If you're looking for some smaller, easier work item to pick up and get started
|
||||||
|
on, search for the *'low-hanging-fruit'* tag.
|
||||||
|
|
||||||
|
Kanban Board
|
||||||
|
------------
|
||||||
|
|
||||||
|
Progress on implementation of important stories in Ussuri release is tracked in
|
||||||
|
`Monasca Board on StoryBoard <https://storyboard.openstack.org/#!/board/190>`_.
|
||||||
|
|
||||||
|
.. _bug report:
|
||||||
|
|
||||||
|
Reporting a Bug
|
||||||
|
~~~~~~~~~~~~~~~
|
||||||
|
.. Pretty self explanatory section, link directly to where people should report
|
||||||
|
bugs for your project.
|
||||||
|
|
||||||
|
You found an issue and want to make sure we are aware of it? You can `report
|
||||||
|
them on Storyboard <https://storyboard.openstack.org/#!/project_group/monasca>`_.
|
||||||
|
|
||||||
|
When filing a bug please remember to add the *bug* tag to the story. Please
|
||||||
|
provide information on what the problem is, how to replicate it, any
|
||||||
|
suggestions for fixing it, and a recommendation of the priority.
|
||||||
|
|
||||||
|
All open bugs can be found in this `Worklist
|
||||||
|
<https://storyboard.openstack.org/#!/worklist/213>`_.
|
||||||
|
|
||||||
|
Getting Your Patch Merged
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
.. This section should have info about what it takes to get something merged. Do
|
||||||
|
you require one or two +2's before +W? Do some of your repos require unit
|
||||||
|
test changes with all patches? etc.
|
||||||
|
|
||||||
|
All changes proposed to Monasca requires at least one ``Code-Review +2`` votes
|
||||||
|
from Monasca core reviewers before one of the core reviewers can approve
|
||||||
|
patch by giving ``Workflow +1`` vote.
|
||||||
|
|
||||||
|
Reviews Prioritisation
|
||||||
|
----------------------
|
||||||
|
|
||||||
|
Monasca project uses *Review-Priority* field in Gerrit to emphasize
|
||||||
|
prioritized code changes.
|
||||||
|
|
||||||
|
Every developer can propose the changes which should be prioritized
|
||||||
|
in `weekly team meeting <http://eavesdrop.openstack.org/#Monasca_Team_Meeting>`_
|
||||||
|
or in the mailing list. Any core reviewer,
|
||||||
|
preferably from a different company, can confirm such proposed change
|
||||||
|
by setting *Review-Priority* +1.
|
||||||
|
|
||||||
|
Prioritized changes can be listed in this
|
||||||
|
`dashboard <http://www.tinyurl.com/monasca>`_.
|
||||||
|
|
||||||
|
Project Team Lead Duties
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
.. this section is where you can put PTL specific duties not already listed in
|
||||||
|
the common PTL guide (linked below), or if you already have them written
|
||||||
|
up elsewhere you can link to that doc here.
|
||||||
|
|
||||||
|
All common PTL duties are enumerated in the `PTL guide
|
||||||
|
<https://docs.openstack.org/project-team-guide/ptl.html>`_.
|
||||||
@ -2,136 +2,8 @@
|
|||||||
Contribution documentation
|
Contribution documentation
|
||||||
==========================
|
==========================
|
||||||
|
|
||||||
Kanban Board
|
|
||||||
~~~~~~~~~~~~
|
|
||||||
|
|
||||||
Progress on implementation of important stories in Stein release is tracked in
|
|
||||||
`Monasca Board on StoryBoard <https://storyboard.openstack.org/#!/board/111>`_.
|
|
||||||
|
|
||||||
Reviews Prioritisation
|
|
||||||
~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
Monasca project uses *Review-Priority* field in Gerrit to emphasize
|
|
||||||
prioritized code changes.
|
|
||||||
|
|
||||||
Every developer can propose the changes which should be prioritized
|
|
||||||
in `weekly team meeting <http://eavesdrop.openstack.org/#Monasca_Team_Meeting>`_
|
|
||||||
or in the mailing list. Any core reviewer,
|
|
||||||
preferably from a different company, can confirm such proposed change
|
|
||||||
by setting *Review-Priority* +1.
|
|
||||||
|
|
||||||
Prioritized changes can be listed in this
|
|
||||||
`dashboard <http://www.tinyurl.com/monasca>`_.
|
|
||||||
|
|
||||||
Workflow
|
|
||||||
~~~~~~~~
|
|
||||||
|
|
||||||
Our process is meant to allow users, developers, and operators to express their
|
|
||||||
desires for new features using Storyboard stories. The workflow is very simple:
|
|
||||||
|
|
||||||
* If something is clearly broken, submit a `bug report`_ in Storyboard.
|
|
||||||
* If you want to change or add a feature, submit a `story`_ in Storyboard.
|
|
||||||
* Monasca core reviewers may request that you submit a `specification`_ to
|
|
||||||
gerrit to elaborate on the feature request.
|
|
||||||
* Significant features require `release notes`_ to be included when the code is
|
|
||||||
merged.
|
|
||||||
|
|
||||||
.. _bug report:
|
|
||||||
|
|
||||||
Bug Reports
|
|
||||||
-----------
|
|
||||||
|
|
||||||
All open bugs can be found in this `Worklist
|
|
||||||
<https://storyboard.openstack.org/#!/worklist/213>`_.
|
|
||||||
|
|
||||||
Bugs triaged in Stein release can be listed `here
|
|
||||||
<https://storyboard.openstack.org/#!/worklist/467>`_.
|
|
||||||
|
|
||||||
The progress of bug-fixing can be tracked in `this board
|
|
||||||
<https://storyboard.openstack.org/#!/board/114>`_.
|
|
||||||
|
|
||||||
When filing a bug please remember to add the *bug* tag to the story. Please
|
|
||||||
provide information on what the problem is, how to replicate it, any
|
|
||||||
suggestions for fixing it, and a recommendation of the priority.
|
|
||||||
|
|
||||||
.. _story:
|
|
||||||
|
|
||||||
Stories
|
|
||||||
-------
|
|
||||||
|
|
||||||
New features can be proposed in `Storyboard
|
|
||||||
<https://storyboard.openstack.org/#!/project_group/59>`_ as new Story.
|
|
||||||
|
|
||||||
The initial story primarily needs to express the intent of the idea with
|
|
||||||
enough details that it can be evaluated for compatibility with the project
|
|
||||||
mission and whether or not the change requires a `specification`_. It is *not*
|
|
||||||
expected to contain all of the implementation details. If the feature is very
|
|
||||||
simple and well understood by the team, then describe it simply. The story is
|
|
||||||
then used to track all the related code reviews. Team members will
|
|
||||||
request more information as needed.
|
|
||||||
|
|
||||||
.. _specification:
|
|
||||||
|
|
||||||
Specifications
|
|
||||||
--------------
|
|
||||||
|
|
||||||
We use the `monasca-specs <https://github.com/openstack/monasca-specs>`_
|
|
||||||
repository for specification reviews. Specifications:
|
|
||||||
|
|
||||||
* Provide a review tool for collaborating on feedback and reviews for complex
|
|
||||||
features.
|
|
||||||
* Collect team priorities.
|
|
||||||
* Serve as the basis for documenting the feature once implemented.
|
|
||||||
* Ensure that the overall impact on the system is considered.
|
|
||||||
|
|
||||||
.. _release notes:
|
|
||||||
|
|
||||||
Release Notes
|
|
||||||
-------------
|
|
||||||
|
|
||||||
The release notes for a patch should be included in the patch. If not, the
|
|
||||||
release notes should be in a follow-on review.
|
|
||||||
|
|
||||||
If any of the following applies to the patch, a release note is required:
|
|
||||||
|
|
||||||
* The deployer needs to take an action when upgrading
|
|
||||||
* A new feature is implemented
|
|
||||||
* Plugin API function was removed or changed
|
|
||||||
* Current behavior is changed
|
|
||||||
* A new config option is added that the deployer should consider changing from
|
|
||||||
the default
|
|
||||||
* A security bug is fixed
|
|
||||||
* Change may break previous versions of the client library(ies)
|
|
||||||
* Requirement changes are introduced for important libraries like oslo, six
|
|
||||||
requests, etc.
|
|
||||||
* Deprecation period starts or code is purged
|
|
||||||
|
|
||||||
A release note is suggested if a long-standing or important bug is fixed.
|
|
||||||
Otherwise, a release note is not required.
|
|
||||||
|
|
||||||
Database Migrations
|
|
||||||
-------------------
|
|
||||||
|
|
||||||
As of the Rocky release, Monasca uses `Alembic <http://alembic.zzzcomputing.com/en/latest/>`_
|
|
||||||
migrations to set up its configuration database. If you need to change the
|
|
||||||
configuration database's schema, you need to create a migration to adjust the
|
|
||||||
database accordingly, as follows::
|
|
||||||
|
|
||||||
cd monasca_api/db/
|
|
||||||
alembic revision
|
|
||||||
|
|
||||||
This will create a new skeleton revision for you to edit. You will find
|
|
||||||
existing revisions to use for inspiration in the
|
|
||||||
``/monasca_api/db/alembic/versions/`` directory.
|
|
||||||
|
|
||||||
Developer reference
|
|
||||||
-------------------
|
|
||||||
|
|
||||||
.. toctree::
|
.. toctree::
|
||||||
:maxdepth: 1
|
:maxdepth: 1
|
||||||
|
|
||||||
code
|
contributing.rst
|
||||||
|
code.rst
|
||||||
This documentation is generated by the Sphinx toolkit and lives in the source
|
|
||||||
tree. Additional documentation on Monasca and other components of OpenStack can
|
|
||||||
be found on the `OpenStack wiki <http://wiki.openstack.org>`_.
|
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user