Contributing
To see what’s planned see the Molecule Project Board.
Join the Molecule community working group if you would like to influence the direction of the project.
Talk to us
Join us in #ansible-molecule
on libera.chat irc, or
molecule-users Forum.
The full list of Ansible email lists and IRC channels can be found in the communication page.
Guidelines
We are interested in various different kinds of improvement for Molecule; please feel free to raise an Issue if you would like to work on something major to ensure efficient collaboration and avoid duplicate effort.
Create a topic branch from where you want to base your work.
Make sure you have added tests for your changes.
Although not required, it is good to sign off commits using
git commit --signoff
, and agree that usage of--signoff
constitutes agreement with the terms of DCO 1.1.Run all the tests to ensure nothing else was accidentally broken.
Reformat the code by following the formatting section below.
Submit a pull request.
Code Of Conduct
Please see our Code of Conduct document.
Pull Request Life Cycle and Governance
If your PRs get stuck join us on IRC or add to the working group agenda.
The code style is what is enforced by CI, everything else is off-topic.
All PRs must be reviewed by one other person. This is enforced by GitHub. Larger changes require +2.
Testing
Molecule has an extensive set of unit and functional tests. Molecule uses Tox factors to generate a matrix of python x Ansible x unit/functional tests. Manual setup required as of this time.
Dependencies
Tests will be skipped when the driver’s binary is not present.
Install the test framework Tox.
$ python3 -m pip install tox
Full
Run all tests, including linting and coverage reports. This should be run prior to merging or submitting a pull request.
$ tox
List available scenarios
List all available scenarios. This is useful to target specific Python and Ansible version for the functional and unit tests.
$ tox -av
Unit
Run all unit tests with coverage.
$ tox -e 'py{27,35,36,37,38}-unit'
Run all unit tests for a specific version of Python .
$ tox -e py37-unit
Linting
Linting is performed by a combination of linters.
Run all the linters (some perform changes to conform the code to the style rules).
$ tox -e lint
Documentation
Generate the documentation, using sphinx.
$ tox -e docs
Documentation
Working with InterSphinx
In the conf.py, we define an intersphinx_mapping
which provides the base
URLs for conveniently linking to other Sphinx documented projects. In order to
find the correct link syntax and text you can link to, you can quickly inspect
the reference from the command line.
For example, if we would like to link to a specific part of the Ansible documentation, we could first run the following command:
python -m sphinx.ext.intersphinx https://docs.ansible.com/ansible/latest/objects.inv
And then see the entire Sphinx listing. We see entries that look like:
py:attribute
AnsibleModule._debug api/index.html#AnsibleModule._debug
With which we can link out to using the following syntax:
:py:attribute:`AnsibleModule._debug`
Credits
Based on the good work of John Dewey (@retr0h) and other contributors. Active member list can be seen at Molecule working group.