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.
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.
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.
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:
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.
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:
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 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.
- 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
Fix the bug
=============
=============
@ -164,7 +164,7 @@ Test your changes
$ flake8 path/to/changed_file.py
$ 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.
Optionally, you can use the ``--max-line-length=160`` command-line argument.
2. Run sanity tests:
2. Run sanity tests:
@ -193,7 +193,7 @@ Test your changes
There are two possible outcomes:
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.
- 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.
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 +234,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.
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.
a. Fill out the pull request template with all information you want to mention.
@ -263,9 +263,9 @@ Submit a pull request
7. Verify the CI tests pass that run automatically on Red Hat infrastructure after every commit.
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.
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.
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.
Before you request a feature, check what is :ref:`planned for future Ansible Releases <roadmaps>`.
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.