Contributing to opstools-ansible

You can contribute bug fixes or enhancements to the opstools-ansible project by submitting a patch review via git review following the same process as described in submitting a patch. The required .gitreview file is already contained in the repository.

Conventions

When creating or modifying Ansible roles, please use YAML format for module arguments as in:

- debug:
    var: somevar

Instead of the legacy format:

- debug: var=somevar

We extract documentation automatically out of defaults/main.yml in each role. In order for this to work correctly, each variable in that file should be preceded by a comment with no intervening whitespace, and should be separated from other variables by one (or more) blank linkes, like this:

# This is some documentation.
some_variable: some value

# This is documentation for another_variable.
another_variable:
  - this
  - is
  - a
  - test

Running tests

To perform some simple YAML validations, run:

tox

You should do this before submitting pull requests. Arranging to run tox via your local Git pre-commit hook will save you the inconvenience of submitting a pull request only to have it rejected by our CI testing.

Updating the documentation

The role documentation in README.rst is generated automatically from (a) comments in the defaults/main.yml file for each role and (b) a README.rst included in each role.

After making changes, you can regenerate the documentation by running python setup.py build_sphinx in the top level of the repository.