[doc] Refactor contributor documentation
For a while we are having a contradicting sections for contributor documentation, which makes it unobvious on where to start and what documentation is relevant. Patch reduces amount of pages by merging some of repeating content together. Distributions page is removed from the contributor docs, as they are described in different pages throughout the documentation. Change-Id: I716e80ff20b45a6c5df31b994330524a42a33ae8 Signed-off-by: Dmitriy Rabotyagov <dmitriy.rabotyagov@cleura.com>
This commit is contained in:
Dmitriy Rabotyagov
committed by
Dmitriy Rabotyagov
Dmitriy Rabotyagov
parent
c4a45d2fe3
commit
29ed1fe370
@@ -1,6 +1,6 @@
|
||||
==============================
|
||||
OpenStack-Ansible Bug Handling
|
||||
==============================
|
||||
============
|
||||
Bug Handling
|
||||
============
|
||||
|
||||
.. _bug_reporting:
|
||||
|
||||
@@ -28,18 +28,21 @@ criteria are met:
|
||||
|
||||
Bug Tags
|
||||
^^^^^^^^
|
||||
|
||||
If the reported needs fixing in a branch in addition to master, add a
|
||||
'\<release\>-backport-potential' tag (e.g. ``liberty-backport-potential``).
|
||||
There are predefined tags that will auto-complete.
|
||||
|
||||
Status
|
||||
^^^^^^
|
||||
|
||||
Please leave the **status** of an issue alone until someone confirms it or
|
||||
a member of the bugs team triages it. While waiting for the issue to be
|
||||
confirmed or triaged the status should remain as **New**.
|
||||
|
||||
Importance
|
||||
^^^^^^^^^^
|
||||
|
||||
Should only be touched if it is a Blocker/Gating issue. If it is, please
|
||||
set to **High**, and only use **Critical** if you have found a bug that
|
||||
can take down whole infrastructures. Once the importance has been changed
|
||||
@@ -61,7 +64,7 @@ prioritised. Triage should help ensure we appropriately manage all
|
||||
reported issues - bugs as well as improvements and feature requests."
|
||||
(Source: `Moodle bug triage`_)
|
||||
|
||||
.. _Moodle bug triage: https://docs.moodle.org/dev/Bug_triage
|
||||
.. _Moodle bug triage: https://moodledev.io/general/development/process/triage
|
||||
|
||||
Reported bugs need confirmation, prioritization, and ensure they do not
|
||||
go stale. If you care about OpenStack stability but are not wanting to
|
||||
|
||||
@@ -4,6 +4,52 @@
|
||||
Code rules
|
||||
==========
|
||||
|
||||
Project repositories
|
||||
====================
|
||||
|
||||
The OpenStack-Ansible project has different kinds of git repositories,
|
||||
each of them with specific use cases, and different sets of practices.
|
||||
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
|
||||
* - Repository type or name
|
||||
- Code location
|
||||
- Repository purpose
|
||||
* - | **OpenStack-Ansible**
|
||||
| Also called *integrated repository*
|
||||
- * https://opendev.org/openstack/openstack-ansible
|
||||
- Our main repository, used by deployers.
|
||||
Uses the other repositories.
|
||||
* - | The **OpenStack-Ansible roles** repositories
|
||||
- * https://opendev.org/openstack/openstack-ansible-os_nova
|
||||
* https://opendev.org/openstack/openstack-ansible-os_glance
|
||||
* https://opendev.org/openstack/ansible-role-systemd_mount
|
||||
* https://opendev.org/openstack/ansible-config_template
|
||||
* https://opendev.org/openstack/ansible-hardening
|
||||
* ...
|
||||
- Each role is in charge of deploying **exactly one**
|
||||
component of an OpenStack-Ansible deployment.
|
||||
* - | The **specs** repository
|
||||
- * https://opendev.org/openstack/openstack-ansible-specs
|
||||
- This repository contains all the information concerning
|
||||
large bodies of work done in OpenStack-Ansible,
|
||||
split by cycle.
|
||||
* - | The **ops** repository
|
||||
- * https://opendev.org/openstack/openstack-ansible-ops
|
||||
- This repository is an incubator for new projects, each project
|
||||
solving a particular operational problem. Each project has its
|
||||
own folder in this repository.
|
||||
* - | External repositories
|
||||
- * https://github.com/ceph/ceph-ansible
|
||||
* https://github.com/logan2211/ansible-resolvconf
|
||||
* https://github.com/evrardjp/ansible-keepalived
|
||||
* ...
|
||||
- OpenStack-Ansible is not re-inventing the wheel, and tries to
|
||||
reuse as much as possible existing roles. A bugfix for one of
|
||||
those repositories must be handled to these repositories'
|
||||
maintainers.
|
||||
|
||||
.. _codeguidelines:
|
||||
|
||||
General Guidelines for Submitting Code
|
||||
@@ -170,10 +216,47 @@ submitted with patches:
|
||||
section. Note that if a variable has been removed entirely then it has not
|
||||
been deprecated and the removal should be noted in the ``upgrade`` section.
|
||||
|
||||
.. _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
|
||||
|
||||
.. _newfeatures:
|
||||
|
||||
Working on new features
|
||||
=======================
|
||||
|
||||
.. _specs:
|
||||
|
||||
Submitting a specification
|
||||
==========================
|
||||
--------------------------
|
||||
|
||||
By proposing a draft spec you can help the OpenStack-Ansible
|
||||
community keep track of what roles or large changes are being developed,
|
||||
@@ -189,6 +272,97 @@ name folder. Rename and edit it for your needs.
|
||||
|
||||
.. _specification template: https://opendev.org/openstack/openstack-ansible-specs/src/specs/templates/template.rst
|
||||
|
||||
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:
|
||||
|
||||
* 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, python_venv_build, rabbitmq_server,
|
||||
systemd_service, openstack.osa.db_setup**)
|
||||
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.
|
||||
#. 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
|
||||
|
||||
.. _Ansible Style Guide:
|
||||
|
||||
Ansible Style Guide
|
||||
@@ -369,4 +543,4 @@ to simulate a multi-node build out as part of the testing infrastructure.
|
||||
Minimum supported distributions
|
||||
-------------------------------
|
||||
|
||||
See our :ref:`supported-distros` page.
|
||||
See our :ref:`compatibility-matrix` page.
|
||||
|
||||
@@ -1,235 +0,0 @@
|
||||
.. _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
|
||||
@@ -2,56 +2,82 @@
|
||||
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.
|
||||
* For contributing code and documentation, you must follow the
|
||||
OpenStack practices. Nothing special is required for OpenStack-Ansible.
|
||||
See also the `OpenStack developers getting started page`_
|
||||
and our :ref:`code rules <code_rules>` before hacking.
|
||||
|
||||
* For helping on or submitting bugs, you must have an account on
|
||||
Ubuntu Launchpad.
|
||||
All our repositories share the same `Launchpad project`_.
|
||||
Please check our :ref:`bug report <bug_reporting>` and
|
||||
:ref:`bug triage <bug_triage>` processes.
|
||||
Easy to fix bugs are marked with the tag *low hanging fruit*, and
|
||||
should be the target of first time contributors.
|
||||
|
||||
* For sharing your user experience, stories, and helping other users,
|
||||
please join us in our :ref:`IRC channel <irc>`.
|
||||
|
||||
* The OpenStack-Ansible project has recurring tasks that need
|
||||
attention, like releasing, or other code duties.
|
||||
See our page :ref:`Periodic work <periodicwork>`.
|
||||
|
||||
Below will cover the more project specific information you need to get started
|
||||
with OpenStack-Ansible.
|
||||
|
||||
.. _OpenStack developers getting started page: https://docs.openstack.org/infra/manual/developers.html#getting-started
|
||||
.. _Launchpad project: https://bugs.launchpad.net/openstack-ansible
|
||||
|
||||
Communication
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
.. _irc:
|
||||
|
||||
IRC channel
|
||||
^^^^^^^^^^^
|
||||
|
||||
.. warning::
|
||||
|
||||
The OpenStack Community moved the IRC network from Freenode to OFTC on May 31,
|
||||
2021. All the current IRC channels used in The OpenStack community are registered in OFTC
|
||||
network too.
|
||||
|
||||
The OpenStack-Ansible community communicates in the #openstack-ansible IRC
|
||||
channel hosted on OFTC. This channel is logged, and its logs are published
|
||||
on https://meetings.opendev.org/irclogs/%23openstack-ansible/
|
||||
The OpenStack-Ansible community communicates in the ``#openstack-ansible`` IRC
|
||||
channel hosted on `OFTC <https://www.oftc.net/>` network. This channel is logged, and its
|
||||
logs are published on https://meetings.opendev.org/irclogs/%23openstack-ansible/
|
||||
|
||||
Weekly meetings are held in our IRC channel. The schedule and
|
||||
logs can be found on
|
||||
https://meetings.opendev.org/%23OpenStack_Ansible_Deployment_Meeting
|
||||
|
||||
The agenda for the next meeting can be found on our
|
||||
`Meetings wiki page <https://wiki.openstack.org/wiki/Meetings/openstack-ansible>`_.
|
||||
|
||||
Matrix bridge
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
Matrix maintains a bridge connection to the OFTC IRC server. So you can use
|
||||
an `Element <https://element.io/>`_ or any other client compatible with Matrix
|
||||
protocol, to connect with the team.
|
||||
|
||||
To join the channel with Matrix, you will need to enter the room
|
||||
`#_oftc_#openstack-ansible:matrix.org <https://matrix.to/#/!eHBScvBFekcFIYVcYz:matrix.org>`_.
|
||||
|
||||
|
||||
Mailing lists
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
Members of the OpenStack-Ansible community should monitor the
|
||||
**OpenStack-discuss** `mailing lists`_.
|
||||
|
||||
.. _mailing lists: https://lists.openstack.org/mailman3/lists/
|
||||
.. _mailing lists: https://lists.openstack.org/mailman3/lists/openstack-discuss.lists.openstack.org/
|
||||
|
||||
All our communications should be prefixed with **[openstack-ansible]**.
|
||||
|
||||
Contacting the Core Team
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
All of our core team is available through IRC and present in #openstack-ansible
|
||||
All of our core team is available through IRC and present in ``#openstack-ansible``
|
||||
channel on OFTC. The list of the current members of the OpenStack-Ansible Team
|
||||
might be found on `gerrit`_.
|
||||
|
||||
.. _gerrit: https://review.opendev.org/#/admin/groups/490,members
|
||||
|
||||
|
||||
New Feature Planning
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
@@ -60,21 +86,60 @@ or infrastructure service, or to improve an existing role, the
|
||||
OpenStack-Ansible project would welcome that contribution and your assistance
|
||||
in maintaining it.
|
||||
|
||||
Please look through :dev_docs:`Contributor Guidelines <contributors/contribute.html>`
|
||||
page for more information about the process.
|
||||
Here are a few rules to get started:
|
||||
|
||||
Task Tracking
|
||||
~~~~~~~~~~~~~
|
||||
* 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.
|
||||
* Feel free to reach the Core Team via Mailing List or IRC to double-check
|
||||
details or ask question regarding a feature at any step. It can save you
|
||||
time and avoid unnecessary confusion in the future.
|
||||
|
||||
We track our tasks in Launchpad
|
||||
Please check :ref:`newfeatures` section for more detailed process.
|
||||
|
||||
.. _Working on Specifications and Blueprints: https://docs.openstack.org/infra/manual/developers.html#working-on-specifications-and-blueprints
|
||||
.. _Tempest: https://docs.openstack.org/tempest/
|
||||
|
||||
|
||||
Bug Tracking
|
||||
~~~~~~~~~~~~
|
||||
|
||||
We track our tasks and bugs in Launchpad
|
||||
|
||||
https://bugs.launchpad.net/openstack-ansible
|
||||
|
||||
If you're looking for some smaller, easier work item to pick up and get started
|
||||
on, search for the 'low-hanging-fruit' tag.
|
||||
on, search for the *low-hanging-fruit* tag.
|
||||
|
||||
|
||||
Reporting a Bug
|
||||
~~~~~~~~~~~~~~~
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
You found an issue and want to make sure we are aware of it? You can do so on
|
||||
`Launchpad
|
||||
@@ -83,13 +148,35 @@ You found an issue and want to make sure we are aware of it? You can do so on
|
||||
Also you may find more detailed information about how to work with bugs
|
||||
on the page :dev_docs:`Bug Handling <contributors/bugs.html>`.
|
||||
|
||||
.. _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
|
||||
|
||||
|
||||
.. _reviews:
|
||||
|
||||
Getting Your Patch Merged
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Any new code will be reviewed before merging into our repositories and
|
||||
requires at least 2 approvals from our Core team.
|
||||
Any new code will be reviewed by the project Core Team
|
||||
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.
|
||||
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`.
|
||||
|
||||
@@ -1,38 +0,0 @@
|
||||
====================
|
||||
Distribution support
|
||||
====================
|
||||
|
||||
.. _supported-distros:
|
||||
|
||||
Supported distributions
|
||||
=======================
|
||||
|
||||
The list of supported distributions can be found in the
|
||||
:ref:`compatibility-matrix`
|
||||
|
||||
Minimum requirements for OpenStack-Ansible roles
|
||||
================================================
|
||||
|
||||
Existing and new distributions are expected to meet the following requirements
|
||||
in order for them to be accepted in the individual OpenStack-Ansible roles:
|
||||
|
||||
* Pass functional tests
|
||||
|
||||
Graduation
|
||||
==========
|
||||
|
||||
For a distribution to be considered supported by the OpenStack-Ansible
|
||||
project, it has to meet the following minimum requirements:
|
||||
|
||||
* The necessary steps for bootstrapping the operating system have to be
|
||||
documented in the :deploy_guide:`Deployment Guide <index.html>`.
|
||||
* The integration repository contains at least one job which passes the
|
||||
Temptest testing framework.
|
||||
|
||||
Voting
|
||||
======
|
||||
|
||||
Distributions can be promoted to voting jobs on individual roles once they move
|
||||
to the `Graduation` phase and their stability has been confirmed by the core
|
||||
OpenStack-Ansible developers. Similar to this, voting can also be enabled in
|
||||
the integration repository for all the scenarios or a specific one.
|
||||
@@ -22,11 +22,9 @@ Contents:
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
project-onboarding
|
||||
contributing
|
||||
bugs
|
||||
contribute
|
||||
code-rules
|
||||
testing
|
||||
periodic-work
|
||||
core-reviewers
|
||||
distributions
|
||||
|
||||
@@ -1,118 +0,0 @@
|
||||
==================
|
||||
Project Onboarding
|
||||
==================
|
||||
|
||||
This document should help you understand how to contribute to
|
||||
OpenStack-Ansible.
|
||||
|
||||
Project repositories
|
||||
====================
|
||||
|
||||
The OpenStack-Ansible project has different kinds of git repositories,
|
||||
each of them with specific use cases, and different sets of practices.
|
||||
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
|
||||
* - Repository type or name
|
||||
- Code location
|
||||
- Repository purpose
|
||||
* - | **OpenStack-Ansible**
|
||||
| Also called *integrated repository*
|
||||
- * https://opendev.org/openstack/openstack-ansible
|
||||
- Our main repository, used by deployers.
|
||||
Uses the other repositories.
|
||||
* - | The **OpenStack-Ansible roles** repositories
|
||||
- * https://opendev.org/openstack/openstack-ansible-os_nova
|
||||
* https://opendev.org/openstack/openstack-ansible-os_glance
|
||||
* https://opendev.org/openstack/ansible-role-systemd_mount
|
||||
* https://opendev.org/openstack/ansible-config_template
|
||||
* https://opendev.org/openstack/ansible-hardening
|
||||
* ...
|
||||
- Each role is in charge of deploying **exactly one**
|
||||
component of an OpenStack-Ansible deployment.
|
||||
* - | The **specs** repository
|
||||
- * https://opendev.org/openstack/openstack-ansible-specs
|
||||
- This repository contains all the information concerning
|
||||
large bodies of work done in OpenStack-Ansible,
|
||||
split by cycle.
|
||||
* - | The **ops** repository
|
||||
- * https://opendev.org/openstack/openstack-ansible-ops
|
||||
- This repository is an incubator for new projects, each project
|
||||
solving a particular operational problem. Each project has its
|
||||
own folder in this repository.
|
||||
* - | External repositories
|
||||
- * https://github.com/ceph/ceph-ansible
|
||||
* https://github.com/logan2211/ansible-resolvconf
|
||||
* https://github.com/willshersystems/ansible-sshd
|
||||
* https://github.com/evrardjp/ansible-keepalived
|
||||
* ...
|
||||
- OpenStack-Ansible is not re-inventing the wheel, and tries to
|
||||
reuse as much as possible existing roles. A bugfix for one of
|
||||
those repositories must be handled to these repositories'
|
||||
maintainers.
|
||||
|
||||
How to contribute on code or issues
|
||||
===================================
|
||||
|
||||
* For contributing code and documentation, you must follow the
|
||||
OpenStack practices. Nothing special is required for OpenStack-Ansible.
|
||||
|
||||
See also the `OpenStack developers getting started page`_.
|
||||
and our :ref:`contributor guidelines<contributing>` before hacking.
|
||||
|
||||
* For helping on or submitting bugs, you must have an account on
|
||||
ubuntu Launchpad.
|
||||
All our repositories share the same `Launchpad project`_.
|
||||
|
||||
Please check our :ref:`bug report<bug_reporting>` and
|
||||
:ref:`bug triage<bug_triage>` processes.
|
||||
|
||||
Easy to fix bugs are marked with the tag *low hanging fruit*, and
|
||||
should be the target of first time contributors.
|
||||
|
||||
* For sharing your user experience, stories, and helping other users,
|
||||
please join us in our :ref:`IRC channel<irc>`.
|
||||
|
||||
* The OpenStack-Ansible project has recurring tasks that need
|
||||
attention, like releasing, or other code duties.
|
||||
See our page :ref:`Periodic work<periodicwork>`.
|
||||
|
||||
.. _OpenStack developers getting started page: https://docs.openstack.org/infra/manual/developers.html#getting-started
|
||||
.. _Launchpad project: https://bugs.launchpad.net/openstack-ansible
|
||||
|
||||
Community communication channels
|
||||
================================
|
||||
|
||||
.. _irc:
|
||||
|
||||
IRC channel
|
||||
^^^^^^^^^^^
|
||||
|
||||
.. warning::
|
||||
|
||||
The OpenStack Community moved the IRC network from Freenode to OFTC on May 31,
|
||||
2021. All the current IRC channels used in The OpenStack community are registered in OFTC
|
||||
network too.
|
||||
|
||||
The OpenStack-Ansible community communicates a lot through IRC, in
|
||||
the #openstack-ansible channel, on OFTC. This channel is
|
||||
logged, and its logs are published on
|
||||
https://meetings.opendev.org/irclogs/%23openstack-ansible/
|
||||
|
||||
Weekly meetings are held in our IRC channel. The schedule and
|
||||
logs can be found on
|
||||
https://meetings.opendev.org/%23OpenStack_Ansible_Deployment_Meeting
|
||||
|
||||
Next meeting agenda can be found on our
|
||||
`Meetings wiki page <https://wiki.openstack.org/wiki/Meetings/openstack-ansible>`_.
|
||||
|
||||
Mailing lists
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
A member of the OpenStack-Ansible community should monitor the
|
||||
**OpenStack-discuss** `mailing lists`_.
|
||||
|
||||
.. _mailing lists: https://lists.openstack.org/mailman3/lists/
|
||||
|
||||
All our communications should be prefixed with **[openstack-ansible]**.
|
||||
@@ -25,5 +25,4 @@ Support status for each OpenStack release can be found on `releases.openstack.or
|
||||
admin/index
|
||||
user/index
|
||||
reference/index
|
||||
contributors/contributing
|
||||
contributors/index
|
||||
|
||||
Reference in New Issue
Block a user