openstack-ansible/doc/source/contributor/contribute.rst

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 codeguidelines.
• All code requires to go through our reviews.
• Documentation should be provided with the code directly. See also documentation.
• Fixing bugs and increasing test coverage have priority to new features. See also the section bugfixing.
• New features are following a process, explained in the section newfeatures. New features are less likely to be backported<backport> to previous branches.

Review process

Any new code will be reviewed before merging into our repositories.

We follow openstack guidelines for the code reviewing process.

Please be aware that any patch can be refused by the community if they don't match the codeguidelines.

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 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 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 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 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 documentation section.

Example process to develop a new role

Here are the steps to write the role:

1. 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 specs.

2. Create a source repository (e.g. on Github) to start your work on the Role.

3. 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.

4. 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.

5. 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.

6. Add tests to the role. See also our tests page.

7. Ensuring the role matches OpenStack-Ansible's latest standards. See also our code_rules page.

8. 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.

9. 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 tempest-testing.

10. Test the role on a new machine, using our provided scripts.

11. Submit your role for review.

12. 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).

13. If necessary, work on the integration within the openstack-ansible integrated repository, and deploy the role on an AIO. See also integrate-new-role-with-aio.

Example process for adding a feature to an existing role

1. Search for in the OpenStack-Ansible Launchpad project for the feature request.
2. 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.
3. The bug_triage will classify if this new feature requires a spec or not.
4. Work on the role files, following our code_rules.
5. Add an extra role test scenario, to ensure your code path is tested and working.
6. Test your new scenario with a new machine. See also the devel_and_testing page.
7. Submit your code for review, with its necessary documentation and release notes.

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.

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 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.