Bugs should be filed on Bug Launchpad for OpenStack-Ansible.
When submitting a bug, or working on a bug, please ensure the following criteria are met:
If it’s a bug that 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.
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.
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 the status should be changed to Triaged by someone other than the bug creator.
The triaging process is explained on the bug triage documentation page.
cherry-pick -x
. Here’s more
information on Submitting a change to a branch for review.Documentation is a critical part of ensuring that the deployers of OpenStack-Ansible are appropriately informed about:
To meet these needs developers must submit code comments, documentation and release notes with any code submissions. All forms of documentation should comply with the guidelines provided in the OpenStack Documentation Contributor Guide, with particular reference to the following sections:
Code comments for variables should be used to explain the purpose of the variable. This is particularly important for the role defaults file as the file is included verbatim in the role’s documentation. Where there is an optional variable, the variable and an explanation of what it is used for should be added to the defaults file.
Code comments for bash/python scripts should give guidance to the purpose of the code. This is important to provide context for reviewers before the patch has merged, and for later modifications to remind the contributors what the purpose was and why it was done that way.
OpenStack-Ansible has multiple forms of documentation with different intent.
Note
The statements below regarding the Install Guide and Role Documentation are statements of intent. The work to fulfill the intent is ongoing. Any new documentation submissions should try to help this intent where possible.
The Deployment Guide intends to help deployers deploy OpenStack-Ansible for the first time.
The role documentation (for example, the keystone role documentation) intends to explain all the options available for the role and how to implement more advanced requirements. To reduce duplication, the role documentation directly includes the role’s default variables file which includes the comments explaining the purpose of the variables. The long hand documentation for the roles should focus less on explaining variables and more on explaining how to implement advanced use cases.
Where possible the documentation in OpenStack-Ansible should steer clear of trying to explain OpenStack concepts. Those explanations belong in the OpenStack Manuals or service documentation and OpenStack-Ansible documentation should link to those documents when available, rather than duplicate their content.
Release notes are generated using the reno tool. Release notes must be written with the following guidelines in mind:
In most cases only the following sections should be used for new release notes submitted with patches:
features
: This should inform the deployer briefly about a new feature and
should describe how to use it either by referencing the variables to set or
by referring to documentation.issues
: This should inform the deployer about known issues. This may be
used when fixing an issue and wanting to inform deployers about a workaround
that can be used for versions prior to that which contains the patch that
fixes the issue. Issue notes should specifically make mention of what
versions of OpenStack-Ansible are affected by the issue.upgrade
: This should inform the deployer about changes which may affect
them when upgrading from a previous major or minor version. Typically, these
notes would describe changes to default variable values or variables that
have been removed.deprecations
: If a variable has been deprecated (ideally using the
deprecation filter), then it should be communicated through notes in this
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.When creating tasks and other roles for use in Ansible please create them using the YAML dictionary format.
Example YAML dictionary format:
- name: The name of the tasks
module_name:
thing1: "some-stuff"
thing2: "some-other-stuff"
tags:
- some-tag
- some-other-tag
Example what NOT to do:
- name: The name of the tasks
module_name: thing1="some-stuff" thing2="some-other-stuff"
tags: some-tag
- name: The name of the tasks
module_name: >
thing1="some-stuff"
thing2="some-other-stuff"
tags: some-tag
Usage of the “>” and “|” operators should be limited to Ansible conditionals
and command modules such as the Ansible shell
or command
.
Tags are assigned based on the relevance of each individual item.
Higher level includes (for example in the tasks/main.yml
) need high
level tags. For example, *-config
or *-install
.
Included tasks can have more detailed tags.
The following convention is used:
install
handles software installation tasks.
Running a playbook with --tags <role>-install
only deploys the
necessary software on the target, and will not configure it to your
needs or run any service.config
prepares the configuration of the
software (adapted to your needs), and all the components necessary
to run the service(s) configured in the role. Running a playbook with
--tags <role>-config
is only possible if the target already ran
the tags <role>-install
.upgrade
handles all the upgrade tasks.The variables files in a role are split in 3 locations:
The variables with lower priority should be in the defaults/main.yml. This allows their overriding with group variables or host variables. A good example for this are default database connection details, default queues connection details, or debug mode.
In other words, defaults/main.yml contains variables that are meant to be overridable by a deployer or a continuous integration system. These variables should be limited as much as possible, to avoid increasing the test matrix.
The vars/main.yml is always included. It contains generic variables that aren’t meant to be changed by a deployer. This includes for example static information that aren’t distribution specific (like aggregation of role internal variables for example).
The vars/<platform specific>.yml is the place where distribution specific content will be stored. For example, this file will hold the package names, repositories urls and keys, file paths, service names/init scripts.
On top of the normal cycle goals, a contributor can help the OpenStack-Ansible development team by performing one of the following recurring tasks:
Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.