236 lines
10 KiB
ReStructuredText
236 lines
10 KiB
ReStructuredText
.. _contributing:
|
|
|
|
======================
|
|
Contributor Guidelines
|
|
======================
|
|
|
|
Before submitting code
|
|
======================
|
|
|
|
Before jumping ahead and working on code, a series of steps should
|
|
be taken:
|
|
|
|
* Is there a bug for it? Can your track if someone else has seen
|
|
the same bug?
|
|
* Are you sure nobody is working on this problem at the moment?
|
|
Could there be a review pending fixing the same issue?
|
|
* Have you checked if your issue/feature request
|
|
hasn't been solved in another branch?
|
|
|
|
If you're willing to submit code, please remember the following rules:
|
|
|
|
* All code should match our
|
|
:ref:`codeguidelines`.
|
|
* All code requires to go through our :ref:`reviews`.
|
|
* Documentation should be provided with the
|
|
code directly. See also :ref:`documentation`.
|
|
* Fixing bugs and increasing test coverage have priority to new features.
|
|
See also the section :ref:`bugfixing`.
|
|
* New features are following a process, explained in the section
|
|
:ref:`newfeatures`.
|
|
New features are less likely to be :ref:`backported<backport>`
|
|
to previous branches.
|
|
|
|
.. _reviews:
|
|
|
|
Review process
|
|
==============
|
|
|
|
Any new code will be reviewed before merging into our repositories.
|
|
|
|
We follow openstack guidelines for the `code reviewing <https://docs.openstack.org/project-team-guide/review-the-openstack-way.html>`_ process.
|
|
|
|
Please be aware that any patch can be refused by the community if they
|
|
don't match the :ref:`codeguidelines`.
|
|
|
|
.. _bugfixing:
|
|
|
|
Working on bug fixes
|
|
====================
|
|
|
|
Any bug fix should have, in its commit message:
|
|
|
|
Closes-Bug: #bugnumber
|
|
|
|
or
|
|
|
|
Related-Bug: #bugnumber
|
|
|
|
where #bugnumber refers to a Launchpad issue.
|
|
|
|
See also the `working on bugs`_ section of the openstack documentation.
|
|
|
|
.. _working on bugs: https://docs.openstack.org/infra/manual/developers.html#working-on-bugs
|
|
|
|
.. _newfeatures:
|
|
|
|
Working on new features
|
|
=======================
|
|
|
|
If you would like to contribute towards a role to introduce an OpenStack
|
|
or infrastructure service, or to improve an existing role, the
|
|
OpenStack-Ansible project would welcome that contribution and your assistance
|
|
in maintaining it.
|
|
|
|
Here are a few rules to get started:
|
|
|
|
* All large feature additions/deletions should be accompanied by a
|
|
blueprint/spec. e.g. adding additional active agents to neutron,
|
|
developing a new service role, etc... See also
|
|
:ref:`specs`.
|
|
* Before creating blueprint/spec an associated 'Wishlist Bug' can be raised on
|
|
launchpad. This issue will be triaged and a determination will be made on
|
|
how large the change is and whether or not the change warrants a
|
|
blueprint/spec. Both features and bug fixes may require the creation of a
|
|
blueprint/spec. This requirement will be voted on by core reviewers and will
|
|
be based on the size and impact of the change.
|
|
* All blueprints/specs should be voted on and approved by core reviewers
|
|
before any associated code will be merged. For more information on
|
|
blueprints/specs please review the OpenStack documentation regarding
|
|
`Working on Specifications and Blueprints`_ and our own
|
|
:ref:`specs`.
|
|
* Once the blueprint work is completed the author(s) can request a backport
|
|
of the blueprint work into a stable branch. Each backport will be evaluated
|
|
on a case by case basis with cautious consideration based on how the
|
|
backport affects any existing deployments. See the
|
|
:ref:`backport` section for more information.
|
|
* Any new OpenStack services implemented which have `Tempest`_ tests
|
|
available must be implemented along with suitable functional tests enabled
|
|
as part of the feature development in order to ensure that any changes
|
|
to the code base do not break the service functionality.
|
|
* Feature additions must include documentation which provides reference to
|
|
OpenStack documentation about what the feature is and how it works. The
|
|
documentation should then describe how it is implemented in
|
|
OpenStack-Ansible and what configuration options there are.
|
|
See also the :ref:`documentation` section.
|
|
|
|
.. _Working on Specifications and Blueprints: https://docs.openstack.org/infra/manual/developers.html#working-on-specifications-and-blueprints
|
|
.. _Tempest: https://docs.openstack.org/tempest/
|
|
|
|
|
|
Example process to develop a new role
|
|
-------------------------------------
|
|
|
|
Here are the steps to write the role:
|
|
|
|
#. You can review roles which may be currently in development by checking our
|
|
`specs repository`_ and `unmerged specs`_ on review.openstack.org. If you
|
|
do not find a spec for the role, propose a blueprint/spec.
|
|
See also :ref:`specs`.
|
|
#. Create a source repository (e.g. on Github) to start your work on the Role.
|
|
#. Generate the reference directory structure for an Ansible role which is
|
|
the necessary subset of the documented `Best Practice`_. You might use
|
|
Ansible Galaxy tools to do this for you (e.g. ``ansible-galaxy init``).
|
|
You may additionally want to include directories such as ``docs`` and
|
|
``examples`` and ``tests`` for your role.
|
|
#. Generate a meta/main.yml right away. This file is important to Ansible to
|
|
ensure your dependent roles are installed and available and provides others
|
|
with the information they will need to understand the purpose of your role.
|
|
|
|
#. Develop task files for each of the install stages in turn, creating any
|
|
handlers and templates as needed. Ensure that you notify handlers after any
|
|
task which impacts the way the service would run (such as configuration
|
|
file modifications). Also take care that file ownership and permissions are
|
|
appropriate.
|
|
|
|
.. HINT:: Fill in variable defaults, libraries, and prerequisites as you
|
|
discover a need for them. You can also develop documentation for your
|
|
role at the same time.
|
|
|
|
#. Add tests to the role. See also our :ref:`tests` page.
|
|
#. Ensuring the role matches OpenStack-Ansible's latest standards.
|
|
See also our :ref:`code_rules` page.
|
|
#. Ensure the role converges:
|
|
|
|
* Implement **developer_mode** to build from a git source into
|
|
a Python virtual environment.
|
|
* Deploy the applicable configuration files in the right places.
|
|
* Ensure that the service starts.
|
|
|
|
The convergence may involve consuming other OpenStack-Ansible roles
|
|
(For example: **galera_server, galera_client, rabbitmq_server**)
|
|
in order to ensure that the appropriate infrastructure is in place.
|
|
Re-using existing roles in OpenStack-Ansible or Ansible Galaxy is
|
|
strongly encouraged.
|
|
#. Once the initial convergence is working and the services are running,
|
|
the role development should focus on implementing some level of
|
|
functional testing. See also :ref:`tempest-testing`.
|
|
#. Test the role on a new machine, using our provided scripts.
|
|
#. Submit your role for review.
|
|
#. If required, ask the OpenStack-Ansible PTL to import the github
|
|
role into the openstack-ansible namespace (This can only be done
|
|
early in the development cycle, and may be postponed to next
|
|
cycle).
|
|
#. If necessary, work on the integration within the
|
|
openstack-ansible integrated repository, and deploy
|
|
the role on an AIO. See also :ref:`integrate-new-role-with-aio`.
|
|
|
|
.. _specs repository: https://opendev.org/openstack/openstack-ansible-specs
|
|
.. _unmerged specs: https://review.opendev.org/#/q/status:+open+project:openstack/openstack-ansible-specs
|
|
.. _Best Practice: https://docs.ansible.com/ansible/playbooks_best_practices.html#directory-layout
|
|
|
|
Example process for adding a feature to an existing role
|
|
--------------------------------------------------------
|
|
|
|
#. Search for in the `OpenStack-Ansible Launchpad project`_ for
|
|
the feature request.
|
|
#. If no "Wishlist" item exist in Launchpad for your feature, create
|
|
a bug for it. Don't hesitate to ask if a spec is required in
|
|
the bug.
|
|
#. The :ref:`bug_triage` will classify if this new feature requires
|
|
a spec or not.
|
|
#. Work on the role files, following our :ref:`code_rules`.
|
|
#. Add an extra role test scenario, to ensure your code path is
|
|
tested and working.
|
|
#. Test your new scenario with a new machine.
|
|
See also the :ref:`devel_and_testing` page.
|
|
#. Submit your code for review, with its necessary documentation and
|
|
release notes.
|
|
|
|
.. _OpenStack-Ansible Launchpad project: https://bugs.launchpad.net/openstack-ansible
|
|
|
|
|
|
Example process to incubate a new "ops" project
|
|
-----------------------------------------------
|
|
|
|
A new project in "openstack-ansible-ops" can be started at any time,
|
|
with no constraint like writing a specification, or creating a bug.
|
|
|
|
Instead, the new code has to be isolated on a separate folder of the
|
|
`openstack-ansible-ops repo`_.
|
|
|
|
.. _openstack-ansible-ops repo: https://opendev.org/openstack/openstack-ansible-ops
|
|
|
|
|
|
.. _backport:
|
|
|
|
Backporting
|
|
===========
|
|
|
|
* Backporting is defined as the act of reproducing a change from another
|
|
branch. Unclean/squashed/modified cherry-picks and complete
|
|
reimplementations are OK.
|
|
* Backporting is often done by using the same code (via cherry picking), but
|
|
this is not always the case. This method is preferred when the cherry-pick
|
|
provides a complete solution for the targeted problem.
|
|
* When cherry-picking a commit from one branch to another the commit message
|
|
should be amended with any files that may have been in conflict while
|
|
performing the cherry-pick operation. Additionally, cherry-pick commit
|
|
messages should contain the original commit *SHA* near the bottom of the new
|
|
commit message. This can be done with ``cherry-pick -x``. Here's more
|
|
information on `Submitting a change to a branch for review`_.
|
|
* Every backport commit must still only solve one problem, as per the
|
|
guidelines in :ref:`codeguidelines`.
|
|
* If a backport is a squashed set of cherry-picked commits, the original SHAs
|
|
should be referenced in the commit message and the reason for squashing the
|
|
commits should be clearly explained.
|
|
* When a cherry-pick is modified in any way, the changes made and the reasons
|
|
for them must be explicitly expressed in the commit message.
|
|
* Refactoring work must not be backported to a "released" branch.
|
|
* Backport reviews should be done with due consideration to the effect of the
|
|
patch on any existing environment deployed by OpenStack-Ansible. The general
|
|
`OpenStack Guidelines for stable branches`_ can be used as a reference.
|
|
|
|
.. _Submitting a change to a branch for review: https://www.mediawiki.org/wiki/Gerrit/Advanced_usage#Submitting_a_change_to_a_branch_for_review_.28.22backporting.22.29
|
|
.. _OpenStack Guidelines for stable branches: https://docs.openstack.org/project-team-guide/stable-branches.html
|