Contribution guidelines

Ansible best practices

We try hard to follow Ansible Best Practices.

Include vs Import

Usually, we should rely on ansible.builtin.import_(tasks|role) instead of ansible.builtin.include_(tasks|role).

While both are mostly doing the same, the time and support is different.

Include

The include_* directives allow to load content dynamically. This is usually mandatory when we want to loop on items, and include multiple time the same tasks or role. The inclusion is done mostly runtime, and makes some usages a bit more complicated.

For instance, tags aren’t passed along, unless we use apply keyword.

The include_* directives may also have an impact on performances.

Import

The import_* directives allow to load content statically. It’s usually “compiled” internally when the play environment is built, meaning we may get small performances improvements. They fully support tags so that we may get a more convenient way to filter tasks in the play.

What to use then?

A simple rule of thumb: if I intend to run the tasks/role multiple time over the same play, I’ll use include_* module. For the rest, I’ll use import_*.

Testing

Ansible role

Please take the time to ensure molecule tests are present and cover as many corner cases as possible.

Ansible custom plugins

Please take the time to consider how to test your custom plugins. You may either rely on molecule or, maybe, ansible-test.

Review workflow

Once your patch is passing CI and not in draft status a reviewer will review your patch. If you would like to bring attention to your patch before a reviewer has made it to your patch reached out in our slack channel

Auto Draft status

When a PR is opened or reopened the Github bot will enable the draft status. Once your patch is passing CI and you would be happy with it merging, click the “Ready for review” button, this will then trigger the Review workflow mentioned above.