'Continue building on your automation knowledge, visit the <ahref="https://events.experiences.redhat.com/widget/redhat/rhaf22/SessionCatalog2022">AnsibleFest content hub!</a> ' +
'</p>' +
'<br>' +
'</div>'; */
'</div>';
// Create a banner if we're not on the official docs site
if (location.host == "docs.testing.ansible.com") {
@ -112,6 +112,8 @@ A few recommendations when creating such playbooks, ``hosts:`` should be generic
This will have an implied entry in the ``collections:`` keyword of ``my_namespace.my_collection`` just as with roles.
..note::
Playbook names, like other collection resources, have a restricted set of valid characters.
Names can contain only lowercase alphanumeric characters, plus _ and must start with an alpha character. The dash ``-`` character is not valid for playbook names in collections.
Playbooks whose names contain invalid characters are not addressable: this is a limitation of the Python importer that is used to load collection resources.
* Playbook names, like other collection resources, have a restricted set of valid characters.
Names can contain only lowercase alphanumeric characters, plus _ and must start with an alpha character. The dash ``-`` character is not valid for playbook names in collections.
Playbooks whose names contain invalid characters are not addressable: this is a limitation of the Python importer that is used to load collection resources.
* Playbooks in collections do not support 'adjacent' plugins, all plugins must be in the collection specific directories.
- There are no integration tests for a collection / group of modules in a collection at all.
- There are no integration tests for a collection or group of modules in a collection at all.
- You are adding a new module and you want to include integration tests.
- You want to add integration tests for a module that already exists without integration tests.
@ -92,7 +92,7 @@ Add the following to ``tests/integration/targets/abstract_service_info/tasks/mai
- name: Fetch info from abstract service
abstract_service_info:
host: 127.0.0.1 # We assume the service accepts local connection by default
port: 1234 # We assume that the service is listening this port by default
port: 1234 # We assume that the service is listening to this port by default
register: result # This variable will contain the returned JSON including the server version
- name: Test the output
@ -104,7 +104,7 @@ Add the following to ``tests/integration/targets/abstract_service_info/tasks/mai
If there are any issues with connectivity (for example, the service is not accepting connections) or with the code, the play will fail.
Examine the output to see at which step the failure occurred. Investigate the reason, fix, and run again. Repeat the cycle until the test passes.
Examine the output to see at which step the failure occurred. Investigate the reason, fix it, and run again. Repeat the cycle until the test passes.
8. If the test succeeds, write more tests. Refer to the :ref:`Recommendations on coverage<collection_integration_recommendations>` section for details.
@ -201,7 +201,7 @@ That is enough for our very basic example.
11. To make the ``setup_postgresql_db`` target running before the ``postgresql_info`` target as a dependency, create the ``tests/integration/targets/postgresql_info/meta/main.yml`` file and add the following code to it:
11. To make the ``setup_postgresql_db`` target run before the ``postgresql_info`` target as a dependency, create the ``tests/integration/targets/postgresql_info/meta/main.yml`` file and add the following code to it:
..code-block:: yaml
@ -247,4 +247,4 @@ The tests should pass. If we look at the output, we should see something like th
"msg": "All assertions passed"
}
If your tests fail when you are working on your project, examine the output to see at which step the failure occurred. Investigate the reason, fix, and run again. Repeat the cycle until the test passes. If the test succeeds, write more tests. Refer to the :ref:`Recommendations on coverage<collection_integration_recommendations>` section for details.
If your tests fail when you are working on your project, examine the output to see at which step the failure occurred. Investigate the reason, fix it, and run again. Repeat the cycle until the test passes. If the test succeeds, write more tests. Refer to the :ref:`Recommendations on coverage<collection_integration_recommendations>` section for details.
In the following examples, we will use ``Docker`` to run integration tests locally. Ensure you have :ref:`collection_prepare_environment` first.
In the following examples, we will use ``Docker`` to run integration tests locally. Ensure you :ref:`collection_prepare_environment` first.
We assume that you are in the ``~/ansible_collections/NAMESPACE/COLLECTION`` directory.
@ -25,7 +25,7 @@ In the examples above, the ``fedora34`` test image will be automatically downloa
See the :ref:`list of supported container images <test_container_images>`.
In some cases, for example, for platformindependent tests, the ``default`` test image is required. Use the ``--docker default`` or just ``--docker`` option without specifying a distribution in this case.
In some cases, for example, for platform-independent tests, the ``default`` test image is required. Use the ``--docker default`` or just ``--docker`` option without specifying a distribution in this case.
@ -6,7 +6,7 @@ Adding to an existing integration test
The test tasks are stored in the ``tests/integration/targets/<target_name>/tasks`` directory.
The ``main.yml`` file holds test tasks and includes other test files.
Look for a suitable test file to integrate your tests or create and include / import a separate test file.
Look for a suitable test file to integrate your tests or create and include or import a separate test file.
You can use one of the existing test files as a draft.
When fixing a bug
@ -15,9 +15,9 @@ When fixing a bug
When fixing a bug:
1. :ref:`Determine if integration tests for the module exist<collection_integration_prepare>`. If they do not, see :ref:`collection_creating_integration_tests` section.
2. Add a task which reproduces the bug to an appropriate file within the ``tests/integration/targets/<target_name>/tasks`` directory.
2. Add a task that reproduces the bug to an appropriate file within the ``tests/integration/targets/<target_name>/tasks`` directory.
3. :ref:`Run the tests<collection_run_integration_tests>`. The newly added task should fail.
4. If they do not fail, re-check if your environment / test task satisfies the conditions described in the ``Steps to Reproduce`` section of the issue.
4. If they do not fail, re-check if your environment or test task satisfies the conditions described in the ``Steps to Reproduce`` section of the issue.
5. If you reproduce the bug and tests fail, change the code.
6. :ref:`Run the tests<collection_run_integration_tests>` again.
7. If they fail, repeat steps 5-6 until the tests pass.
@ -74,7 +74,7 @@ When adding a new feature
The process described in this section also applies when you want to add integration tests to a feature that already exists, but is missing integration tests.
If you have not already implemented the new feature, you can start with writing the integration tests for it. Of course they will not work as the code does not yet exist, but it can help you improve your implementation design before you start writing any code.
If you have not already implemented the new feature, you can start by writing the integration tests for it. They will not work as the code does not yet exist, but they can help you improve your implementation design before you start writing any code.
When adding new features, the process of adding tests consists of the following steps:
When users report bugs, verify the behavior reported. Remember always to be kind with your feedback.
* Did the user made a mistake in the code they put in the Steps to reproduce issue's section? We often see user errors reported as bugs.
* Did the user make a mistake in the code they put in the Steps to Reproduce issue section? We often see user errors reported as bugs.
* Did the user assume an unexpected behavior? Ensure that the related documentation is clear. If not, the issue is useful to help us improve documentation.
* Is there a minimal reproducer? If not, ask the reporter to reduce the complexity to help pinpoint the issue.
* Is the issue a consequence of wrong-configured environment?
* If it seems to be real bug, does the behaviour still exist in the most recent release or the development branch?
* Is the issue a consequence of a misconfigured environment?
* If it seems to be a real bug, does the behaviour still exist in the most recent release or the development branch?
* Reproduce the bug, or if you do not have a suitable infrastructure, ask other contributors to reproduce the bug.
Reviewing suggested changes
---------------------------
When reviewing PRs, verify the suggested changes first. Do not:
When reviewing PRs, verify that the suggested changes do not:
* Unnecessarily break backwards compatibility.
* Unnecessarily break backward compatibility.
* Bring more harm than value.
* Introduce non-idempotent solutions.
* Duplicate already existing features (inside or outside the collection).
@ -32,7 +32,7 @@ When reviewing PRs, verify the suggested changes first. Do not:
Other standards to check for in a PR include:
* A pull request MUST NOT contain a mix of bugfixes and new features that are not tightly related. If yes, ask the author to split the pull request into separate PRs.
* A pull request MUST NOT contain a mix of bugfixes and new features that are not tightly related. If yes, ask the author to split the pull request into separate PRs.
* If the pull request is not a documentation fix, it must include a :ref:`changelog fragment <collection_changelog_fragments>`. Check the format carefully as follows:
* New modules and plugins (that are not jinja2 filter and test plugins) do not need changelog fragments.
@ -45,7 +45,7 @@ Other standards to check for in a PR include:
* If a new plugin is added, it is one of the `allowed plugin types <https://github.com/ansible-collections/overview/blob/main/collection_requirements.rst#modules-plugins>`_.
* Documentation, examples, and return sections use FQCNs for the ``M(..)``:ref:`format macros <module_documents_linking>` when referring to modules.
* Modules and plugins from ansible-core use ``ansible.builtin.`` as an FQCN prefix when mentioned.
* When a new option, module, plugin, or return value is added, the corresponding documentation or return sections use ``version_added:`` containing the *collection* version which they will be first released in.
* When a new option, module, plugin, or return value is added, the corresponding documentation or return sections use ``version_added:`` containing the *collection* version in which they will be first released.
* This is typically the next minor release, sometimes the next major release. For example: if 2.7.5 is the current release, the next minor release will be 2.8.0, and the next major release will be 3.0.0).
@ -70,5 +70,5 @@ Review for merge commits and breaking changes
---------------------------------------------
* The pull request does not contain merge commits. See the GitHub warnings at the bottom of the pull request. If merge commits are present, ask the author to rebase the pull request branch.
* If the pull request contains breaking changes, ask the author and the collection maintainers if it really is needed, and there is a way not to introduce breaking changes. If breaking changes are present, they MUST only appear in the next major release and MUST NOT appear in a minor or patch release. The only exception is breaking changes caused by security fixes that are absolutely necessary to fix the security issue.
* If the pull request contains breaking changes, ask the author and the collection maintainers if it really is needed, and if there is a way not to introduce breaking changes. If breaking changes are present, they MUST only appear in the next major release and MUST NOT appear in a minor or patch release. The only exception is breaking changes caused by security fixes that are absolutely necessary to fix the security issue.
@ -23,7 +23,7 @@ Your first post to the mailing list will be moderated (to reduce spam), so pleas
* `Ansible AWX List <https://groups.google.com/forum/#!forum/awx-project>`_ is for `Ansible AWX <https://github.com/ansible/awx>`_
* `Ansible Development List <https://groups.google.com/forum/#!forum/ansible-devel>`_ is for questions about developing Ansible modules (mostly in Python), fixing bugs in the Ansible core code, asking about prospective feature design, or discussions about extending Ansible or features in progress.
* `Ansible Lockdown List <https://groups.google.com/forum/#!forum/ansible-lockdown>`_ is for all things related to Ansible Lockdown projects, including DISA STIG automation and CIS Benchmarks.
* `Ansible Outreach List <https://groups.google.com/forum/#!forum/ansible-outreach>`_ help with promoting Ansible and `Ansible Meetups <https://ansible.meetup.com/>`_
* `Ansible Outreach List <https://groups.google.com/forum/#!forum/ansible-outreach>`_ help with promoting Ansible and `Ansible Meetups <https://www.meetup.com/topics/ansible/>`_
* `Ansible Project List <https://groups.google.com/forum/#!forum/ansible-project>`_ is for sharing Ansible tips, answering questions about playbooks and roles, and general user discussion.
* `Molecule Discussions <https://github.com/ansible-community/molecule/discussions>`_ is designed to aid with the development and testing of Ansible roles with Molecule.
@ -16,7 +16,7 @@ In general, collection maintainers:
- Act in accordance with the :ref:`code_of_conduct`.
- Subscribe to the collection repository they maintain (click :guilabel:`Watch > All activity` in GitHub).
- Keep README, development guidelines, and other general collection :ref:`maintainer_documentation` relevant.
- Keep README, development guidelines, and other general collections:ref:`maintainer_documentation` relevant.
- Review and commit changes made by other contributors.
- :ref:`Backport <Backporting>` changes to stable branches.
- Address or assign issues to appropriate contributors.
@ -32,7 +32,7 @@ Multiple maintainers can divide responsibilities among each other.
How to become a maintainer
--------------------------
A person interested in becoming a maintainer and satisfies the :ref:`requirements<maintainer_requirements>` may either self-nominate or be nominated by another maintainer.
A person interested in becoming a maintainer and satisfying the :ref:`requirements<maintainer_requirements>` may either self-nominate or be nominated by another maintainer.
To nominate a candidate, create a GitHub issue in the relevant collection repository. If there is no response, the repository is not actively maintained, or the current maintainers do not have permissions to add the candidate, please create the issue in the `ansible/community <https://github.com/ansible/community>`_ repository.
@ -44,7 +44,7 @@ Communicating as a collection maintainer
Collection contributors and maintainers should also communicate through:
* :ref:`communication_irc` appropriate to their collection, or if none exist, the general community and developer chat channels
* :ref:`communication_irc` appropriate to their collection, or if none exists, the general community and developer chat channels
* Mailing lists such as `ansible-announce <https://groups.google.com/d/forum/ansible-announce>`_ and `ansible-devel <https://groups.google.com/d/forum/ansible-devel>`_
* Collection project boards, issues, and GitHub discussions in corresponding repositories
* Quarterly Contributor Summits.
@ -65,7 +65,7 @@ Contributor Summits
-------------------
The quarterly Ansible Contributor Summit is a global event that provides our contributors a great opportunity to meet each other, communicate, share ideas, and see that there are other real people behind the messages on Matrix or Libera Chat IRC or GitHub. This gives a sense of community. Watch the `Bullhorn newsletter <https://github.com/ansible/community/wiki/News#the-bullhorn>`_ for information when the next contributor summit, invite contributors you know, and take part in the event together.
The quarterly Ansible Contributor Summit is a global event that provides our contributors a great opportunity to meet each other, communicate, share ideas, and see that there are other real people behind the messages on Matrix or Libera Chat IRC, or GitHub. This gives a sense of community. Watch the `Bullhorn newsletter <https://github.com/ansible/community/wiki/News#the-bullhorn>`_ for information when the next contributor summit, invite contributors you know, and take part in the event together.
Weekly community Matrix/IRC meetings
------------------------------------
@ -102,13 +102,13 @@ Here are some ways you can expand the community around your collection:
Encouraging new contributors
-----------------------------
Easyfix items are the best way to attract and mentor new contributors. You should triage incoming issues to mark them with labels such as ``easyfix``, ``waiting_on_contributor``, and ``docs``. where appropriate. Do not fix these trivial non-critical bugs yourself. Instead, mentor a person who wants to contribute.
Easy-fix items are the best way to attract and mentor new contributors. You should triage incoming issues to mark them with labels such as ``easyfix``, ``waiting_on_contributor``, and ``docs``. where appropriate. Do not fix these trivial non-critical bugs yourself. Instead, mentor a person who wants to contribute.
For some easyfix issues, you could ask the issue reporter whether they want to fix the issue themselves providing the link to a quickstart guide for creating PRs.
For some easy-fix issues, you could ask the issue reporter whether they want to fix the issue themselves providing the link to a quickstart guide for creating PRs.
Conduct pull request days regularly. You could plan PR days, for example, in the last Friday of every month when you and other maintainers go through all open issues and pull requests focusing on old ones, asking people if you can help, and so on. If there are pull requests that look abandoned (for example, there is no response on your help offers since the previous PR day), announce that anyone else interested can complete the pull request.
Conduct pull request days regularly. You could plan PR days, for example, on the last Friday of every month when you and other maintainers go through all open issues and pull requests focusing on old ones, asking people if you can help, and so on. If there are pull requests that look abandoned (for example, there is no response on your help offers since the previous PR day), announce that anyone else interested can complete the pull request.
Promote active contributors satisfying :ref:`requirements<maintainer_requirements>` to maintainers. Revise contributors activity regularly.
Promote active contributors satisfying :ref:`requirements<maintainer_requirements>` to maintainers. Revise contributors' activity regularly.
If your collection found new maintainers, announce that fact in the `Bullhorn newsletter <https://github.com/ansible/community/wiki/News#the-bullhorn>`_ and during the next Contributor Summit congratulating and thanking them for the work done. You can mention all the people promoted since the previous summit. Remember to invite the other maintainers to the Summit in advance.
@ -118,8 +118,8 @@ Some other general guidelines to encourage contributors:
* If there is a non-crucial easy-fix bug reported, politely ask the author to fix it themselves providing a link to :ref:`collection_quickstart`.
* When suggesting changes, try to use questions, not statements.
* When suggesting mandatory changes, do it as politely as possible providing documentation references.
* If your suggestion is optional or a matter of personal preferences, please say it explicitly.
* When asking for adding tests or for complex code refactoring, say that the author is welcome to ask for clarifications and help if they need.
* If your suggestion is optional or a matter of personal preference, please say it explicitly.
* When asking for adding tests or for complex code refactoring, say that the author is welcome to ask for clarifications and help if they need it.
* If somebody suggests a good idea, mention it or put a thumbs up.
* After merging, thank the author and reviewers for their time and effort.
@ -140,7 +140,7 @@ A good ``README`` includes a description of the collection, a link to the :ref:`
The ``CONTRIBUTING`` file includes all the details or links to the details on how a new or continuing contributor can contribute to this collection. The ``CONTRIBUTING`` file should include:
* Information or links to new contributor guidelines, such as a quickstart on opening PRs.
* Information or links to new contributor guidelines, such as a quickstart on opening PRs.
* Information or links to contributor requirements, such as unit and integration test requirements.
You can optionally include a ``CONTRIBUTORS`` and ``MAINTAINERS`` file to list the collection contributors and maintainers.
Module-scope maintainers exist in collections that have the `collection bot <https://github.com/ansible-community/collection_bot>`_,
for example `community.general <https://github.com/ansible-collections/community.general>`_
for example,`community.general <https://github.com/ansible-collections/community.general>`_
and `community.network <https://github.com/ansible-collections/community.network>`_.
Being a module maintainer is the stage prior to becoming a collection maintainer. Module maintainers are contributors who are listed in ``.github/BOTMETA.yml``. The scope can be any file (for example, a module or plugin), directory, or repository. Because in most cases the scope is a module or group of modules, we call these contributors module maintainers. The collection bot notifies module maintainers when issues/pull requests related to files they maintain are created.
Being a module maintainer is the stage prior to becoming a collection maintainer. Module maintainers are contributors who are listed in ``.github/BOTMETA.yml``. The scope can be any file (for example, a module or plugin), directory, or repository. Because in most cases the scope is a module or group of modules, we call these contributors module maintainers. The collection bot notifies module maintainers when issues/pull requests related to files they maintain are created.
Module maintainers have indirect commit rights implemented through the `collection bot <https://github.com/ansible-community/collection_bot>`_.
When two module maintainers comment with the keywords ``shipit``, ``LGTM``, or ``+1`` on a pull request
@ -47,7 +47,7 @@ see to the `Collection bot overview <https://github.com/ansible-community/collec
Releasing a collection
----------------------
Collection maintainers are responsible for releasing new versions of a collection. Generally, releasing in the collections consists of:
Collection maintainers are responsible for releasing new versions of a collection. Generally, releasing a collection consists of:
#. Planning and announcement.
#. Generating a changelog.
@ -76,14 +76,14 @@ For convenience, backporting can be implemented automatically using GitHub bots
Including a collection in Ansible
-----------------------------------
If a collection is not included in Ansible (not shipped with Ansible package), maintainers can submit the collection for inclusion by creating a discussion under `ansible-collections/ansible-inclusion repository <https://github.com/ansible-collections/ansible-inclusion>`_. For more information, see the `repository's README <https://github.com/ansible-collections/ansible-inclusion/blob/main/README.md>`_, and the `Ansible community package collections requirements <https://github.com/ansible-collections/overview/blob/main/collection_requirements.rst>`.
If a collection is not included in Ansible (not shipped with Ansible package), maintainers can submit the collection for inclusion by creating a discussion under the `ansible-collections/ansible-inclusion repository <https://github.com/ansible-collections/ansible-inclusion>`_. For more information, see the `repository's README <https://github.com/ansible-collections/ansible-inclusion/blob/main/README.md>`_, and the `Ansible community package collections requirements <https://github.com/ansible-collections/overview/blob/main/collection_requirements.rst>`.
Stepping down as a collection maintainer
===========================================
Times change, and so may your ability to continue as a collection maintainer. We ask that you do not step down silently.
If you feel you don't have time to maintain your collection anymore, you should:
If you feel you don't have time to maintain your collection anymore, you should:
- Inform other maintainers about it.
- If the collection is under the ``ansible-collections`` organization, also inform relevant :ref:`communication_irc`, the ``community`` chat channels on IRC or matrix, or by email ``ansible-community@redhat.com``.
The *managed* node (the machine that Ansible is managing) does not require Ansible to be installed, but requires Python 2.7, or Python 3.5 - 3.11 to run Ansible library code.
The managed node also needs a user account that can SSH to the node with an interactive POSIX shell.
@ -535,6 +535,9 @@ To use ``allow_duplicates: true`` with role dependencies, you must specify it fo
Embedding modules and plugins in roles
======================================
..note::
This applies only to standalone roles. Roles in collections do not support plugin embedding; they must use the collection's ``plugins`` structure to distribute plugins.
If you write a custom module (see :ref:`developing_modules`) or a plugin (see :ref:`developing_plugins`), you might wish to distribute it as part of a role. For example, if you write a module that helps configure your company's internal software, and you want other people in your organization to use this module, but you do not want to tell everyone how to configure their Ansible library path, you can include the module in your internal_config role.
Sandra McCann
2 years ago
committed by