Contributing to Ansible-lint¶
To contribute to ansible-lint, please use pull requests on a branch of your own fork.
After creating your fork on GitHub, you can do:
$ git clone email@example.com:yourname/ansible-lint $ cd ansible-lint $ git checkout -b your-branch-name # DO SOME CODING HERE $ git add your new files $ git commit -v $ git push origin your-branch-name
You will then be able to create a pull request from your commit.
All fixes to core functionality (i.e. anything except docs or examples) should be accompanied by tests that fail prior to your change and succeed afterwards.
Feel free to raise issues in the repo if you feel unable to contribute a code fix.
ansible-lint is flake8 compliant with
max-line-length set to 100
ansible-lint works only with supported Ansible versions at the time it was released.
Automated tests will be run against all PRs for flake8 compliance and Ansible compatibility — to check before pushing commits, just use tox.
Module dependency graph¶
Extra care should be taken when considering adding any dependency. Removing most dependencies on Ansible internals is desired as these can change without any warning.
$ pipdeptree -p ansible-lint ansible-lint==5.1.4.dev6 - enrich [required: >=1.2.6, installed: 1.2.6] - rich [required: >=9.5.1, installed: 10.7.0] - colorama [required: >=0.4.0,<0.5.0, installed: 0.4.4] - commonmark [required: >=0.9.0,<0.10.0, installed: 0.9.1] - pygments [required: >=2.6.0,<3.0.0, installed: 2.10.0] - packaging [required: Any, installed: 21.0] - pyparsing [required: >=2.0.2, installed: 2.4.7] - pyyaml [required: Any, installed: 5.4.1] - rich [required: >=9.5.1, installed: 10.7.0] - colorama [required: >=0.4.0,<0.5.0, installed: 0.4.4] - commonmark [required: >=0.9.0,<0.10.0, installed: 0.9.1] - pygments [required: >=2.6.0,<3.0.0, installed: 2.10.0] - ruamel.yaml [required: >=0.15.37,<1, installed: 0.17.11] - ruamel.yaml.clib [required: >=0.1.2, installed: 0.2.6] - tenacity [required: Any, installed: 8.0.1] - wcmatch [required: >=7.0, installed: 8.2] - bracex [required: >=2.1.1, installed: 2.1.1]
Talk to us¶
Use Github discussions forum or for a live chat experience try
#ansible-lint IRC channel on libera.chat.
Possible security bugs should be reported via email to firstname.lastname@example.org.
Adding a new rule¶
Writing a new rule is as easy as adding a single new rule, one that combines implementation, testing and documentation.
One good example is MetaTagValidRule which can easily be copied in order to create a new rule by following the steps below:
Use a short but clear class name, which must match the filename
Pick an unused
id, the first number is used to determine rule section. Look at rules page and pick one that matches the best your new rule. see which one fits best.
experimentaltag. Any new rule must stay as experimental for at least two weeks until this tag is removed in next major release.
Update all class level variables.
Implement linting methods needed by your rule, these are those starting with match prefix. Implement only those you need. For the moment you will need to look at how similar rules were implemented to figure out what to do.
Update the tests. It must have at least one test and likely also a negative match one.
If the rule is task specific, it may be best to include a test to verify its use inside blocks as well.
Optionally run only the rule specific tests with a command like: tox -e py38-ansible29 -- -k NewRule
Run tox in order to run all ansible-lint tests. Adding a new rule can break some other tests. Update them if needed.
Run ansible-lint -L and check that the rule description renders correctly.
Build the docs using tox -e docs and check that the new rule is displayed correctly in them.