[ English | español | Deutsch | Indonesia | русский | English (United Kingdom) ]
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 General Guidelines for Submitting Code.
All code requires to go through our Review process.
Documentation should be provided with the code directly. See also Documentation and Release Note Guidelines.
Fixing bugs and increasing test coverage have priority to new features. See also the section Working on bug fixes.
New features are following a process, explained in the section Working on new features. New features are less likely to be backported 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 General Guidelines for Submitting Code.
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 Submitting a specification.
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 Submitting a specification.
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 Backporting 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 and Release Note Guidelines section.
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 Submitting a specification.
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 asdocsandexamplesandtestsfor 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 Testing page.
Ensuring the role matches OpenStack-Ansible’s latest standards. See also our 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 Improve testing with tempest.
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 Testing a new role with an AIO.
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 Bug triage will classify if this new feature requires a spec or not.
Work on the role files, following our 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 Running tests locally page.
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 General Guidelines for Submitting Code.
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.
