2. If the module changes the system state, check the actual system state using at least one other module. For example, if the module changes a file, we can check that the file has been changed by checking its checksum with the :ref:`stat <ansible_collections.ansible.builtin.stat_module>` module before and after the test tasks.
3. Run the same task with ``check_mode: yes`` if check-mode is supported by the module. Check with other modules that the actual system state has not been changed.
3. Run the same task with ``check_mode: true`` if check-mode is supported by the module. Check with other modules that the actual system state has not been changed.
4. Cover cases when the module must fail. Use the ``ignore_errors: true`` option and check the returned message with the ``assert`` module.
The new version is assumed to be ``X.Y.Z``, and the previous patch version is assumed to be ``X.Y.z`` with ``z < Z``. ``z`` is frequently``0`` snce patch releases are uncommon.
The new version is assumed to be ``X.Y.Z``, and the previous patch version is assumed to be ``X.Y.z`` with ``z < Z``. ``z`` is frequently``0`` since patch releases are uncommon.
@ -46,6 +46,8 @@ We do not merge every PR. See :ref:`collection_quickstart` for tips to make you
Creating changelog fragments
-----------------------------
Most changelogs should emphasize the impact of the change on the end user of the feature or collection, unless the change impacts developers directly. Consider what the user needs to know about this change and write the changelog to convey that detail.
Changelogs help users and developers keep up with changes to Ansible collections. Many collections build changelogs for each release from fragments. For collections that use this model, you **must** add a changelog fragment to any PR that changes functionality or fixes a bug.
You do not need a changelog fragment for PRs that:
This section describes the contributor journey from the beginning to becoming a leader who helps shape the future of Ansible. You can use this path as a roadmap for your long-term participation.
This section describes the contributor's journey from the beginning to becoming a leader who helps shape the future of Ansible. You can use this path as a roadmap for your long-term participation.
Any contribution to the project, even a small one, is very welcome and valuable. Any contribution counts, whether it's feedback on an issue, a pull request, a topic or documentation change, or a coding contribution. When you contribute regularly, your proficiency and judgment in the related area increase and, along with this, the importance of your presence in the project.
@ -39,16 +39,16 @@ Specific knowledge for code developers
Code development requires the most technical knowledge. Let's sort out what an Ansible developer should learn.
You should understand at least *basics* of the following tools:
You should understand at least the *basics* of the following tools:
- `Python programming language <https://docs.python.org/3/tutorial/>`_
- `Git <https://git-scm.com/docs/gittutorial>`_
- `GitHub collaborative development model through forks and pull requests <https://docs.github.com/en/github/collaborating-with-pull-requests/getting-started/about-collaborative-development-models>`_
You can learn these tools more indepth when working on your first contributions.
You can learn these tools more in-depth when working on your first contributions.
Each Ansible project has its own set of contributor guidelines. Familarize yourself with these as you prepare your first contributions.
Each Ansible project has its own set of contributor guidelines. Familiarize yourself with these as you prepare your first contributions.
* :ref:`Ansible Core development <developer_guide>`.
* :ref:`Ansible collection development <developing_collections>` and the collection-level contributor guidelines in the collection repository.
@ -72,18 +72,18 @@ See :ref:`communication` for ways to communicate and engage with the Ansible com
Teach others
============
Share your experience with other contributors through `improving documentation <ommunity_documentation_contributions>`, answering question from other contributors and users on `Matrix/Libera.Chat IRC <communicate>`, giving advice in issues and pull requests, and discussing the `Community Topics <https://github.com/ansible-community/community-topics/issues>`_.
Share your experience with other contributors through :ref:`improving documentation<community_documentation_contributions>`, and answering questions from other contributors and users on :ref:`Matrix/Libera.Chat IRC<communication>`, giving advice on issues and pull requests, and discussing `Community Topics <https://github.com/ansible-community/community-topics/issues>`_.
Become a collection maintainer
===============================
If you are a code contributor to a collection, you can get extended permissions in the repository and become a maintainer. A collection maintainer is a contributor trusted by the community who makes significant and regular contributions to the project and showed themselves as a specialist in the related area. See :ref:`maintainers` for details.
For some collections that use the `collection bot <https://github.com/ansible-community/collection_bot>`_, such as `community.general <https://github.com/ansible-collections/community.general>`_ and `community.network <https://github.com/ansible-collections/community.network>`_, you can have different levels of access and permissions.
For some collections that use the `collection bot <https://github.com/ansible-community/collection_bot>`_, such as `community.general <https://github.com/ansible-collections/community.general>`_ and `community.network <https://github.com/ansible-collections/community.network>`_, you can have different levels of access and permissions.
* `module_maintainers` - The stage prior to becoming a collection maintainer. The file is usually a module or plugin. File maintainers have indirect commit rights.
* supershipit permissions - Similar to being a file maintainer but the scope where a maintainer has the indirect commit is the whole repository.
* ``triage`` - Access to the repository that allows contributors manage issues and pull requests.
* ``triage`` - Access to the repository that allows contributors to manage issues and pull requests.
* ``write`` access to the repository also known as ``commit``. In other words, become a committer. This access level allows contributors to merge pull requests to the development branch as well as perform all the other activities listed in the :ref:`maintainers`.
For information about permission levels, see the `GitHub official documentation <https://docs.github.com/en/organizations/managing-access-to-your-organizations-repositories/repository-permission-levels-for-an-organization>`_.
@ -95,7 +95,7 @@ Become a steering committee member
You do NOT have to be a programmer to become a steering committee member.
The :ref:`Steering Committee <community_steering_committee>` member status reflects the highest level of trust which allows contributors to lead the project through making very important `decisions <https://github.com/ansible-community/community-topics/issues>`_ for the Ansible project. The Committee members are the community leaders who shape the project's future and the future of automation in the IT world in general.
The :ref:`Steering Committee <community_steering_committee>` member status reflects the highest level of trust which allows contributors to lead the project by making very important `decisions <https://github.com/ansible-community/community-topics/issues>`_ for the Ansible project. The Committee members are the community leaders who shape the project's future and the future of automation in the IT world in general.
To reach the status, as the current Committee members did before getting it, along with the things mentioned in this document, you should:
Do NOT mix several bugfixes or features that are not tightly-related in one pull request. Use separate pull requests for different changes.
Do NOT mix several bug fixes or features that are not tightly related in one pull request. Use separate pull requests for different changes.
You should start with writing integration and unit tests if applicable. These can verify the bug exists (prior to your code fix) and verify your code fixed that bug once the tests pass.
@ -113,7 +113,7 @@ 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 a dedicated test file.
You can use one of the existing test files as a draft.
When fixing a bug, write a task which reproduces the bug from the issue.
When fixing a bug, write a task that reproduces the bug from the issue.
Put the reported case in the tests, then run integration tests with the following command:
@ -121,16 +121,16 @@ Put the reported case in the tests, then run integration tests with the followin
You can use the ``-vv`` or ``-vvv`` argument, if you need more detailed output.
You can use the ``-vv`` or ``-vvv`` argument if you need more detailed output.
In the examples above, the default test image is automatically downloaded and used to create and run a test container.
Use the default test image for platformindependent integration tests such as those for cloud modules.
Use the default test image for platform-independent integration tests such as those for cloud modules.
If you need to run the tests against a specific distribution, see the :ref:`list of supported container images <test_container_images>`. For example:
@ -145,7 +145,7 @@ If you need to run the tests against a specific distribution, see the :ref:`list
If the tests ran successfully, there are usually two possible outcomes:
- If the bug has not appeared and the tests have passed successfully, ask the reporter to provide more details. It may not be a bug or can relate to a particular software version used or specifics of the reporter's local environment configuration.
- The bug has appeared and the tests has failed as expected showing the reported symptoms.
- The bug has appeared and the tests have failed as expected showing the reported symptoms.
Fix the bug
=============
@ -155,6 +155,8 @@ See :ref:`module_contribution` for some general guidelines about Ansible module
Test your changes
=================
If using the ``docker`` CLI program, the host must be configured to use cgroupsv1 (this is not required for ``podman``). This can be done by adding ``systemd.unified_cgroup_hierarchy=0`` to the kernel boot arguments (requires bootloader config update and reboot).
1. Install ``flake8`` (``pip install flake8``, or install the corresponding package on your operating system).
1. Run ``flake8`` against a changed file:
@ -164,7 +166,7 @@ Test your changes
$ flake8 path/to/changed_file.py
This shows unused imports, which is not shown by sanity tests, as well as other common issues.
This shows unused imports, which are not shown by sanity tests, as well as other common issues.
Optionally, you can use the ``--max-line-length=160`` command-line argument.
2. Run sanity tests:
@ -193,7 +195,7 @@ Test your changes
There are two possible outcomes:
- They have failed. Look at the output of the command. Fix the problem place in the code and run again. Repeat the cycle until the tests pass.
- They have failed. Look at the output of the command. Fix the problem in the code and run again. Repeat the cycle until the tests pass.
- They have passed. Remember they failed originally? Our congratulations! You have fixed the bug.
In addition to the integration tests, you can also cover your changes with unit tests. This is often required when integration tests are not applicable to the collection.
@ -234,7 +236,7 @@ Submit a pull request
GitHub is tracking your fork, so it should see the new branch in it and automatically offer to create a pull request. Sometimes GitHub does not do it, and you should click the :guilabel:`New pull request` button yourself. Then choose :guilabel:`compare across forks` under the :guilabel:`Compare changes` title.
5.Choose your repository and the new branch you pushed in the right drop-down list. Confirm.
5.Choose your repository and the new branch you pushed in the right drop-down list. Confirm.
a. Fill out the pull request template with all information you want to mention.
@ -263,9 +265,9 @@ Submit a pull request
7. Verify the CI tests pass that run automatically on Red Hat infrastructure after every commit.
You will see the CI status in the bottom of your pull request. If they are green and you think that you do not want to add more commits before someone should take a closer look at it, remove ``[WIP]`` from the title. Mention the issue reporter in a comment and let contributors know that the pull request is "Ready for review".
You will see the CI status at the bottom of your pull request. If they are green and you think that you do not want to add more commits before someone should take a closer look at it, remove ``[WIP]`` from the title. Mention the issue reporter in a comment and let contributors know that the pull request is "Ready for review".
8. Wait for reviews. You can also ask for review in the ``#ansible-community``:ref:`Matrix/Libera.Chat IRC channel <communication_irc>`.
8. Wait for reviews. You can also ask for a review in the ``#ansible-community``:ref:`Matrix/Libera.Chat IRC channel <communication_irc>`.
9. If the pull request looks good to the community, committers will merge it.
As you become more familiar with how Ansible works, you may be able to fix issues or develop new features yourself. If you think you have a fix for a bug in Ansible, or if you have a new feature that you would like to share with millions of Ansible users, read all about the :ref:`development process <community_development_process>` to learn how to get your code accepted into Ansible.
Another good way to help is to review pull requests that other Ansible users have submitted. Ansible core keeps a full list of `open pull requests by file <https://ansible.sivel.net/pr/byfile.html>`_, so if a particular module or plugin interests you, you can easily keep track of all the relevant new pull requests and provide testing or feedback. Alternately, you can review the pull requests for any collections that interest you. Click :guilabel:`Issue tracker` on the collection documentation page to find the issues and PRs for that collection.
Another good way to help is to review pull requests that other Ansible users have submitted. Ansible core keeps a full list of `open pull requests by file <https://ansible.sivel.net/pr/byfile.html>`_, so if a particular module or plugin interests you, you can easily keep track of all the relevant new pull requests and provide testing or feedback. Alternatively, you can review the pull requests for any collections that interest you. Click :guilabel:`Issue tracker` on the collection documentation page to find the issues and PRs for that collection.
The purpose of this guide is to teach you everything you need to know about being a contributing member of the Ansible community. All types of contributions are welcome and necessary to Ansible's continued success.
The purpose of this guide is to teach you everything you need to know about being a contributing member of the Ansible community. All types of contributions are welcome and necessary for Ansible's continued success.
Before you request a feature, check what is :ref:`planned for future Ansible Releases <roadmaps>`.
The best way to get a feature into an Ansible collection is to :ref:`submit a pull request <community_pull_requests>`, either against ansible-core or against a collection. See also :ref:`ansible_collection_merge_requirements`.
The best way to get a feature into an Ansible collection is to :ref:`submit a pull request <community_pull_requests>`, either against ansible-core or against a collection. See also the :ref:`ansible_collection_merge_requirements`.
You can also submit a feature request through opening an issue in the collection repository.
You can also submit a feature request by opening an issue in the collection repository.
@ -189,10 +189,10 @@ You can have most of the subdirectories you would expect, such ``files/``, ``var
Also, playbooks within a collection follow the same guidelines as any playbooks except for these few adjustments:
- Directory: It must be in ``/playbooks directory``.
- Directory: It must be in the ``playbooks/`` directory.
- Hosts: The host should be defined as a variable so the users of a playbook do not mistakenly run the plays against their entire inventory (if the host is set to all). For example - ``hosts: '{{target|default("all")}}'``.
To run the plays, users can now use such commands as ``ansible-playbook --e 'targets=webservers'`` or ``ansible-playbook --limit webservers``. Either way, the collection owner should document their playbooks and how to use them in the ``/docs`` folder or ``README`` file.
To run the plays, users can now use such commands as ``ansible-playbook --e 'targets=webservers'`` or ``ansible-playbook --limit webservers``. Either way, the collection owner should document their playbooks and how to use them in the ``docs/`` folder or ``README`` file.
@ -53,7 +53,7 @@ Here's what a plain text inventory file looks like:
db0.example.com
db1.example.com
Once inventory hosts are listed, variables can be assigned to them in simple text files (in a subdirectory called 'group_vars/' or 'host_vars/' or directly in the inventory file.
Once inventory hosts are listed, variables can be assigned to them in simple text files (in a subdirectory called 'group_vars/' or 'host_vars/') or directly in the inventory file.
Or, as already mentioned, use a dynamic inventory to pull your inventory from data sources like EC2, Rackspace, or OpenStack.
In a case like this (or ``local_action``) when Ansible needs to contact a 'localhost' but you did not supply one, we create one for you. This host is defined with specific connection variables equivalent to this in an inventory::
In a case like this (or ``local_action``) when Ansible needs to contact a 'localhost' but you did not supply one, we create one for you. This host is defined with specific connection variables equivalent to this in an inventory:
..code-block:: yaml
...
@ -27,6 +31,7 @@ This ensures that the proper connection and Python are used to execute your task
You can override the built-in implicit version by creating a ``localhost`` host entry in your inventory. At that point, all implicit behaviors are ignored; the ``localhost`` in inventory is treated just like any other host. Group and host vars will apply, including connection vars, which includes the ``ansible_python_interpreter`` setting. This will also affect ``delegate_to: localhost`` and ``local_action``, the latter being an alias to the former.
..note::
- This host is not targetable via any group, however it will use vars from ``host_vars`` and from the 'all' group.
- Implicit localhost does not appear in the ``hostvars`` magic variable unless demanded, such as by ``"{{ hostvars['localhost'] }}"``.
- The ``inventory_file`` and ``inventory_dir`` magic variables are not available for the implicit localhost as they are dependent on **each inventory host**.
The extended first playbook has four tasks in a single play. Run it with the same command you used above. The output shows you the change Ansible made to the config:
The extended first playbook has five tasks in a single play. Run it with the same command you used above. The output shows you the change Ansible made to the config:
@ -6,7 +6,7 @@ Ansible 2.5 and above work with Python 3. Previous to 2.5, using Python 3 was
considered a tech preview. This topic discusses how to set up your controller and managed machines
to use Python 3.
..note:: On the controller we support Python 3.5 or greater and Python 2.7 or greater. Module-side, we support Python 3.5 or greater and Python 2.6 or greater.
See :ref: `Control Node Requirements <control_node_requirements>` and :ref: `Managed Node Requirements <managed_node_requirements>` for the specific versions supported.
On the controller side
----------------------
@ -18,7 +18,7 @@ version of pip. This will make the default :command:`/usr/bin/ansible` run with
$ pip3 install ansible
$ ansible --version | grep "python version"
python version = 3.6.2 (default, Sep 22 2017, 08:28:09) [GCC 7.2.1 20170915 (Red Hat 7.2.1-2)]
python version = 3.10.5 (main, Jun 9 2022, 00:00:00) [GCC 12.1.1 20220507 (Red Hat 12.1.1-1)] (/usr/bin/python)
If you are running Ansible :ref:`from_source` and want to use Python 3 with your source checkout, run your
Sandra McCann
2 years ago
committed by