diff options
Diffstat (limited to 'docs/docsite/rst/community')
40 files changed, 4669 insertions, 0 deletions
diff --git a/docs/docsite/rst/community/advanced_index.rst b/docs/docsite/rst/community/advanced_index.rst new file mode 100644 index 0000000..b07b72f --- /dev/null +++ b/docs/docsite/rst/community/advanced_index.rst @@ -0,0 +1,14 @@ +.. _advanced_community_guide: + +********************************************** +Advanced Contributor Guide +********************************************** + +This guide focuses on contributors who are committers, GitHub admins, or release managers. + +.. toctree:: + :maxdepth: 1 + + committer_guidelines + release_managers + github_admins diff --git a/docs/docsite/rst/community/code_of_conduct.rst b/docs/docsite/rst/community/code_of_conduct.rst new file mode 100644 index 0000000..776236a --- /dev/null +++ b/docs/docsite/rst/community/code_of_conduct.rst @@ -0,0 +1,145 @@ +.. _code_of_conduct: + +************************* +Community Code of Conduct +************************* + +.. contents:: Topics + +Every community can be strengthened by a diverse variety of viewpoints, insights, +opinions, skillsets, and skill levels. However, with diversity comes the potential for +disagreement and miscommunication. The purpose of this Code of Conduct is to ensure that +disagreements and differences of opinion are conducted respectfully and on their own +merits, without personal attacks or other behavior that might create an unsafe or +unwelcoming environment. + +These policies are not designed to be a comprehensive set of Things You Cannot Do. We ask +that you treat your fellow community members with respect and courtesy, and in general, +Don't Be A Jerk. This Code of Conduct is meant to be followed in spirit as much as in +letter and is not exhaustive. + +All Ansible events and participants therein are governed by this Code of Conduct and +anti-harassment policy. We expect organizers to enforce these guidelines throughout all events, +and we expect attendees, speakers, sponsors, and volunteers to help ensure a safe +environment for our whole community. Specifically, this Code of Conduct covers +participation in all Ansible-related forums and mailing lists, code and documentation +contributions, public chat (Matrix, IRC), private correspondence, and public meetings. + +Ansible community members are... + +**Considerate** + +Contributions of every kind have far-ranging consequences. Just as your work depends on +the work of others, decisions you make surrounding your contributions to the Ansible +community will affect your fellow community members. You are strongly encouraged to take +those consequences into account while making decisions. + +**Patient** + +Asynchronous communication can come with its own frustrations, even in the most responsive +of communities. Please remember that our community is largely built on volunteered time, +and that questions, contributions, and requests for support may take some time to receive +a response. Repeated "bumps" or "reminders" in rapid succession are not good displays of +patience. Additionally, it is considered poor manners to ping a specific person with +general questions. Pose your question to the community as a whole, and wait patiently for +a response. + +**Respectful** + +Every community inevitably has disagreements, but remember that it is +possible to disagree respectfully and courteously. Disagreements are never an excuse for +rudeness, hostility, threatening behavior, abuse (verbal or physical), or personal attacks. + +**Kind** + +Everyone should feel welcome in the Ansible community, regardless of their background. +Please be courteous, respectful and polite to fellow community members. Do not make or +post offensive comments related to skill level, gender, gender identity or expression, +sexual orientation, disability, physical appearance, body size, race, or religion. +Sexualized images or imagery, real or implied violence, intimidation, oppression, +stalking, sustained disruption of activities, publishing the personal information of +others without explicit permission to do so, unwanted physical contact, and unwelcome +sexual attention are all strictly prohibited. Additionally, you are encouraged not to +make assumptions about the background or identity of your fellow community members. + +**Inquisitive** + +The only stupid question is the one that does not get asked. We +encourage our users to ask early and ask often. Rather than asking whether you can ask a +question (the answer is always yes!), instead, simply ask your question. You are +encouraged to provide as many specifics as possible. Code snippets in the form of Gists or +other paste site links are almost always needed in order to get the most helpful answers. +Refrain from pasting multiple lines of code directly into the chat channels - instead use +gist.github.com or another paste site to provide code snippets. + +**Helpful** + +The Ansible community is committed to being a welcoming environment for all users, +regardless of skill level. We were all beginners once upon a time, and our community +cannot grow without an environment where new users feel safe and comfortable asking questions. +It can become frustrating to answer the same questions repeatedly; however, community +members are expected to remain courteous and helpful to all users equally, regardless of +skill or knowledge level. Avoid providing responses that prioritize snideness and snark over +useful information. At the same time, everyone is expected to read the provided +documentation thoroughly. We are happy to answer questions, provide strategic guidance, +and suggest effective workflows, but we are not here to do your job for you. + +Anti-harassment policy +====================== + +Harassment includes (but is not limited to) all of the following behaviors: + +- Offensive comments related to gender (including gender expression and identity), age, sexual orientation, disability, physical appearance, body size, race, and religion +- Derogatory terminology including words commonly known to be slurs +- Posting sexualized images or imagery in public spaces +- Deliberate intimidation +- Stalking +- Posting others' personal information without explicit permission +- Sustained disruption of talks or other events +- Inappropriate physical contact +- Unwelcome sexual attention + +Participants asked to stop any harassing behavior are expected to comply immediately. +Sponsors are also subject to the anti-harassment policy. In particular, sponsors should +not use sexualized images, activities, or other material. Meetup organizing staff and +other volunteer organizers should not use sexualized attire or otherwise create a +sexualized environment at community events. + +In addition to the behaviors outlined above, continuing to behave a certain way after you +have been asked to stop also constitutes harassment, even if that behavior is not +specifically outlined in this policy. It is considerate and respectful to stop doing +something after you have been asked to stop, and all community members are expected to +comply with such requests immediately. + +Policy violations +================= + +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by +contacting `codeofconduct@ansible.com <mailto:codeofconduct@ansible.com>`_, to anyone with administrative power in community chat (Admins or Moderators on Matrix, ops on IRC), or to the local organizers of an event. Meetup +organizers are encouraged to prominently display points of contact for reporting unacceptable +behavior at local events. + +If a participant engages in harassing behavior, the meetup organizers may take any action +they deem appropriate. These actions may include but are not limited to warning the +offender, expelling the offender from the event, and barring the offender from future +community events. + +Organizers will be happy to help participants contact security or local law enforcement, +provide escorts to an alternate location, or otherwise assist those experiencing +harassment to feel safe for the duration of the meetup. We value the safety and well-being +of our community members and want everyone to feel welcome at our events, both online and +offline. + +We expect all participants, organizers, speakers, and attendees to follow these policies at +all of our event venues and event-related social events. + +The Ansible Community Code of Conduct is licensed under the Creative Commons +Attribution-Share Alike 3.0 license. Our Code of Conduct was adapted from Codes of Conduct +of other open source projects, including: + +* Contributor Covenant +* Elastic +* The Fedora Project +* OpenStack +* Puppet Labs +* Ubuntu diff --git a/docs/docsite/rst/community/collection_contributors/collection_integration_about.rst b/docs/docsite/rst/community/collection_contributors/collection_integration_about.rst new file mode 100644 index 0000000..d011fdb --- /dev/null +++ b/docs/docsite/rst/community/collection_contributors/collection_integration_about.rst @@ -0,0 +1,155 @@ +.. _collection_integration_tests_about: + +Understanding integration tests +================================= + +.. note:: + + Some collections do not have integration tests. + +Integration tests are functional tests of modules and plugins. +With integration tests, we check if a module or plugin satisfies its functional requirements. Simply put, we check that features work as expected and users get the outcome described in the module or plugin documentation. + +There are :ref:`two kinds of integration tests <collections_adding_integration_test>` used in collections: + +* integration tests that use Ansible roles +* integration tests that use ``runme.sh``. + +This section focuses on integration tests that use Ansible roles. + +Integration tests check modules with playbooks that invoke those modules. The tests pass standalone parameters and their combinations, check what the module or plugin reports with the :ref:`assert <ansible_collections.ansible.builtin.assert_module>` module, and the actual state of the system after each task. + +Integration test example +------------------------- + +Let's say we want to test the ``postgresql_user`` module invoked with the ``name`` parameter. We expect that the module will both create a user based on the provided value of the ``name`` parameter and will report that the system state has changed. We cannot rely on only what the module reports. To be sure that the user has been created, we query our database with another module to see if the user exists. + +.. code-block:: yaml + + - name: Create PostgreSQL user and store module's output to the result variable + community.postgresql.postgresql_user: + name: test_user + register: result + + - name: Check the module returns what we expect + assert: + that: + - result is changed + + - name: Check actual system state with another module, in other words, that the user exists + community.postgresql.postgresql_query: + query: SELECT * FROM pg_authid WHERE rolename = 'test_user' + register: query_result + + - name: We expect it returns one row, check it + assert: + that: + - query_result.rowcount == 1 + + +Details about integration tests +-------------------------------- + +The basic entity of an Ansible integration test is a ``target``. The target is an :ref:`Ansible role <playbooks_reuse_roles>` stored in the ``tests/integration/targets`` directory of the collection repository. The target role contains everything that is needed to test a module. + +The names of targets contain the module or plugin name that they test. Target names that start with ``setup_`` are usually executed as dependencies before module and plugin targets start execution. See :ref:`collection_creating_integration_tests` for details. + +To run integration tests, we use the ``ansible-test`` utility that is included in the ``ansible-core`` and ``ansible`` packages. See :ref:`collection_run_integration_tests` for details. After you finish your integration tests, see to :ref:`collection_quickstart` to learn how to submit a pull request. + +.. _collection_integration_prepare: + +Preparing for integration tests for collections +================================================= + +To prepare for developing integration tests: + +#. :ref:`Set up your local environment <collection_prepare_environment>`. + +#. Determine if integration tests already exist. + + .. code-block:: bash + + ansible-test integration --list-targets + + +If a collection already has integration tests, they are stored in ``tests/integration/targets/*`` subdirectories of the collection repository. + +If you use ``bash`` and the ``argcomplete`` package is installed with ``pip`` on your system, you can also get a full target list. + +.. code-block:: shell + + ansible-test integration <tab><tab> + +Alternately, you can check if the ``tests/integration/targets`` directory contains a corresponding directory with the same name as the module. For example, the tests for the ``postgresql_user`` module of the ``community.postgresql`` collection are stored in the ``tests/integration/targets/postgresql_user`` directory of the collection repository. If there is no corresponding target there, then that module does not have integration tests. In this case, consider adding integration tests for the module. See :ref:`collection_creating_integration_tests` for details. + + +.. _collection_integration_recommendations: + +Recommendations on coverage +=========================== + +Bugfixes +-------- + +Before fixing code, create a test case in an :ref:`appropriate test target<collection_integration_prepare>` that reproduces the bug provided by the issue reporter and described in the ``Steps to Reproduce`` issue section. :ref:`Run <collection_run_integration_tests>` the tests. + +If you failed to reproduce the bug, ask the reporter to provide additional information. The issue may be related to environment settings. Sometimes specific environment issues cannot be reproduced in integration tests, in that case, manual testing by issue reporter or other interested users is required. + +Refactoring code +---------------- + +When refactoring code, always check that related options are covered in a :ref:`corresponding test target<collection_integration_prepare>`. Do not assume if the test target exists, everything is covered. + +.. _collections_recommendation_modules: + +Covering modules / new features +------------------------------- + +When covering a module, cover all its options separately and their meaningful combinations. Every possible use of the module should be tested against: + +- Idempotency - Does rerunning a task report no changes? +- Check-mode - Does dry-running a task behave the same as a real run? Does it not make any changes? +- Return values - Does the module return values consistently under different conditions? + +Each test action has to be tested at least the following times: + +- Perform an action in check-mode if supported. This should indicate a change. +- Check with another module that the changes have ``not`` been actually made. +- Perform the action for real. This should indicate a change. +- Check with another module that the changes have been actually made. +- Perform the action again in check-mode. This should indicate ``no`` change. +- Perform the action again for real. This should indicate ``no`` change. + +To check a task: + +1. Register the outcome of the task as a variable, for example, ``register: result``. Using the :ref:`assert <ansible_collections.ansible.builtin.assert_module>` module, check: + + #. If ``- result is changed`` or not. + #. Expected return values. + +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: 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. + +Example: + +.. code-block:: yaml + + - name: Task to fail + abstract_module: + ... + register: result + + - name: Check the task fails and its error message + assert: + that: + - result is failed + - result.msg == 'Message we expect' + +Here is a summary: + +- Cover options and their sensible combinations. +- Check returned values. +- Cover check-mode if supported. +- Check a system state using other modules. +- Check when a module must fail and error messages. diff --git a/docs/docsite/rst/community/collection_contributors/collection_integration_add.rst b/docs/docsite/rst/community/collection_contributors/collection_integration_add.rst new file mode 100644 index 0000000..a4c8a10 --- /dev/null +++ b/docs/docsite/rst/community/collection_contributors/collection_integration_add.rst @@ -0,0 +1,250 @@ +.. _collection_creating_integration_tests: + +Creating new integration tests +================================= + +This section covers the following cases: + +- 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. + +In other words, there are currently no tests for a module regardless of whether the module exists or not. + +If the module already has tests, see :ref:`collection_updating_integration_tests`. + +Simplified example +-------------------- + +Here is a simplified abstract example. + +Let's say we are going to add integration tests to a new module in the ``community.abstract`` collection which interacts with some service. + +We :ref:`checked<collection_integration_prepare>` and determined that there are no integration tests at all. + +We should basically do the following: + +1. Install and run the service with a ``setup`` target. +2. Create a test target. +3. Add integration tests for the module. +4. :ref:`Run the tests<collection_run_integration_tests>`. +5. Fix the code and tests as needed, run the tests again, and repeat the cycle until they pass. + +.. note:: + + You can reuse the ``setup`` target when implementing other targets that also use the same service. + +1. Clone the collection to the ``~/ansible_collections/community.abstract`` directory on your local machine. + +2. From the ``~/ansible_collections/community.abstract`` directory, create directories for the ``setup`` target: + +.. code-block:: bash + + mkdir -p tests/integration/targets/setup_abstract_service/tasks + +3. Write all the tasks needed to prepare the environment, install, and run the service. + +For simplicity, let's imagine that the service is available in the native distribution repositories and no sophisticated environment configuration is required. + +Add the following tasks to the ``tests/integration/targets/setup_abstract_service/tasks/main.yml`` file to install and run the service: + +.. code-block:: yaml + + - name: Install abstract service + package: + name: abstract_service + + - name: Run the service + systemd: + name: abstract_service + state: started + +This is a very simplified example. + +4. Add the target for the module you are testing. + +Let's say the module is called ``abstract_service_info``. Create the following directory structure in the target: + +.. code-block:: bash + + mkdir -p tests/integration/targets/abstract_service_info/tasks + mkdir -p tests/integration/targets/abstract_service_info/meta + +Add all of the needed subdirectories. For example, if you are going to use defaults and files, add the ``defaults`` and ``files`` directories, and so on. The approach is the same as when you are creating a role. + +5. To make the ``setup_abstract_service`` target run before the module's target, add the following lines to the ``tests/integration/targets/abstract_service_info/meta/main.yml`` file. + +.. code-block:: yaml + + dependencies: + - setup_abstract_service + +6. Start with writing a single stand-alone task to check that your module can interact with the service. + +We assume that the ``abstract_service_info`` module fetches some information from the ``abstract_service`` and that it has two connection parameters. + +Among other fields, it returns a field called ``version`` containing a service version. + +Add the following to ``tests/integration/targets/abstract_service_info/tasks/main.yml``: + +.. code-block:: yaml + + - 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 to this port by default + register: result # This variable will contain the returned JSON including the server version + + - name: Test the output + assert: + that: + - result.version == '1.0.0' # Check version field contains what we expect + +7. :ref:`Run the tests<collection_run_integration_tests>` with the ``-vvv`` argument. + +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 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. + +``community.postgresql`` example +-------------------------------- + +Here is a real example of writing integration tests from scratch for the ``community.postgresql.postgresql_info`` module. + +For the sake of simplicity, we will create very basic tests which we will run using the Ubuntu 20.04 test container. + +We use ``Linux`` as a work environment and have ``git`` and ``docker`` installed and running. + +We also installed ``ansible-core``. + +1. Create the following directories in your home directory: + +.. code-block:: bash + + mkdir -p ~/ansible_collections/community + +2. Fork the `collection repository <https://github.com/ansible-collections/community.postgresql>`_ through the GitHub web interface. + +3. Clone the forked repository from your profile to the created path: + +.. code-block:: bash + + git clone https://github.com/YOURACC/community.postgresql.git ~/ansible_collections/community/postgresql + +If you prefer to use the SSH protocol: + +.. code-block:: bash + + git clone git@github.com:YOURACC/community.postgresql.git ~/ansible_collections/community/postgresql + +4. Go to the cloned repository: + +.. code-block:: bash + + cd ~/ansible_collections/community/postgresql + +5. Be sure you are in the default branch: + +.. code-block:: bash + + git status + +6. Checkout a test branch: + +.. code-block:: bash + + git checkout -b postgresql_info_tests + +7. Since we already have tests for the ``postgresql_info`` module, we will run the following command: + +.. code-block:: bash + + rm -rf tests/integration/targets/* + +With all of the targets now removed, the current state is as if we do not have any integration tests for the ``community.postgresql`` collection at all. We can now start writing integration tests from scratch. + +8. We will start with creating a ``setup`` target that will install all required packages and will launch PostgreSQL. Create the following directories: + +.. code-block:: bash + + mkdir -p tests/integration/targets/setup_postgresql_db/tasks + +9. Create the ``tests/integration/targets/setup_postgresql_db/tasks/main.yml`` file and add the following tasks to it: + +.. code-block:: yaml + + - name: Install required packages + package: + name: + - apt-utils + - postgresql + - postgresql-common + - python3-psycopg2 + + - name: Initialize PostgreSQL + shell: . /usr/share/postgresql-common/maintscripts-functions && set_system_locale && /usr/bin/pg_createcluster -u postgres 12 main + args: + creates: /etc/postgresql/12/ + + - name: Start PostgreSQL service + ansible.builtin.service: + name: postgresql + state: started + +That is enough for our very basic example. + +10. Then, create the following directories for the ``postgresql_info`` target: + +.. code-block:: bash + + mkdir -p tests/integration/targets/postgresql_info/tasks tests/integration/targets/postgresql_info/meta + +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 + + dependencies: + - setup_postgresql_db + +12. Now we are ready to add our first test task for the ``postgresql_info`` module. Create the ``tests/integration/targets/postgresql_info/tasks/main.yml`` file and add the following code to it: + +.. code-block:: yaml + + - name: Test postgresql_info module + become: true + become_user: postgres + community.postgresql.postgresql_info: + login_user: postgres + login_db: postgres + register: result + + - name: Check the module returns what we expect + assert: + that: + - result is not changed + - result.version.major == 12 + - result.version.minor == 8 + +In the first task, we run the ``postgresql_info`` module to fetch information from the database we installed and launched with the ``setup_postgresql_db`` target. We are saving the values returned by the module into the ``result`` variable. + +In the second task, we check the ``result`` variable, which is what the first task returned, with the ``assert`` module. We expect that, among other things, the result has the version and reports that the system state has not been changed. + +13. Run the tests in the Ubuntu 20.04 docker container: + +.. code-block:: bash + + ansible-test integration postgresql_info --docker ubuntu2004 -vvv + +The tests should pass. If we look at the output, we should see something like the following: + +.. code-block:: shell + + TASK [postgresql_info : Check the module returns what we expect] *************** + ok: [testhost] => { + "changed": false, + "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 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. diff --git a/docs/docsite/rst/community/collection_contributors/collection_integration_running.rst b/docs/docsite/rst/community/collection_contributors/collection_integration_running.rst new file mode 100644 index 0000000..64e610d --- /dev/null +++ b/docs/docsite/rst/community/collection_contributors/collection_integration_running.rst @@ -0,0 +1,32 @@ +.. _collection_run_integration_tests: + +Running integration tests +============================ + +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. + +After you change the tests, you can run them with the following command: + +.. code-block:: text + + ansible-test integration <target_name> --docker <distro> + +The ``target_name`` is a test role directory containing the tests. For example, if the test files you changed are stored in the ``tests/integration/targets/postgresql_info/`` directory and you want to use the ``fedora34`` container image, then the command will be: + +.. code-block:: bash + + ansible-test integration postgresql_info --docker fedora34 + +You can use the ``-vv`` or ``-vvv`` argument if you need more detailed output. + +In the examples above, the ``fedora34`` test image will be automatically downloaded and used to create and run a test container. + +See the :ref:`list of supported container images <test_container_images>`. + +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. + +.. note:: + + If you have any difficulties with writing or running integration tests or you are not sure if the case can be covered, submit your pull request without the tests. Other contributors can help you with them later if needed. diff --git a/docs/docsite/rst/community/collection_contributors/collection_integration_tests.rst b/docs/docsite/rst/community/collection_contributors/collection_integration_tests.rst new file mode 100644 index 0000000..9eef463 --- /dev/null +++ b/docs/docsite/rst/community/collection_contributors/collection_integration_tests.rst @@ -0,0 +1,36 @@ +.. _collection_integration_tests: + + +***************************************** +Adding integration tests to a collection +***************************************** + +This section describes the steps to add integration tests to a collection and how to run them locally using the ``ansible-test`` command. + +.. toctree:: + :maxdepth: 1 + + collection_integration_about + collection_integration_updating + collection_integration_running + collection_integration_add + + +.. seealso:: + + :ref:`testing_units_modules` + Unit testing Ansible modules + `pytest <https://docs.pytest.org/en/latest/>`_ + Pytest framework documentation + :ref:`developing_testing` + Ansible Testing Guide + :ref:`collection_unit_tests` + Unit testing for collections + :ref:`testing_integration` + Integration tests guide + :ref:`testing_collections` + Testing collections + :ref:`testing_resource_modules` + Resource module integration tests + :ref:`collection_pr_test` + How to test a pull request locally diff --git a/docs/docsite/rst/community/collection_contributors/collection_integration_updating.rst b/docs/docsite/rst/community/collection_contributors/collection_integration_updating.rst new file mode 100644 index 0000000..46d18c0 --- /dev/null +++ b/docs/docsite/rst/community/collection_contributors/collection_integration_updating.rst @@ -0,0 +1,169 @@ +.. _collection_updating_integration_tests: + +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 or import a separate test file. +You can use one of the existing test files as a draft. + +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 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 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. + +Here is an example. + +Let's say someone reported an issue in the ``community.postgresql`` collection that when users pass a name containing underscores to the ``postgresql_user`` module, the module fails. + +We cloned the collection repository to the ``~/ansible_collections/community/postgresql`` directory and :ref:`prepared our environment <collection_prepare_environment>`. From the collection's root directory, we run ``ansible-test integration --list-targets`` and it shows a target called ``postgresql_user``. It means that we already have tests for the module. + +We start with reproducing the bug. + +First, we look into the ``tests/integration/targets/postgresql_user/tasks/main.yml`` file. In this particular case, the file imports other files from the ``tasks`` directory. The ``postgresql_user_general.yml`` looks like an appropriate one to add our tests. + +.. code-block:: yaml + + # General tests: + - import_tasks: postgresql_user_general.yml + when: postgres_version_resp.stdout is version('9.4', '>=') + +We will add the following code to the file. + +.. code-block:: yaml + + # https://github.com/ansible-collections/community.postgresql/issues/NUM + - name: Test user name containing underscore + community.postgresql.postgresql_user: + name: underscored_user + register: result + + - name: Check the module returns what we expect + assert: + that: + - result is changed + + - name: Query the database if the user exists + community.postgresql.postgresql_query: + query: SELECT * FROM pg_authid WHERE rolename = 'underscored_user' + register: result + + - name: Check the database returns one row + assert: + that: + - result.query_result.rowcount == 1 + +When we :ref:`run the tests<collection_run_integration_tests>` with ``postgresql_user`` as a test target, this task must fail. + +Now that we have our failing test; we will fix the bug and run the same tests again. Once the tests pass, we will consider the bug fixed and will submit a pull request. + +When adding a new feature +------------------------- + +.. note:: + + 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 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: + +1. :ref:`Determine if integration tests for the module exists<collection_integration_prepare>`. If they do not, see :ref:`collection_creating_integration_tests`. +2. Find an appropriate file for your tests within the ``tests/integration/targets/<target_name>/tasks`` directory. +3. Cover your feature with tests. Refer to the :ref:`Recommendations on coverage<collection_integration_recommendations>` section for details. +4. :ref:`Run the tests<collection_run_integration_tests>`. +5. If they fail, see the test output for details. Fix your code or tests and run the tests again. +6. Repeat steps 4-5 until the tests pass. + +Here is an example. + +Let's say we decided to add a new option called ``add_attribute`` to the ``postgresql_user`` module of the ``community.postgresql`` collection. + +The option is boolean. If set to ``yes``, it adds an additional attribute to a database user. + +We cloned the collection repository to the ``~/ansible_collections/community/postgresql`` directory and :ref:`prepared our environment<collection_integration_prepare>`. From the collection's root directory, we run ``ansible-test integration --list-targets`` and it shows a target called ``postgresql_user``. Therefore, we already have some tests for the module. + +First, we look at the ``tests/integration/targets/<target_name>/tasks/main.yml`` file. In this particular case, the file imports other files from the ``tasks`` directory. The ``postgresql_user_general.yml`` file looks like an appropriate one to add our tests. + +.. code-block:: yaml + + # General tests: + - import_tasks: postgresql_user_general.yml + when: postgres_version_resp.stdout is version('9.4', '>=') + +We will add the following code to the file. + +.. code-block:: yaml + + # https://github.com/ansible-collections/community.postgresql/issues/NUM + # We should also run the same tasks with check_mode: yes. We omit it here for simplicity. + - name: Test for new_option, create new user WITHOUT the attribute + community.postgresql.postgresql_user: + name: test_user + register: result + + - name: Check the module returns what we expect + assert: + that: + - result is changed + + - name: Query the database if the user exists but does not have the attribute (it is NULL) + community.postgresql.postgresql_query: + query: SELECT * FROM pg_authid WHERE rolename = 'test_user' AND attribute = NULL + register: result + + - name: Check the database returns one row + assert: + that: + - result.query_result.rowcount == 1 + + - name: Test for new_option, create new user WITH the attribute + community.postgresql.postgresql_user: + name: test_user + register: result + + - name: Check the module returns what we expect + assert: + that: + - result is changed + + - name: Query the database if the user has the attribute (it is TRUE) + community.postgresql.postgresql_query: + query: SELECT * FROM pg_authid WHERE rolename = 'test_user' AND attribute = 't' + register: result + + - name: Check the database returns one row + assert: + that: + - result.query_result.rowcount == 1 + +Then we :ref:`run the tests<collection_run_integration_tests>` with ``postgresql_user`` passed as a test target. + +In reality, we would alternate the tasks above with the same tasks run with the ``check_mode: yes`` option to be sure our option works as expected in check-mode as well. See :ref:`Recommendations on coverage<collection_integration_recommendations>` for details. + +If we expect a task to fail, we use the ``ignore_errors: true`` option and check that the task actually failed and returned the message we expect: + +.. code-block:: yaml + + - name: Test for fail_when_true option + community.postgresql.postgresql_user: + name: test_user + fail_when_true: true + register: result + ignore_errors: true + + - name: Check the module fails and returns message we expect + assert: + that: + - result is failed + - result.msg == 'The message we expect' diff --git a/docs/docsite/rst/community/collection_contributors/collection_release_with_branches.rst b/docs/docsite/rst/community/collection_contributors/collection_release_with_branches.rst new file mode 100644 index 0000000..f8ba7ed --- /dev/null +++ b/docs/docsite/rst/community/collection_contributors/collection_release_with_branches.rst @@ -0,0 +1,341 @@ +.. _collection_release_with_branches: + +Releasing collections with release branches +============================================ + +Collections MUST follow the `semantic versioning <https://semver.org/>`_ rules. See :ref:`releasing_collections` for high-level details. + +.. contents:: + :local: + + +Release planning and announcement +---------------------------------- + +#. Announce your intention to release the collection in a corresponding pinned release issue/community pinboard of the collection and in the ``#ansible-community`` `Matrix/IRC channel <https://docs.ansible.com/ansible/devel/community/communication.html#real-time-chat>`_. Repeat the announcement in any other dedicated channels if they exist. + +#. Ensure all the other repository maintainers are informed about the time of the following release. + + +Releasing major collection versions +------------------------------------- + +The new version is assumed to be ``X.0.0``. + +1. Make sure that ``galaxy.yml`` contains the correct version number ``X.0.0``. If that is not the case, create a PR to update it. This will make sanity tests fail for all deprecations that have to be removed in ``X.0.0``, so this is potentially a lot of work and should have been done weeks before the major release. + +2. Check the collection for deprecations that are planned for removal in the major release that were not reported by the sanity tests. Use past changelogs or run ``grep -r `X.0.0` plugins/`` in the repository. + +3. If you are going to release the ``community.general`` and ``community.network`` collections, create a new ``backport-X`` label in the corresponding repositories. Copy the styles and descriptions from the corresponding existing labels. + +4. Ensure you are in a default branch in your local fork. These examples use ``main``. + + .. code-block:: bash + + git status + git checkout main # if needed + + +5. Update your local fork: + + .. code-block:: bash + + git pull --rebase upstream main + + +Creating the release branch +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +1. Create a branch ``stable-X``. Replace ``X`` with a correct number and push it to the **upstream** repository, NOT to the ``origin``.: + + .. code-block:: bash + + git branch stable-X main + git push upstream stable-X + + +2. Create and checkout to another branch from the ``main`` branch: + + .. code-block:: bash + + git checkout -b update_repo + + +3. Update the version in ``galaxy.yml`` in the branch to the next **expected** version, for example, ``X.1.0``. + + +Creating the changelogs +^^^^^^^^^^^^^^^^^^^^^^^^ + +1. Replace ``changelogs/changelog.yml`` with: + + .. code-block:: yaml + + ancestor: X.0.0 + releases: {} + + +2. Remove all changelog fragments from ``changelogs/fragments/``. Removing the changelog fragments ensures that every major release has a changelog describing changes since the last major release. + +3. Add and commit all the changes made. Push the branch to the ``origin`` repository. + +4. Create a pull request in the collection repository. If CI tests pass, merge the pull request since the ``main`` branch is expecting changes for the next minor/major versions + +5. Switch to the ``stable-X`` branch. + +6. In the ``stable-X`` branch, verify that ``galaxy.yml`` contains the correct version number ``X.0.0``. + +7. In the ``stable-X`` branch, ensure that ``changelogs/changelog.yml`` contains a correct ancestor's version: + + .. code-block:: yaml + + ancestor: X-1.0.0 + releases: {} + + +8. In the ``stable-X`` branch, add a changelog fragment ``changelogs/fragments/X.0.0.yml`` with the content: + + .. code-block:: yaml + + release_summary: |- + Write some text here that should appear as the release summary for this version. + The format is reStructuredText, but not a list as for regular changelog fragments. + This text will be inserted into the changelog. + + + For example: + + .. code-block:: yaml + + release_summary: This is release 2.0.0 of ``community.foo``, released on YYYY-MM-DD. + + +9. In the ``stable-X`` branch, generate the changelogs: + + .. code-block:: bash + + antsibull-changelog release --cummulative-release + + +10. In the ``stable-X`` branch, verify that the ``CHANGELOG.rst`` looks as expected. + +11. In the ``stable-X`` branch, update ``README.md`` so that the changelog link points to ``/tree/stable-X/`` and no longer to ``/tree/main/``, and change badges respectively, for example, in case of AZP, add ``?branchName=stable-X`` to the AZP CI badge (https://dev.azure.com/ansible/community.xxx/_apis/build/status/CI?branchName=stable-X). + +12. In the ``stable-X`` branch, add, commit, and push changes to ``README.md``, ``CHANGELOG.rst`` and ``changelogs/changelog.yaml``, and potentially deleted/archived fragments to the **upstream** repository, NOT to the ``origin``. + + +Publishing the collection +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +1. In the ``stable-X`` branch, add an annotated tag to the last commit with the collection version ``X.0.0``. Pushing this tag to the ``upstream`` repository will make Zuul publish the collection on `Ansible Galaxy <https://galaxy.ansible.com/>`_. + + .. code-block:: bash + + git tag -n # see current tags and their comments + git tag -a NEW_VERSION -m "comment here" # the comment can be, for example, "community.foo: 2.0.0" + git push upstream NEW_VERSION + + +2. If the collection uses `Zuul <https://github.com/ansible/zuul-config/blob/master/README.rst>`_ for publishing its releases, wait until the new version is published on the collection's `Ansible Galaxy <https://galaxy.ansible.com/>`_ page. It will appear in a list of tarballs available to download. + +3. If the release tarball did not appear within several hours after pushing the tag, try to re-tag the release commit and push the tag again. In the ``stable-X`` branch being at the release commit: + + .. code-block:: bash + + git tag --delete NEW_VERSION + git push upstream :NEW_VERSION + git tag -a NEW_VERSION -m "comment here" # the comment can be, for example, "community.foo: 2.0.0" + git push upstream NEW_VERSION + + +4. Add a GitHub release for the new tag. The title should be the version and content, such as - ``See https://github.com/ansible-collections/community.xxx/blob/stable-X/CHANGELOG.rst for all changes``. + +5. Announce the release through the `Bullhorn Newsletter <https://github.com/ansible/community/wiki/News#the-bullhorn>`_. + +6. Announce the release in the pinned release issue/community pinboard of the collection and in the ``#ansible-community`` `Matrix/Libera.Chat IRC channel <https://docs.ansible.com/ansible/devel/community/communication.html#real-time-chat>`_. + +7. In the ``stable-X`` branch, update the version in ``galaxy.yml`` to the next **expected** version, for example, ``X.1.0``. Add, commit and push to the **upstream** repository. + + +Releasing minor collection versions +------------------------------------- + +The new version is assumed to be ``X.Y.0``. All changes that should go into it are expected to be previously backported from the default branch to the ``stable-X`` branch. + +Creating the changelogs +^^^^^^^^^^^^^^^^^^^^^^^^ + +1. In the ``stable-X`` branch, make sure that ``galaxy.yml`` contains the correct version number ``X.Y.0``. If not, update it. + +2. In the ``stable-X`` branch, add a changelog fragment ``changelogs/fragments/X.Y.0.yml`` with content: + + .. code-block:: yaml + + release_summary: |- + Write some text here that should appear as the release summary for this version. + The format is reStructuredText, but not a list as for regular changelog fragments. + This text will be inserted into the changelog. + + +3. In the ``stable-X`` branch, run: + + .. code-block:: bash + + antsibull-changelog release + + +4. In the ``stable-X`` branch, verify that ``CHANGELOG.rst`` looks as expected. + +5. In the ``stable-X`` branch, add, commit, and push changes to ``CHANGELOG.rst`` and ``changelogs/changelog.yaml``, and potentially deleted/archived fragments to the **upstream** repository, NOT to the origin. + + +Publishing the collection +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +1. In the ``stable-X`` branch, add an annotated tag to the last commit with the collection version ``X.Y.0``. Pushing this tag to the ``upstream`` repository will make Zuul publish the collection on `Ansible Galaxy <https://galaxy.ansible.com/>`_. + + .. code-block:: bash + + git tag -n # see current tags and their comments + git tag -a NEW_VERSION -m "comment here" # the comment can be, for example, "community.foo: 2.1.0" + git push upstream NEW_VERSION + + +2. Wait until the new version is published on the collection's `Ansible Galaxy <https://galaxy.ansible.com/>`_ page. The published version will appear in a list of tarballs available to download. + +3. Add a GitHub release for the new tag. The title should be the version and content, such as - ``See https://github.com/ansible-collections/community.xxx/blob/stable-X/CHANGELOG.rst for all changes``. + +4. Announce the release through the `Bullhorn Newsletter <https://github.com/ansible/community/wiki/News#the-bullhorn>`_. + +5. Announce the release in the pinned release issue/community pinboard of the collection and in the ``#ansible-community`` `Matrix/IRC channel <https://docs.ansible.com/ansible/devel/community/communication.html#real-time-chat>`_. Additionally, you can announce it using GitHub's Releases system. + +6. In the ``stable-X`` branch, update the version in ``galaxy.yml`` to the next **expected** version, for example, if you have released ``X.1.0``, the next expected version could be ``X.2.0``. Add, commit and push to the **upstream** repository. + +7. Checkout to the ``main`` branch. + +8. In the ``main`` branch: + + #. If more minor versions are released before the next major version, update the version in ``galaxy.yml`` to ``X.(Y+1).0`` as well. Create a dedicated pull request and merge. + + #. If the next version will be a new major version, create a pull request where you update the version in ``galaxy.yml`` to ``(X+1).0.0``. Note that the sanity tests will most likely fail since there will be deprecations with removal scheduled for ``(X+1).0.0``, which are flagged by the tests. + + For every such deprecation, decide: + + * Whether to remove them now. For example you remove the complete ``modules/plugins`` or you remove redirects. + * Whether to add ignore entries to the corresponding ``tests/sanity/ignore-*.txt`` file and create issues, for example for removed features in ``modules/plugins``. + + Once the CI tests pass, merge the pull request. Make sure that this pull request is merged not too much later after the release + for ``version_added`` sanity tests not to expect the wrong version for the new feature pull request. + +.. note:: + + It makes sense to already do some removals in the days before the release. These removals must happen in the main branch and must not be backported. + + +Releasing patch versions +------------------------- + +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. + +Releasing when more minor versions are expected +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +1. Checkout the ``X.Y.z`` tag. + +2. Update ``galaxy.yml`` so that the version is ``X.Y.Z``. Add and commit. + +3. Cherry-pick all changes from ``stable-X`` that were added after ``X.Y.z`` and should go into ``X.Y.Z``. + +4. Add a changelog fragment ``changelogs/fragments/X.Y.Z.yml`` with content: + + .. code-block:: yaml + + release_summary: |- + Write some text here that should appear as the release summary for this version. + The format is reStructuredText but not a list as for regular changelog fragments. + This text will be inserted into the changelog. + + Add to git and commit. + +5. Generate the changelogs. + +.. code-block:: bash + + antsibull-changelog release + +6. Verify that ``CHANGELOG.rst`` looks as expected. + +7. Add and commit changes to ``CHANGELOG.rst`` and ``changelogs/changelog.yaml``, and potentially deleted/archived fragments. + +**Publishing the collection** + + +1. Add an annotated tag to the last commit with the collection version ``X.Y.Z``. Pushing this tag to the ``upstream`` repository will make Zuul publish the collection on `Ansible Galaxy <https://galaxy.ansible.com/>`_. + + .. code-block:: bash + + git tag -n # see current tags and their comments + git tag -a NEW_VERSION -m "comment here" # the comment can be, for example, "community.foo: 2.1.1" + git push upstream NEW_VERSION + + +2. Wait until the new version is published on the collection's `Ansible Galaxy <https://galaxy.ansible.com/>`_ page. It will appear in a list of tarballs available to download. + +3. Add a GitHub release for the new tag. The title should be the version and content, such as - ``See https://github.com/ansible-collections/community.xxx/blob/stable-X/CHANGELOG.rst for all changes``. + + .. note:: + + The data for this release is only contained in a tag, and not in a branch, in particular not in ``stable-X``. + This is deliberate, since the next minor release ``X.(Y+1).0`` already contains the changes for ``X.Y.Z`` as well, since these were cherry-picked from ``stable-X``. + + +4. Announce the release through the `Bullhorn Newsletter <https://github.com/ansible/community/wiki/News#the-bullhorn>`_. + +5. Announce the release in the pinned release issue/community pinboard of the collection and in the ``#ansible-community`` `Matrix/IRC channel <https://docs.ansible.com/ansible/devel/community/communication.html#real-time-chat>`. + + +Releasing when no more minor versions are expected +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +1. In the ``stable-X`` branch, make sure that ``galaxy.yml`` contains the correct version number ``X.Y.Z``. If not, update it! + +2. In the ``stable-X`` branch, add a changelog fragment ``changelogs/fragments/X.Y.Z.yml`` with content: + + .. code-block:: yaml + + release_summary: |- + Write some text here that should appear as the release summary for this version. + The format is reStructuredText, but not a list as for regular changelog fragments. + This text will be inserted into the changelog. + + +3. Generate the changelogs in the ``stable-X`` branch. + + .. code-block:: bash + + antsibull-changelog release + + +4. In the ``stable-X`` branch, verify that ``CHANGELOG.rst`` looks as expected. + +5. In the ``stable-X`` branch, add, commit, and push changes to ``CHANGELOG.rst`` and ``changelogs/changelog.yaml``, and potentially deleted/archived fragments to the **upstream** repository, NOT to the origin. + +**Publishing the collection** + + +1. In the ``stable-X`` branch, add an annotated tag to the last commit with the collection version ``X.Y.Z``. Pushing this tag to the ``upstream`` repository will make Zuul publish the collection on `Ansible Galaxy <https://galaxy.ansible.com/>`_. + + .. code-block:: bash + + git tag -n # see current tags and their comments + git tag -a NEW_VERSION -m "comment here" # the comment can be, for example, "community.foo: 2.1.1" + git push upstream NEW_VERSION + + +2. Wait until the new version is published on the collection's `Ansible Galaxy <https://galaxy.ansible.com/>`_ page. It will appear in a list of tarballs available to download. + +3. Add a GitHub release for the new tag. Title should be the version and content, such as: ``See https://github.com/ansible-collections/community.xxx/blob/stable-X/CHANGELOG.rst for all changes``. + +4. Announce the release through the `Bullhorn Newsletter <https://github.com/ansible/community/wiki/News#the-bullhorn>`_. + +5. Announce the release in the pinned issue/community pinboard of the collection and in the ``#ansible-community`` `Matrix/IRC channel <https://docs.ansible.com/ansible/devel/community/communication.html#real-time-chat>`_. diff --git a/docs/docsite/rst/community/collection_contributors/collection_release_without_branches.rst b/docs/docsite/rst/community/collection_contributors/collection_release_without_branches.rst new file mode 100644 index 0000000..4cef33f --- /dev/null +++ b/docs/docsite/rst/community/collection_contributors/collection_release_without_branches.rst @@ -0,0 +1,115 @@ + +.. _collection_release_without_branches: + +Releasing collections without release branches +=============================================== + +Since no release branches are used, this section does not distinguish between releasing a major, minor, or patch version. + +.. contents:: + :local: + +Release planning and announcement +---------------------------------- + +#. Examine the collection to determine if there are merged changes to release. + +#. According to the changes made, choose an appropriate release version number. Keep in mind that the collections must follow the `semantic versioning <https://semver.org/>`_ rules. See :ref:`collection_versioning_and_deprecation` for details. + +#. Announce your intention to release the collection in a corresponding pinned release issue or community pinboard of the collection and in the ``community`` :ref:`Matrix/IRC channel <communication_irc>`. + +Creating the release branch +---------------------------- + +1. Ensure you are in a default branch in your local fork. We use ``main`` in the following examples. + + .. code:: bash + + git status + git checkout main # if needed + + +2. Update your local fork: + + .. code:: bash + + git pull --rebase upstream main + + +3. Checkout a new release branch from the default branch: + + .. code:: bash + + git checkout -b release_branch + +4. Ensure the ``galaxy.yml`` contains the correct release version number. + + +Generating the changelog +------------------------- + +1. Add a changelog fragment ``changelogs/fragments/X.Y.Z.yml`` with content: + + .. code:: yaml + + release_summary: |- + Write some text here that should appear as the release summary for this version. + The format is reStructuredText, but not a list as for regular changelog fragments. + This text will be inserted into the changelog. + + For example: + + .. code:: yaml + + release_summary: |- + This is the minor release of the ``community.mysql`` collection. + This changelog contains all changes to the modules and plugins in this collection + that have been made after the previous release. + + +2. If the content was recently moved from another collection (for example, migrating a module from one collection to another), ensure you have all related changelog fragments in the ``changelogs/fragments`` directory. If not, copy them previously. + +3. Run ``antsibull-changelog release --reload-plugins`` . This package should previously be installed with ``pip install antsibull-changelog``. + +4. Verify that the ``CHANGELOG.rst`` looks as expected. + +5. Commit and push changes to the ``CHANGELOG.rst`` and ``changelogs/changelog.yaml``, and potentially deleted/archived fragments to the ``origin`` repository's ``release_branch``. + + .. code:: bash + + git commit -a -m "Release VERSION commit" + git push origin release_branch + + +6. Create a pull request in the collection repository. If CI tests pass, merge it. + +7. Checkout the default branch and pull the changes: + + .. code:: bash + + git checkout main + git pull --rebase upstream main + + +Publish the collection +----------------------------------- + +1. Add an annotated tag to the release commit with the collection version. Pushing this tag to the ``upstream`` repository will make Zuul publish the collection on `Ansible Galaxy <https://galaxy.ansible.com/>`_. + + .. code:: bash + + git tag -n # see current tags and their comments + git tag -a NEW_VERSION -m "comment here" # the comment can be, for example, "community.postgresql: 1.2.0" + git push upstream NEW_VERSION + + + +2. Wait until the new version is published on the collection's `Ansible Galaxy <https://galaxy.ansible.com/>`_ page. It will appear in a list of tarballs available to download. + +3. Update the version in the ``galaxy.yml`` file to the next **expected** version. Add, commit, and push to the ``upstream``'s default branch. + +4. Add a GitHub release for the new tag. Title should be the version and content ``See https://github.com/ansible-collections/community.xxx/blob/main/CHANGELOG.rst for all changes``. + +5. Announce the release through the `Bullhorn Newsletter issue <https://github.com/ansible/community/wiki/News#the-bullhorn>`_. + +6. Announce the release in the pinned release issue/community pinboard of the collection mentioned in step 3 and in the ``community`` :ref:`Matrix/IRC channel <communication_irc>`. diff --git a/docs/docsite/rst/community/collection_contributors/collection_releasing.rst b/docs/docsite/rst/community/collection_contributors/collection_releasing.rst new file mode 100644 index 0000000..481208b --- /dev/null +++ b/docs/docsite/rst/community/collection_contributors/collection_releasing.rst @@ -0,0 +1,106 @@ + +.. _releasing_collections: +.. _Releasing: + +Releasing collections +====================== + +Collection maintainers release all supported stable versions of the collections regularly, +provided that there have been enough changes merged to release. + + +.. contents:: + :local: + +Preparing to release a collection +-------------------------------------------- + + +The collections under the `ansible-collections organization <https://github.com/ansible-collections>`_ follow `semantic versioning <https://semver.org/>`_ when releasing. See :ref:`collection_versioning_and_deprecation` for details. + +To prepare for a release, a collection must have: + +* A publicly available policy of releasing, versioning, and deprecation. This can be, for example, written in its README or in a dedicated pinned issue. +* A pinned issue when its release managers inform the community about planned or completed releases. This can be combined with the release policy issue mentioned above. +* A :ref:`changelog <collection_changelogs>`. +* Releases of the collection tagged in the collection's repository. +* CI pipelines up and running. This can be implemented by using GitHub Actions, Azure Pipelines, Zuul. +* All CI tests running against a commit that releases the collection. If they do not pass, the collection MUST NOT be released. + +See :ref:`including_collection_ansible` if you plan on adding a new collection to the Ansible package. + +.. note:: + + Your collection must pass ``ansible-test sanity`` tests. See :ref:`testing_collections` for details. + + +.. _collection_versioning_and_deprecation: + +Collection versioning and deprecation +-------------------------------------- + +.. note:: + + Collections MUST adhere to `semantic versioning <https://semver.org/>`_. + +To preserve backward compatibility for users, every Ansible minor version series (5.1.x, 5.2.x, and so on) will keep the major version of a collection constant. For example, if Ansible 5.0.0 includes ``community.general`` 4.0.2, then each Ansible 5.X.x release will include the latest ``community.general`` 4.y.z release available at build time. Ansible 5.x.x will **never** include a ``community.general`` 5.y.x release, even if it is available. Major collection version changes will be included in the next Ansible major release (6.0.0 in this case). +Ensure that the current major release of your collection included in 6.0.0 receives at least bugfixes as long as new Ansible 6.X.X releases are produced. + +Since new minor releases are included, you can include new features, modules and plugins. You must make sure that you do not break backwards compatibility. See `semantic versioning <https://semver.org/>`_. for more details. This means in particular: + +* You can fix bugs in **patch** releases but not add new features or deprecate things. +* You can add new features and deprecate things in **minor** releases, but not remove things or change behavior of existing features. +* You can only remove things or make breaking changes in **major** releases. + +Ensure that if a deprecation is added in a collection version that is included in 5.x.y, the removal itself will only happen in a collection version included in 7.0.0 or later. +Ensure that the policy of releasing, versioning, and deprecation is announced to contributors and users in some way. For an example of how to do this, see `the announcement in community.general <https://github.com/ansible-collections/community.general/issues/582>`_. You could also do this in the collection README file. + +.. _collection_changelog: + +Collection changelogs +---------------------- + +Collections MUST include a changelog. To give a consistent feel for changelogs across collections and ensure changelogs exist for collections included in the ``ansible`` package, we suggest you use `antsibull-changelog <https://github.com/ansible-community/antsibull-changelog>`_ to maintain and generate this. + +Before releasing, verify the following for your changelogs: + +* All merged pull requests since the last release, except ones related to documentation and new modules/plugins, have :ref:`changelog fragments <collection_changelog_fragments>`. +* New module and plugin pull requests, except jinja2 test and filter plugins, do **not** need a changelog fragment, they are auto-detected by the changelog generator by their ``version_added`` value. +* All the fragments follow the :ref:`changelog entry format <collection_changelogs_how_to_format>`. + +Options for releasing a collection +----------------------------------- + +There are several approaches on how to release a collection. If you are not aware of which approach to use, ask in the ``#ansible-community`` IRC channel or the ``community`` Matrix channel. + +This section assumes that publishing the collection is done with `Zuul <https://github.com/ansible/project-config>`_ and that `antsibull-changelog <https://github.com/ansible-community/antsibull-changelog>`_ is used for the changelog. + +Releasing without release branches +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Use releasing without release branches when: + +* There are no prior major releases of the collection. +* There are no breaking changes introduced since the ``1.0.0`` release of the collection. + +See :ref:`collection_release_without_branches` for details. + +When there is a need to introduce breaking changes, you can switch to the next approach. + +Hybrid approach +^^^^^^^^^^^^^^^^^^^^^ + +In this approach, releases for the current major version are made from the ``main`` branch, while new releases for older major versions are made from release branches for these versions. + +Releasing with release branches +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Use releasing with release branches when breaking changes have been introduced. This approach is usually only used by the large community collections, ``community.general`` and ``community.network``. + +See :ref:`collection_release_with_branches` for details. + +.. toctree:: + :maxdepth: 1 + + collection_release_without_branches + collection_release_with_branches diff --git a/docs/docsite/rst/community/collection_contributors/collection_reviewing.rst b/docs/docsite/rst/community/collection_contributors/collection_reviewing.rst new file mode 100644 index 0000000..0eb203b --- /dev/null +++ b/docs/docsite/rst/community/collection_contributors/collection_reviewing.rst @@ -0,0 +1,74 @@ +.. _review_checklist: + +Review checklist for collection PRs +==================================== + +Use this section as a checklist reminder of items to review when you review a collection PR. + +Reviewing bug reports +---------------------- + +When users report bugs, verify the behavior reported. Remember always to be kind with your feedback. + +* 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 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 that the suggested changes do not: + +* Unnecessarily break backward compatibility. +* Bring more harm than value. +* Introduce non-idempotent solutions. +* Duplicate already existing features (inside or outside the collection). +* Violate the :ref:`Ansible development conventions <module_conventions>`. + + +Other standards to check for in a PR include: + +* A pull request MUST NOT contain a mix of bug fixes 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. + * For jinja2 filter and test plugins, check out the `special syntax for changelog fragments <https://github.com/ansible-community/antsibull-changelog/blob/main/docs/changelogs.rst#adding-new-roles-playbooks-test-and-filter-plugins>`_. + * The changelog content contains useful information for end users of the collection. + +* If new files are added with the pull request, they follow the `licensing rules <https://github.com/ansible-collections/overview/blob/main/collection_requirements.rst#licensing>`_. +* The changes follow the :ref:`Ansible documentation standards <developing_modules_documenting>` and the :ref:`style_guide`. +* The changes follow the :ref:`Development conventions <developing_modules_best_practices>`. +* 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 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). + +* FQCNs are used for ``extends_documentation_fragment:``, unless the author is referring to doc_fragments from ansible-core. +* New features have corresponding examples in the :ref:`examples_block`. +* Return values are documented in the :ref:`return_block`. + + +Review tests in the PR +---------------------- +Review the following if tests are applicable and possible to implement for the changes included in the PR: + + +* Where applicable, the pull request has :ref:`testing_integration` and :ref:`testing_units`. +* All changes are covered. For example, a bug case or a new option separately and in sensible combinations with other options. +* Integration tests cover ``check_mode`` if supported. +* Integration tests check the actual state of the system, not only what the module reports. For example, if the module actually changes a file, check that the file was changed by using the ``ansible.builtin.stat`` module.. +* Integration tests check return values, if applicable. + + +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 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. + diff --git a/docs/docsite/rst/community/collection_contributors/collection_test_pr_locally.rst b/docs/docsite/rst/community/collection_contributors/collection_test_pr_locally.rst new file mode 100644 index 0000000..7b01e2d --- /dev/null +++ b/docs/docsite/rst/community/collection_contributors/collection_test_pr_locally.rst @@ -0,0 +1,67 @@ +.. _collection_pr_test: + +**************************** +How to test a collection PR +**************************** + +Reviewers and issue authors can verify a PR fixes the reported bug by testing the PR locally. + +.. contents:: + :local: + +.. _collection_prepare_environment: + +Prepare your environment +======================== + +We assume that you use Linux as a work environment (you can use a virtual machine as well) and have ``git`` installed. + + +1. :ref:`Install Ansible <installation_guide>` or ansible-core. + +2. Create the following directories in your home directory: + + .. code:: bash + + mkdir -p ~/ansible_collections/NAMESPACE/COLLECTION_NAME + + For example, if the collection is ``community.general``: + + .. code:: bash + + mkdir -p ~/ansible_collections/community/general + + If the collection is ``ansible.posix``: + + .. code:: bash + + mkdir -p ~/ansible_collections/ansible/posix + + +3. Clone the forked repository from the author profile to the created path: + + .. code:: bash + + git clone https://github.com/AUTHOR_ACC/COLLECTION_REPO.git ~/ansible_collections/NAMESPACE/COLLECTION_NAME + +4. Go to the cloned repository. + + .. code:: bash + + cd ~/ansible_collections/NAMESPACE/COLLECTION_NAME + +5. Checkout the PR branch (it can be retrieved from the PR's page): + + .. code:: bash + + git checkout pr_branch + + +Test the Pull Request +===================== + +1. Include `~/ansible_collections` in `COLLECTIONS_PATHS`. See :ref:`COLLECTIONS_PATHS` for details. + +2. Run your playbook using the PR branch and verify the PR fixed the bug. + +3. Give feedback on the pull request or the linked issue(s). diff --git a/docs/docsite/rst/community/collection_contributors/collection_unit_tests.rst b/docs/docsite/rst/community/collection_contributors/collection_unit_tests.rst new file mode 100644 index 0000000..e357358 --- /dev/null +++ b/docs/docsite/rst/community/collection_contributors/collection_unit_tests.rst @@ -0,0 +1,162 @@ + +.. _collection_unit_tests: + +****************************** +Add unit tests to a collection +****************************** + +This section describes all of the steps needed to add unit tests to a collection and how to run them locally using the ``ansible-test`` command. + +See :ref:`testing_units_modules` for more details. + +.. contents:: + :local: + +Understanding the purpose of unit tests +======================================== + +Unit tests ensure that a section of code (known as a ``unit``) meets its design requirements and behaves as intended. Some collections do not have unit tests but it does not mean they are not needed. + + +A ``unit`` is a function or method of a class used in a module or plugin. Unit tests verify that a function with a certain input returns the expected output. + +Unit tests should also verify when a function raises or handles exceptions. + +Ansible uses `pytest <https://docs.pytest.org/en/latest/>`_ as a testing framework. + +See :ref:`testing_units_modules` for complete details. + +Inclusion in the Ansible package `requires integration and/or unit tests <https://github.com/ansible-collections/overview/blob/main/collection_requirements.rst#requirements-for-collections-to-be-included-in-the-ansible-package>`_ You should have tests for your collection as well as for individual modules and plugins to make your code more reliable To learn how to get started with integration tests, see :ref:`collection_integration_tests`. + + +See :ref:`collection_prepare_local` to prepare your environment. + +.. _collection_unit_test_required: + +Determine if unit tests exist +============================= + +Ansible collection unit tests are located in the ``tests/units`` directory. + +The structure of the unit tests matches the structure of the code base, so the tests can reside in the ``tests/units/plugins/modules/`` and ``tests/units/plugins/module_utils`` directories. There can be sub-directories, if modules are organized by module groups. + +If you are adding unit tests for ``my_module`` for example, check to see if the tests already exist in the collection source tree with the path ``tests/units/plugins/modules/test_my_module.py``. + +Example of unit tests +===================== + +Let's assume that the following function is in ``my_module`` : + +.. code:: python + + def convert_to_supported(val): + """Convert unsupported types to appropriate.""" + if isinstance(val, decimal.Decimal): + return float(val) + + if isinstance(val, datetime.timedelta): + return str(val) + + if val == 42: + raise ValueError("This number is just too cool for us ;)") + + return val + +Unit tests for this function should, at a minimum, check the following: + +* If the function gets a ``Decimal`` argument, it returns a corresponding ``float`` value. +* If the function gets a ``timedelta`` argument, it returns a corresponding ``str`` value. +* If the function gets ``42`` as an argument, it raises a ``ValueError``. +* If the function gets an argument of any other type, it does nothing and returns the same value. + +To write these unit tests in collection is called ``community.mycollection``: + +1. If you already have your local environment :ref:`prepared <collection_prepare_local>`, go to the collection root directory. + + .. code:: bash + + cd ~/ansible_collection/community/mycollection + +2. Create a test file for ``my_module``. If the path does not exist, create it. + + .. code:: bash + + touch tests/units/plugins/modules/test_my_module.py + +3. Add the following code to the file: + + .. code:: python + + # -*- coding: utf-8 -*- + + from __future__ import (absolute_import, division, print_function) + __metaclass__ = type + + from datetime import timedelta + from decimal import Decimal + + import pytest + + from ansible_collections.community.mycollection.plugins.modules.my_module import ( + convert_to_supported, + ) + + # We use the @pytest.mark.parametrize decorator to parametrize the function + # https://docs.pytest.org/en/latest/how-to/parametrize.html + # Simply put, the first element of each tuple will be passed to + # the test_convert_to_supported function as the test_input argument + # and the second element of each tuple will be passed as + # the expected argument. + # In the function's body, we use the assert statement to check + # if the convert_to_supported function given the test_input, + # returns what we expect. + @pytest.mark.parametrize('test_input, expected', [ + (timedelta(0, 43200), '12:00:00'), + (Decimal('1.01'), 1.01), + ('string', 'string'), + (None, None), + (1, 1), + ]) + def test_convert_to_supported(test_input, expected): + assert convert_to_supported(test_input) == expected + + def test_convert_to_supported_exception(): + with pytest.raises(ValueError, match=r"too cool"): + convert_to_supported(42) + + See :ref:`testing_units_modules` for examples on how to mock ``AnsibleModule`` objects, monkeypatch methods (``module.fail_json``, ``module.exit_json``), emulate API responses, and more. + +4. Run the tests using docker: + + .. code:: bash + + ansible-test units tests/unit/plugins/modules/test_my_module.py --docker + + +.. _collection_recommendation_unit: + +Recommendations on coverage +=========================== + +Use the following tips to organize your code and test coverage: + +* Make your functions simple. Small functions that do one thing with no or minimal side effects are easier to test. +* Test all possible behaviors of a function including exception related ones such as raising, catching and handling exceptions. +* When a function invokes the ``module.fail_json`` method, passed messages should also be checked. + +.. seealso:: + + :ref:`testing_units_modules` + Unit testing Ansible modules + :ref:`developing_testing` + Ansible Testing Guide + :ref:`collection_integration_tests` + Integration testing for collections + :ref:`testing_integration` + Integration tests guide + :ref:`testing_collections` + Testing collections + :ref:`testing_resource_modules` + Resource module integration tests + :ref:`collection_pr_test` + How to test a pull request locally diff --git a/docs/docsite/rst/community/collection_contributors/test_index.rst b/docs/docsite/rst/community/collection_contributors/test_index.rst new file mode 100644 index 0000000..19a6142 --- /dev/null +++ b/docs/docsite/rst/community/collection_contributors/test_index.rst @@ -0,0 +1,14 @@ +.. _testing_collections_guide: + +********************************************** +Testing Collection Contributions +********************************************** + +This section focuses on the different tests a contributor should run on their collection PR. + +.. toctree:: + :maxdepth: 1 + + collection_test_pr_locally + collection_unit_tests + collection_integration_tests diff --git a/docs/docsite/rst/community/collection_development_process.rst b/docs/docsite/rst/community/collection_development_process.rst new file mode 100644 index 0000000..3c2f609 --- /dev/null +++ b/docs/docsite/rst/community/collection_development_process.rst @@ -0,0 +1,255 @@ +.. _collection_development_process: + +****************************************** +The Ansible Collections Development Cycle +****************************************** + +Ansible developers (including community contributors) add new features, fix bugs, and update code in many different repositories. These repositories contain plugins and modules that enable Ansible to execute specific tasks, like adding a user to a particular database or configuring a particular network device. These repositories contain the source code for collections. + +Development on collections occurs at the macro and micro levels. Each collection has its own macro development cycle. For more information on the collections development cycle, see :ref:`contributing_maintained_collections`. The micro-level lifecycle of a PR is similar in collections and in ``ansible-core``. + +.. contents:: + :local: + + +Macro development: roadmaps, releases, and projects +===================================================================== + +If you want to follow the conversation about what features will be added to the Ansible package for upcoming releases and what bugs are being fixed, you can watch these resources: + +* the :ref:`roadmaps` +* the :ref:`Ansible Release Schedule <release_and_maintenance>` +* the `Ansible Community Working Group <https://github.com/ansible/community/wiki/Community>`_ . + +Micro development: the lifecycle of a PR +======================================== + +If you want to contribute a feature or fix a bug in a collection, you must open a **pull request** ("PR" for short). GitHub provides a great overview of `how the pull request process works <https://help.github.com/articles/about-pull-requests/>`_ in general. The ultimate goal of any pull request is to get merged and become part of a collection. Each collection has its own contributor guidelines so please check there for specific details. + +Here's an overview of the PR lifecycle: + +* :ref:`Contributor opens a PR <collection_quickstart>` +* CI runs the test suite +* Developers, maintainers, community review the PR +* Contributor addresses any feedback from reviewers +* Developers, maintainers, community re-review +* PR merged or closed + + +Making your PR merge-worthy +=========================== + +We do not merge every PR. See :ref:`collection_quickstart` for tips to make your PR useful, attractive, and merge-worthy. + +.. _collection_changelog_fragments: + +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: + +* add new modules and plugins, because Ansible tooling does that automatically; +* contain only documentation changes. + +.. note:: + Some collections require a changelog fragment for every pull request. They use the ``trivial:`` section for entries mentioned above that will be skipped when building a release changelog. + + +More precisely: + +* Every bugfix PR must have a changelog fragment. The only exception are fixes to a change that has not yet been included in a release. +* Every feature PR must have a changelog fragment. +* New modules and plugins (including jinja2 filter and test plugins) must have ``version_added`` entries set correctly in their documentation, and do not need a changelog fragment. The tooling detects new modules and plugins by their ``version_added`` values and announces them in the next release's changelog automatically. + +We build short summary changelogs for minor releases as well as for major releases. If you backport a bugfix, include a changelog fragment with the backport PR. + +.. _collection_changelogs_how_to_format: + +Creating a changelog fragment +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A basic changelog fragment is a ``.yaml`` or ``.yml`` file placed in the ``changelogs/fragments/`` directory. Each file contains a yaml dict with keys like ``bugfixes`` or ``major_changes`` followed by a list of changelog entries of bugfixes or features. Each changelog entry is rst embedded inside of the yaml file which means that certain constructs would need to be escaped so they can be interpreted by rst and not by yaml (or escaped for both yaml and rst if you prefer). Each PR **must** use a new fragment file rather than adding to an existing one, so we can trace the change back to the PR that introduced it. + +PRs which add a new module or plugin do not necessarily need a changelog fragment. See :ref:`community_changelogs`. Also see :ref:`changelogs_how_to_format` for the precise format changelog fragments should have. + +To create a changelog entry, create a new file with a unique name in the ``changelogs/fragments/`` directory of the corresponding repository. The file name should include the PR number and a description of the change. It must end with the file extension ``.yaml`` or ``.yml``. For example: ``40696-user-backup-shadow-file.yaml`` + +A single changelog fragment may contain multiple sections but most will only contain one section. The toplevel keys (bugfixes, major_changes, and so on) are defined in the `config file <https://github.com/ansible/ansible/blob/devel/changelogs/config.yaml>`_ for our `release note tool <https://github.com/ansible-community/antsibull-changelog/blob/main/docs/changelogs.rst>`_. Here are the valid sections and a description of each: + +**breaking_changes** + MUST include changes that break existing playbooks or roles. This includes any change to existing behavior that forces users to update tasks. Breaking changes means the user MUST make a change when they update. Breaking changes MUST only happen in a major release of the collection. Write in present tense and clearly describe the new behavior that the end user must now follow. Displayed in both the changelogs and the :ref:`Porting Guides <porting_guides>`. + + .. code-block:: yaml + + breaking_changes: + - ec2_instance - instance wait for state behavior no longer waits for the instance monitoring status to become OK when launching a new instance. If plays require the old behavior, the action will need to specify ``state: started`` (https://github.com/ansible-collections/amazon.aws/pull/481). + + +**major_changes** + Major changes to ansible-core or a collection. SHOULD NOT include individual module or plugin changes. MUST include non-breaking changes that impact all or most of a collection (for example, updates to support a new SDK version across the collection). Major changes mean the user can CHOOSE to make a change when they update but do not have to. Could be used to announce an important upcoming EOL or breaking change in a future release. (ideally 6 months in advance, if known. See `this example <https://github.com/ansible-collections/community.general/blob/stable-1/CHANGELOG.rst#v1313>`_). Write in present tense and describe what is new. Optionally, include a 'Previously..." sentence to help the user identify where old behavior should now change. Displayed in both the changelogs and the :ref:`Porting Guides <porting_guides>`. + + .. code-block:: yaml + + major_changes: + - bitbucket_* modules - client_id is no longer marked as ``no_log=true``. If you relied on its value not showing up in logs and output, mark the whole tasks with ``no_log: true`` (https://github.com/ansible-collections/community.general/pull/2045). + +**minor_changes** + Minor changes to ansible-core, modules, or plugins. This includes new parameters added to modules, or non-breaking behavior changes to existing parameters, such as adding new values to choices[]. Minor changes are enhancements, not bug fixes. Write in present tense. + + .. code-block:: yaml + + minor_changes: + - nmcli - adds ``routes6`` and ``route_metric6`` parameters for supporting IPv6 routes (https://github.com/ansible-collections/community.general/issues/4059). + + +**deprecated_features** + Features that have been deprecated and are scheduled for removal in a future release. Write in past tense. Include an alternative, where available, for the feature being deprecated. Displayed in both the changelogs and the :ref:`Porting Guides <porting_guides>`. + + .. code-block:: yaml + + deprecated_features: + - mail callback plugin - not specifying ``sender`` is deprecated and will be disallowed in ``community.general`` 6.0.0 (https://github.com/ansible-collections/community.general/pull/4140). + + +**removed_features** + Features that were previously deprecated and are now removed. Write in past tense. Include an alternative, where available, for the feature being deprecated. Displayed in both the changelogs and the :ref:`Porting Guides <porting_guides>`. + + .. code-block:: yaml + + removed_features: + - acme_account_facts - the deprecated redirect has been removed. Use ``community.crypto.acme_account_info`` instead (https://github.com/ansible-collections/community.crypto/pull/290). + + +**security_fixes** + Fixes that address CVEs or resolve security concerns. MUST use security_fixes for any CVEs. Write in present tense. Include links to CVE information. + + .. code-block:: yaml + + security_fixes: + - win_psexec - ensure password is masked in ``psexec_``command return result (https://github.com/ansible-collections/community.windows/issues/43). + + +**bugfixes** + Fixes that resolve issues. SHOULD NOT be used for minor enhancements (use ``minor_change`` instead). Write in past tense to describe the problem and present tense to describe the fix. + + .. code-block:: yaml + + bugfixes: + - apt_repository - fix crash caused by a timeout. The ``cache.update()`` was raising an ``IOError`` because of a timeout in ``apt update`` (https://github.com/ansible/ansible/issues/51995). + + +**known_issues** + Known issues that are currently not fixed or will not be fixed. Write in present tense to describe the problem and in imperative tense to describe any available workaround. + + .. code-block:: yaml + + known_issues: + - idrac_user - module may error out with the message ``unable to perform the import or export operation`` because there are pending attribute changes or a configuration job is in progress. Wait for the job to complete and run the task again.(https://github.com/dell/dellemc-openmanage-ansible-modules/pull/303). + + +**trivial** + Changes where a formal release changelog entry isn't required. ``trivial`` changelog fragments are excluded from the published changelog output and may be used for changes such as housekeeping, documentation and test only changes. + You can use ``trivial`` for collections that require a changelog fragment for each pull request. + + .. code-block:: yaml + + trivial: + - aws_ec2 - fix broken integration test (https://github.com/ansible-collections/amazon.aws/pull/1269). + + +Each changelog entry must contain a link to its issue between parentheses at the end. If there is no corresponding issue, the entry must contain a link to the PR itself. + +Most changelog entries are ``bugfixes`` or ``minor_changes``. + + +Changelog fragment entry format +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When writing a changelog entry, use the following format: + +.. code-block:: yaml + + - scope - description starting with a lowercase letter and ending with a period at the very end. Multiple sentences are allowed (https://github.com/reference/to/an/issue or, if there is no issue, reference to a pull request itself). + +The scope is usually a module or plugin name or group of modules or plugins, for example, ``lookup plugins``. While module names can (and should) be mentioned directly (``foo_module``), plugin names should always be followed by the type (``foo inventory plugin``). + +For changes that are not really scoped (for example, which affect a whole collection), use the following format: + +.. code-block:: yaml + + - Description starting with an uppercase letter and ending with a dot at the very end. Multiple sentences are allowed (https://github.com/reference/to/an/issue or, if there is no issue, reference to a pull request itself). + + +Here are some examples: + +.. code-block:: yaml + + bugfixes: + - apt_repository - fix crash caused by ``cache.update()`` raising an ``IOError`` + due to a timeout in ``apt update`` (https://github.com/ansible/ansible/issues/51995). + +.. code-block:: yaml + + minor_changes: + - lineinfile - add warning when using an empty regexp (https://github.com/ansible/ansible/issues/29443). + +.. code-block:: yaml + + bugfixes: + - copy - the module was attempting to change the mode of files for + remote_src=True even if mode was not set as a parameter. This failed on + filesystems which do not have permission bits (https://github.com/ansible/ansible/issues/29444). + +You can find more example changelog fragments in the `changelog directory <https://github.com/ansible-collections/community.general/tree/main/changelogs/fragments>`_ for the community.general development branch. + +After you have written the changelog fragment for your PR, commit the file and include it with the pull request. + + +Changelog fragment entry format for new jinja2 plugins, roles, and playbooks +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +While new modules and plugins that are not jinja2 filter or test plugins are mentioned automatically in the generated changelog, jinja2 filter and test plugins, roles, and playbooks are not. To make sure they are mentioned, a changelog fragment in a specific format is needed: + +.. code-block:: yaml + + # A new jinja2 filter plugin: + add plugin.filter: + - # The following needs to be the name of the filter itself, not of the file + # the filter is included in! + name: to_time_unit + # The description should be in the same format as short_description for + # other plugins and modules: it should start with an upper-case letter and + # not have a period at the end. + description: Converts a time expression to a given unit + + # A new jinja2 test plugin: + add plugin.test: + - # The following needs to be the name of the test itself, not of the file + # the test is included in! + name: asn1time + # The description should be in the same format as short_description for + # other plugins and modules: it should start with an upper-case letter and + # not have a period at the end. + description: Check whether the given string is an ASN.1 time + + # A new role: + add object.role: + - # This should be the short (non-FQCN) name of the role. + name: nginx + # The description should be in the same format as short_description for + # plugins and modules: it should start with an upper-case letter and + # not have a period at the end. + description: A nginx installation role + + # A new playbook: + add object.playbook: + - # This should be the short (non-FQCN) name of the playbook. + name: wipe_server + # The description should be in the same format as short_description for + # plugins and modules: it should start with an upper-case letter and + # not have a period at the end. + description: Wipes a server diff --git a/docs/docsite/rst/community/committer_guidelines.rst b/docs/docsite/rst/community/committer_guidelines.rst new file mode 100644 index 0000000..7067a5a --- /dev/null +++ b/docs/docsite/rst/community/committer_guidelines.rst @@ -0,0 +1,79 @@ +.. _community_committer_guidelines: + +********************* +Committers Guidelines +********************* + +These are the guidelines for people with commit privileges on the repositories in the ansible and ansible-collections GitHub organizations. + +Committers of `Ansible-core <https://github.com/ansible/ansible>`_ are necessarily Red Hat employees acting as members of the Ansible Core team. Committers of `Ansible collections <https://github.com/ansible-collections/>`_ are members of the community or Ansible Engineering. Please read the guidelines before you commit. + +These guidelines apply to everyone. At the same time, this is NOT a process document. So just use good judgment. You have been given commit access because we trust your judgment. + +That said, use the trust wisely. + +If you abuse the trust and break components and builds, and so on, the trust level falls and you may be asked not to commit or you may lose your commit privileges. + +Features, high-level design, and roadmap of ansible-core +======================================================== + +As a core team member, you are an integral part of the team that develops the :ref:`roadmap <roadmaps>`. Please be engaged, and push for the features and fixes that you want to see. Also keep in mind that Red Hat, as a company, will commit to certain features, fixes, APIs, and so on, for various releases. Red Hat, the company, and the Ansible team must get these changes completed and released as scheduled. Obligations to users, the community, and customers must come first. Because of these commitments, a feature you want to develop yourself may not get into a release if it affects a lot of other parts within Ansible. + +Any other new features and changes to high level design should go through the proposal process (TBD), to ensure the community and core team have had a chance to review the idea and approve it. The core team has sole responsibility for merging new features based on proposals to `Ansible-core <https://github.com/ansible/ansible>`_. + + +Features, high-level design, and roadmap of Ansible collections +=============================================================== + +Collections maintainers define features, high-level design, and roadmap of the collections themselves and are responsible for merging new features to `Ansible collections <https://github.com/ansible-collections/>`_ based on proposals discussed with their communities. + +Our workflow on GitHub +====================== + +As a committer, you may already know this, but our workflow forms a lot of our team policies. Please ensure you are aware of the following workflow steps: + +* Fork the repository upon which you want to do some work to your own personal repository +* Work on the specific branch upon which you need to commit +* Create a pull request back to the upstream repository and tag the people you would like to review; assign someone as the primary "owner" of your pull request +* Adjust code as necessary based on the comments provided +* Ask someone from the repository committers to do a final review and merge + +Addendum to workflow for committers: +------------------------------------ + +The Core Team is aware that this can be a difficult process at times. Sometimes, the team breaks the rules by making direct commits or merging their own pull requests. This section is a set of guidelines. If you are changing a comma in documentation, or making a very minor change, you can use your best judgement. This is another trust thing. The process is critical for any major change, but for little things or getting something done quickly, use your best judgement and make sure people on the team are aware of your work. + +Roles on Core +============= +* Core committers: Fine to do pull requests for most things, but we should have a timebox. Hanging pull requests may merge on the judgement of these developers. +* :ref:`Module maintainers <maintainers>`: Module maintainers own specific modules and have indirect commit access through the current module pull request mechanisms. +* :ref:`Collection maintainers <maintainers>`: Collection maintainers own specific collections and have commit access to them. Each collection can set its own rules for contributions. + +.. _committer_general_rules: + +General rules +============= +Individuals with direct commit access are entrusted with powers that allow them to do a broad variety of things--probably more than we can write down. Rather than rules, treat these as general *guidelines*, individuals with this power are expected to use their best judgement. + +* Do NOT + + - Commit directly. + - Merge your own pull requests. Someone else should have a chance to review and approve the pull request merge. If you are a Core Committer, you have a small amount of leeway here for very minor changes. + - Forget about alternate environments. Consider the alternatives--yes, people have bad environments, but they are the ones who need us the most. + - Drag your community team members down. Discuss the technical merits of any pull requests you review. Avoid negativity and personal comments. For more guidance on being a good community member, read our :ref:`code_of_conduct`. + - Forget about the maintenance burden. High-maintenance features may not be worth adding. + - Break playbooks. Always keep backwards compatibility in mind. + - Forget to keep it simple. Complexity breeds all kinds of problems. + +* Do + + - Squash, avoid merges whenever possible, use GitHub's squash commits or cherry pick if needed (bisect thanks you). + - Be active. Committers who have no activity on the project (through merges, triage, commits, and so on) will have their permissions suspended. + - Consider backwards compatibility (goes back to "do not break existing playbooks"). + - Write :ref:`tests<developing_testing>` and be sure that other's pull requests you are reviewing are covered well. Pull requests with tests are looked at with more priority than pull requests without tests that should have them included. While not all changes require tests, be sure to add them for new features, bug fixes, and functionality changes. + - Discuss with other committers, specially when you are unsure of something. + - Document! If your pull request is a new feature or a change to behavior, make sure you have updated all associated documentation or have notified the right people to do so. It also helps to add the version of ``ansible-core`` or ``collection`` against which this documentation is compatible (to avoid confusion between stable and devel docs, for backwards compatibility, and so on). + - Consider scope, sometimes a fix can be generalized. + - Keep it simple, then things are maintainable, debuggable, and intelligible. + +Committers are expected to continue to follow the same community and contribution guidelines followed by the rest of the Ansible community. diff --git a/docs/docsite/rst/community/communication.rst b/docs/docsite/rst/community/communication.rst new file mode 100644 index 0000000..1e8bc64 --- /dev/null +++ b/docs/docsite/rst/community/communication.rst @@ -0,0 +1,179 @@ +.. _communication: + +***************************************** +Communicating with the Ansible community +***************************************** + +.. contents:: + :local: + +Code of Conduct +=============== + +All communication and interactions in the Ansible Community are governed by our :ref:`code_of_conduct`. Please read and understand it! + +Asking questions over email +=========================== + +If you want to keep up with Ansible news, need help, or have a question, you can use one of the Ansible mailing lists. Each list covers a particular topic. Read the descriptions here to find the best list for your question. + +Your first post to the mailing list will be moderated (to reduce spam), so please allow up to a day or so for your first post to appear. + +* `Ansible Announce list <https://groups.google.com/forum/#!forum/ansible-announce>`_ is a read-only list that shares information about new releases of Ansible, and also rare infrequent event information, such as announcements about an upcoming AnsibleFest, which is our official conference series. Worth subscribing to! +* `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 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. + +The Ansible mailing lists are hosted on Google, but you do not need a Google account to subscribe. To subscribe to a group from a non-Google account, send an email to the subscription address requesting the subscription. For example: ``ansible-devel+subscribe@googlegroups.com``. + +.. _communication_irc: + +Real-time chat +============== + +For real-time interactions, conversations in the Ansible community happen over two chat protocols: Matrix and IRC. We maintain a bridge between Matrix and IRC, so you can choose whichever protocol you prefer. All channels exist in both places. Join a channel any time to ask questions, participate in a Working Group meeting, or just say hello. + +Ansible community on Matrix +--------------------------- + +To join the community using Matrix, you need two things: + +* a Matrix account (from `Matrix.org <https://app.element.io/#/register>`_ or any other Matrix homeserver) +* a `Matrix client <https://matrix.org/clients/>`_ (we recommend `Element Webchat <https://app.element.io>`_) + +The Ansible community maintains its own Matrix homeserver at ``ansible.im``, however public registration is currently unavailable. + +Matrix chat supports: + +* persistence (when you log on, you see all messages since you last logged off) +* edits (Lets you fix typos and so on. **NOTE** Each edit you make on Matrix re-sends the message to IRC. Please try to avoid multiple edits!) +* replies to individual users +* reactions/emojis +* bridging to IRC +* no line limits +* images + +The room links in the :ref:`general_channels` or in the :ref:`working_group_list` list will take you directly to the relevant rooms. + +If there is no appropriate room for your community, please create it. + +For more information, see the community-hosted `Matrix FAQ <https://hackmd.io/@ansible-community/community-matrix-faq>`_. + +Ansible community on IRC +------------------------ + +The Ansible community maintains several IRC channels on `irc.libera.chat <https://libera.chat/>`_. To join the community using IRC, you need one thing: + +* an IRC client + +IRC chat supports: + +* no persistence (you only see messages when you are logged on unless you add a bouncer) +* simple text interface +* bridging from Matrix + +Our IRC channels may require you to register your IRC nickname. If you receive an error when you connect or when posting a message, see `libera.chat's Nickname Registration guide <https://libera.chat/guides/registration>`_ for instructions. To find all ``ansible`` specific channels on the libera.chat network, use the following command in your IRC client: + +.. code-block:: text + + /msg alis LIST #ansible* -min 5 + +as described in the `libera.chat docs <https://libera.chat/guides/findingchannels>`_. + +Our channels record history on the Matrix side. The channel history can be viewed in a browser - all channels will report an appropriate link to ``chat.ansible.im`` in their Chanserv entrymsg upon joining the room. Alternatively, a URL of the form ``https://chat.ansible.im/#/room/# {IRC channel name}:libera.chat`` will also work, for example - for the #ansible-docs channel it would be `https://app.element.io/#/room/#ansible-docs:libera.chat`. + +.. _general_channels: + +General channels +---------------- + +The clickable links will take you directly to the relevant Matrix room in your browser; room/channel information is also given for use in other clients: + +- `Community social room and posting news for the Bullhorn newsletter <https://matrix.to:/#/#social:ansible.com>`_ - ``Matrix: #social:ansible.com | IRC: #ansible-social`` +- `General usage and support questions <https://matrix.to:/#/#users:ansible.com>`_ - ``Matrix: #users:ansible.com | IRC: #ansible`` +- `Discussions on developer topics and code related to features or bugs <https://matrix.to/#/#devel:ansible.com>`_ - ``Matrix: #devel:ansible.com | IRC: #ansible-devel`` +- `Discussions on community and collections related topics <https://matrix.to:/#/#community:ansible.com>`_ - ``Matrix: #community:ansible.com | IRC: #ansible-community`` +- `For public community meetings <https://matrix.to/#/#meeting:ansible.im>`_ - ``Matrix: #meeting:ansible.im | IRC: #ansible-meeting`` + - We will generally announce these on one or more of the above mailing lists. See the `meeting schedule and agenda page <https://github.com/ansible/community/blob/main/meetings/README.md>`_ + +.. _working_group_list: + +Working groups +-------------- + +Many of our community `Working Groups <https://github.com/ansible/community/wiki#working-groups>`_ meet in chat. If you want to get involved in a working group, join the Matrix room or IRC channel where it meets or comment on the agenda. + +- `AAP Configuration as Code <https://github.com/redhat-cop/controller_configuration/wiki/AAP-Configuration-as-Code>`_ - Matrix: `#aap_config_as_code:ansible.com <https://matrix.to/#/#aap_config_as_code:ansible.com>`_ +- `Amazon (AWS) Working Group <https://github.com/ansible/community/wiki/AWS>`_ - Matrix: `#aws:ansible.com <https://matrix.to:/#/#aws:ansible.com>`_ | IRC: ``#ansible-aws`` +- `AWX Working Group <https://github.com/ansible/awx>`_ - Matrix: `#awx:ansible.com <https://matrix.to:/#/#awx:ansible.com>`_ | IRC: ``#ansible-awx`` +- `Azure Working Group <https://github.com/ansible/community/wiki/Azure>`_ - Matrix: `#azure:ansible.com <https://matrix.to:/#/#azure:ansible.com>`_ | IRC: ``#ansible-azure`` +- `Community Working Group <https://github.com/ansible/community/wiki/Community>`_ (including Meetups) - Matrix: `#community:ansible.com <https://matrix.to:/#/#community:ansible.com>`_ | IRC: ``#ansible-community`` +- `Container Working Group <https://github.com/ansible/community/wiki/Container>`_ - Matrix: `#container:ansible.com <https://matrix.to:/#/#container:ansible.com>`_ | IRC: ``#ansible-container`` +- `Contributor Experience Working Group <https://github.com/ansible/community/wiki/Contributor-Experience>`_ - Matrix: `#community:ansible.com <https://matrix.to:/#/#community:ansible.com>`_ | IRC: ``#ansible-community`` +- `DigitalOcean Working Group <https://github.com/ansible/community/wiki/Digital-Ocean>`_ - Matrix: `#digitalocean:ansible.im <https://matrix.to:/#/#digitalocean:ansible.im>`_ | IRC: ``#ansible-digitalocean`` +- `Diversity Working Group <https://github.com/ansible/community/wiki/Diversity>`_ - Matrix: `#diversity:ansible.com <https://matrix.to:/#/#diversity:ansible.com>`_ | IRC: ``#ansible-diversity`` +- `Docker Working Group <https://github.com/ansible/community/wiki/Docker>`_ - Matrix: `#devel:ansible.com <https://matrix.to:/#/#devel:ansible.com>`_ | IRC: ``#ansible-devel`` +- `Documentation Working Group <https://github.com/ansible/community/wiki/Docs>`_ - Matrix: `#docs:ansible.com <https://matrix.to:/#/#docs:ansible.com>`_ | IRC: ``#ansible-docs`` +- `Galaxy Working Group <https://github.com/ansible/community/wiki/Galaxy>`_ - Matrix: `#galaxy:ansible.com <https://matrix.to:/#/#galaxy:ansible.com>`_ | IRC: ``#ansible-galaxy`` +- `JBoss Working Group <https://github.com/ansible/community/wiki/JBoss>`_ - Matrix: `#jboss:ansible.com <https://matrix.to:/#/#jboss:ansible.com>`_ | IRC: ``#ansible-jboss`` +- `Kubernetes Working Group <https://github.com/ansible/community/wiki/Kubernetes>`_ - Matrix: `#kubernetes:ansible.com <https://matrix.to:/#/#kubernetes:ansible.com>`_ | IRC: ``#ansible-kubernetes`` +- `Linode Working Group <https://github.com/ansible/community/wiki/Linode>`_ - Matrix: `#linode:ansible.com <https://matrix.to:/#/#linode:ansible.com>`_ | IRC: ``#ansible-linode`` +- `Molecule Working Group <https://github.com/ansible/community/wiki/Molecule>`_ (`testing platform for Ansible playbooks and roles <https://molecule.readthedocs.io>`_) - Matrix: `#molecule:ansible.im <https://matrix.to:/#/#molecule:ansible.im>`_ | IRC: ``#ansible-molecule`` +- `MySQL Working Group <https://github.com/ansible-collections/community.mysql/wiki/MySQL-Working-Group>`_ - Matrix: `#mysql:ansible.com <https://matrix.to:/#/#mysql:ansible.com>`_ +- `Network Working Group <https://github.com/ansible/community/wiki/Network>`_ - Matrix: `#network:ansible.com <https://matrix.to:/#/#network:ansible.com>`_ | IRC: ``#ansible-network`` +- `PostgreSQL Working Group <https://github.com/ansible-collections/community.postgresql/wiki/PostgreSQL-Working-Group>`_ - Matrix: `#postgresql:ansible.com <https://matrix.to:/#/#postgresql:ansible.com>`_ +- `Remote Management Working Group <https://github.com/ansible/community/issues/409>`_ - Matrix: `#devel:ansible.com <https://matrix.to:/#/#devel:ansible.com>`_ | IRC: ``#ansible-devel`` +- `Security Automation Working Group <https://github.com/ansible/community/wiki/Security-Automation>`_ - Matrix: `#security-automation:ansible.com <https://matrix.to/#/#security-automation:ansible.com>`_ | IRC: ``#ansible-security`` +- `Storage Working Group <https://github.com/ansible/community/wiki/Storage>`_ - Matrix: `#storage:ansible.com <https://matrix.to/#/#storage:ansible.com>`_ | IRC: ``#ansible-storage`` +- `Testing Working Group <https://github.com/ansible/community/wiki/Testing>`_ - Matrix: `#devel:ansible.com <https://matrix.to:/#/#devel:ansible.com>`_ | IRC: ``#ansible-devel`` +- `VMware Working Group <https://github.com/ansible/community/wiki/VMware>`_ - Matrix: `#vmware:ansible.com <https://matrix.to:/#/#vmware:ansible.com>`_ | IRC: ``#ansible-vmware`` +- `Windows Working Group <https://github.com/ansible/community/wiki/Windows>`_ - Matrix: `#windows:ansible.com <https://matrix.to:/#/#windows:ansible.com>`_ | IRC: ``#ansible-windows`` +- `Ansible developer tools Group <https://github.com/ansible/community/wiki/Ansible-developer-tools>`_ - Matrix: `#devtools:ansible.com <https://matrix.to/#/#devtools:ansible.com>`_ | IRC: ``#ansible-devtools`` + +Want to `form a new Working Group <https://github.com/ansible/community/blob/main/WORKING-GROUPS.md>`_? + +Regional and Language-specific channels +--------------------------------------- + +- Comunidad Ansible en español - Matrix: `#espanol:ansible.im <https://matrix.to:/#/#espanol:ansible.im>`_ | IRC: ``#ansible-es`` +- Communauté française d'Ansible - Matrix: `#francais:ansible.im <https://matrix.to:/#/#francais:ansible.im>`_ | IRC: ``#ansible-fr`` +- Communauté suisse d'Ansible - Matrix: `#suisse:ansible.im <https://matrix.to:/#/#suisse:ansible.im>`_ | IRC: ``#ansible-zh`` +- European Ansible Community - Matrix: `#europe:ansible.im <https://matrix.to:/#/#europe:ansible.im>`_ | IRC: ``#ansible-eu`` + +Meetings on chat +---------------- + +The Ansible community holds regular meetings on various topics on Matrix/IRC, and anyone who is interested is invited to participate. For more information about Ansible meetings, consult the `meeting schedule and agenda page <https://github.com/ansible/community/blob/main/meetings/README.md>`_. + +Ansible Community Topics +======================== + +The `Ansible Community Steering Committee <https://docs.ansible.com/ansible/devel/community/steering/community_steering_committee.html>`_ uses the `community-topics repository <https://github.com/ansible-community/community-topics/issues>`_ to asynchronously discuss with the Community and vote on Community topics in corresponding issues. + +Create a new issue in the `repository <https://github.com/ansible-community/community-topics/issues>`_ if you want to discuss an idea that impacts any of the following: + +* Ansible Community +* Community collection best practices and `requirements <https://github.com/ansible-collections/overview/blob/main/collection_requirements.rst>`_ +* `Community collection inclusion policy <https://github.com/ansible-collections/ansible-inclusion/blob/main/README.md>`_ +* `The Community governance <https://docs.ansible.com/ansible/devel/community/steering/community_steering_committee.html>`_ +* Other proposals of importance that need the Committee or overall Ansible community attention + +Ansible Automation Platform support questions +============================================= + +Red Hat Ansible `Automation Platform <https://www.ansible.com/products/automation-platform>`_ is a subscription that contains support, certified content, and tooling for Ansible including content management, a controller, UI and REST API. + +If you have a question about Ansible Automation Platform, visit `Red Hat support <https://access.redhat.com/products/red-hat-ansible-automation-platform/>`_ rather than using a chat channel or the general project mailing list. + +The Bullhorn +============ + +**The Bullhorn** is our newsletter for the Ansible contributor community. Please `subscribe <https://eepurl.com/gZmiEP>`_ to receive it. + +If you have any content you would like to share, please `contribute/suggest it <https://github.com/ansible/community/wiki/News#the-bullhorn>`_ for upcoming releases. + +If you have any questions, please reach out to us at ``the-bullhorn@redhat.com``. + +Read past issues on the official Bullhorn's `wiki page <https://github.com/ansible/community/wiki/News#the-bullhorn>`_. diff --git a/docs/docsite/rst/community/contributing_maintained_collections.rst b/docs/docsite/rst/community/contributing_maintained_collections.rst new file mode 100644 index 0000000..b044191 --- /dev/null +++ b/docs/docsite/rst/community/contributing_maintained_collections.rst @@ -0,0 +1,304 @@ + +.. _contributing_maintained_collections: + +*********************************************** +Contributing to Ansible-maintained Collections +*********************************************** + +The Ansible team welcomes community contributions to the collections maintained by Red Hat Ansible Engineering. This section describes how you can open issues and create PRs with the required testing before your PR can be merged. + +.. contents:: + :local: + +Ansible-maintained collections +================================= + +The following table shows: + +* **Ansible-maintained collection** - Click the link to the collection on Galaxy, then click the ``repo`` button in Galaxy to find the GitHub repository for this collection. +* **Related community collection** - Collection that holds community-created content (modules, roles, and so on) that may also be of interest to a user of the Ansible-maintained collection. You can, for example, add new modules to the community collection as a technical preview before the content is moved to the Ansible-maintained collection. +* **Sponsor** - Working group that manages the collections. You can join the meetings to discuss important proposed changes and enhancements to the collections. +* **Test requirements** - Testing required for any new or changed content for the Ansible-maintained collection. +* **Developer details** - Describes whether the Ansible-maintained collection accepts direct community issues and PRs for existing collection content, as well as more specific developer guidelines based on the collection type. + + +.. _ansible-collection-table: + +.. raw:: html + + <style> + /* Style for this single table. Add delimiters between header columns */ + table#ansible-collection-table th { + border-width: 1px; + border-color: #dddddd /*rgb(225, 228, 229)*/; + border-style: solid; + text-align: center; + padding: 5px; + background-color: #eeeeee; + } + tr, td { + border-width: 1px; + border-color: rgb(225, 228, 229); + border-style: solid; + text-align: center; + padding: 5px; + + } + </style> + + <table id="ansible-collection-table"> + <tr> + <th colspan="3">Collection details</th> + <th colspan="4">Test requirements: Ansible collections</th> + <th colspan="2">Developer details</th> + </tr> + <tr> + <th>Ansible collection</th> + <th>Related community collection</th> + <th>Sponsor</th> + <th>Sanity</th> + <th>Unit</th> + <th>Integration</th> + <th>CI Platform</th> + <th>Open to PRs*</th> + <th>Guidelines</th> + </tr> + <tr> + <td><a href="https://galaxy.ansible.com/amazon/aws">amazon.aws</a></td> + <td><a href="https://galaxy.ansible.com/community/aws">community.aws</a></td> + <td><a href="https://github.com/ansible/community/tree/main/group-aws">AWS</a></td> + <td>â**</td> + <td>**</td> + <td>â</td> + <td>Zuul</td> + <td>â</td> + <td><a href="https://docs.ansible.com/ansible/devel/dev_guide/platforms/aws_guidelines.html">AWS guide</a></td> + </tr> + <tr> + <td><a href="https://galaxy.ansible.com/ansible/netcommon">ansible.netcommon***</a></td> + <td><a href="https://galaxy.ansible.com/community/network">community.network</a></td> + <td><a href="https://github.com/ansible/community/wiki/Network">Network</a></td> + <td>â</td> + <td>â</td> + <td>â</td> + <td>Zuul</td> + <td>â</td> + <td><a href="https://docs.ansible.com/ansible/devel/network/dev_guide/index.html">Network guide</a></td> + </tr> + <tr> + <td><a href="https://galaxy.ansible.com/ansible/posix">ansible.posix</a></td> + <td><a href="https://galaxy.ansible.com/community/general">community.general</a></td> + <td>Linux</a></td> + <td>â</td> + <td></td> + <td></td> + <td>Zuul</td> + <td>â</td> + <td><a href="https://docs.ansible.com/ansible/latest/dev_guide/index.html">Developer guide</a></td> + </tr> + <tr> + <td><a href="https://galaxy.ansible.com/ansible/windows">ansible.windows</a></td> + <td><a href="https://galaxy.ansible.com/community/windows">community.windows</a></td> + <td><a href="https://github.com/ansible/community/wiki/Windows">Windows</a></td> + <td>â</td> + <td>â****</td> + <td>â</td> + <td>Azure Pipelines and Zuul</td> + <td>â</td> + <td><a href="https://docs.ansible.com/ansible/devel/dev_guide/developing_modules_general_windows.html#developing-modules-general-windows">Windows guide</a></td> + </tr> + <tr> + <td><a href="https://galaxy.ansible.com/arista/eos">arista.eos</a></td> + <td><a href="https://galaxy.ansible.com/community/network">community.network</a></td> + <td><a href="https://github.com/ansible/community/wiki/Network">Network</a></td> + <td>â</td> + <td>â</td> + <td>â</td> + <td>Zuul</td> + <td>â</td> + <td><a href="https://docs.ansible.com/ansible/devel/network/dev_guide/index.html">Network guide</a></td> + </tr> + <tr> + <td><a href="https://galaxy.ansible.com/cisco/asa">cisco.asa</a></td> + <td><a href="https://github.com/ansible-collections/community.asa">community.asa</a></td> + <td><a href="https://github.com/ansible/community/wiki/Security-Automation">Security</a></td> + <td>â</td> + <td>â</td> + <td>â</td> + <td>Zuul</td> + <td>â</td> + <td><a href="https://docs.ansible.com/ansible/latest/dev_guide/index.html">Developer guide</a></td> + </tr> + <tr> + <td><a href="https://galaxy.ansible.com/cisco/ios">cisco.ios</a></td> + <td><a href="https://galaxy.ansible.com/community/network">community.network</a></td> + <td><a href="https://github.com/ansible/community/wiki/Network">Network</a></td> + <td>â</td> + <td>â</td> + <td>â</td> + <td>Zuul</td> + <td>â</td> + <td><a href="https://docs.ansible.com/ansible/devel/network/dev_guide/index.html">Network guide</a></td> + </tr> + <tr> + <td><a href="https://galaxy.ansible.com/cisco/iosxr">cisco.iosxr</a></td> + <td><a href="https://galaxy.ansible.com/community/network">community.network</a></td> + <td><a href="https://github.com/ansible/community/wiki/Network">Network</a></td> + <td>â</td> + <td>â</td> + <td>â</td> + <td>Zuul</td> + <td>â</td> + <td><a href="https://docs.ansible.com/ansible/devel/network/dev_guide/index.html">Network guide</a></td> + </tr> + <tr> + <td><a href="https://galaxy.ansible.com/cisco/nxos">cisco.nxos</a></td> + <td><a href="https://galaxy.ansible.com/community/network">community.network</a></td> + <td><a href="https://github.com/ansible/community/wiki/Network">Network</a></td> + <td>â</td> + <td>â</td> + <td>â</td> + <td>Zuul</td> + <td>â</td> + <td><a href="https://docs.ansible.com/ansible/devel/network/dev_guide/index.html">Network guide</a></td> + </tr> + <tr> + <td><a href="https://galaxy.ansible.com/ibm/qradar">ibm.qradar</a></td> + <td><a href="https://github.com/ansible-collections/community.qradar">community.qradar</a></td> + <td><a href="https://github.com/ansible/community/wiki/Security-Automation">Security</a></td> + <td>â</td> + <td></td> + <td>â</td> + <td>Zuul</td> + <td>â</td> + <td><a href="https://docs.ansible.com/ansible/latest/dev_guide/index.html">Developer guide</a></td> + </tr> + <tr> + <td><a href="https://galaxy.ansible.com/junipernetworks/junos">junipernetworks.junos</a></td> + <td><a href="https://galaxy.ansible.com/community/network">community.network</a></td> + <td><a href="https://github.com/ansible/community/wiki/Network">Network</a></td> + <td>â</td> + <td>â</td> + <td>â</td> + <td>Zuul</td> + <td>â</td> + <td><a href="https://docs.ansible.com/ansible/devel/network/dev_guide/index.html">Network guide</a></td> + </tr> + <tr> + <td><a href="https://galaxy.ansible.com/kubernetes/core">kubernetes.core</a></td> + <td><a href="https://galaxy.ansible.com/kubernetes/core">kubernetes.core</a></td> + <td><a href="https://github.com/ansible/community/wiki/Kubernetes">Kubernetes</a></td> + <td>â</td> + <td>â</td> + <td>â</td> + <td>GitHub Actions</td> + <td>â</td> + <td></td> + </tr> + <tr> + <td><a href="https://cloud.redhat.com/ansible/automation-hub/redhat/openshift">redhat.openshift</a></td> + <td><a href="https://galaxy.ansible.com/community/okd">community.okd</a></td> + <td><a href="https://github.com/ansible/community/wiki/Kubernetes">Kubernetes</a></td> + <td>â</td> + <td>â</td> + <td>â</td> + <td>GitHub Actions</td> + <td>â</td> + <td></td> + <tr> + <td><a href="https://galaxy.ansible.com/openvswitch/openvswitch">openvswitch.openvswitch</a></td> + <td><a href="https://galaxy.ansible.com/community/network">community.network</a></td> + <td><a href="https://github.com/ansible/community/wiki/Network">Network</a></td> + <td>â</td> + <td>â</td> + <td>â</td> + <td>Zuul</td> + <td>â</td> + <td><a href="https://docs.ansible.com/ansible/devel/network/dev_guide/index.html">Network guide</a></td> + </tr> + <tr> + <td><a href="https://github.com/ansible-collections/splunk.es">splunk.es</a></td> + <td><a href="https://github.com/ansible-collections/community.es">community.es</a></td> + <td><a href="https://github.com/ansible/community/wiki/Security-Automation">Security</a></td> + <td>â</td> + <td></td> + <td>â</td> + <td>Zuul</td> + <td>â</td> + <td><a href="https://docs.ansible.com/ansible/latest/dev_guide/index.html">Developer guide</a></td> + </tr> + <tr> + <td><a href="https://galaxy.ansible.com/vyos/vyos">vyos.vyos</a></td> + <td><a href="https://galaxy.ansible.com/community/network">community.network</a></td> + <td><a href="https://github.com/ansible/community/wiki/Network">Network</a></td> + <td>â</td> + <td>â</td> + <td>â</td> + <td>Zuul</td> + <td>â</td> + <td><a href="https://docs.ansible.com/ansible/devel/network/dev_guide/index.html">Network guide</a></td> + </tr> + <tr> + <td><a href="https://galaxy.ansible.com/vmware/vmware_rest">vmware.vmware_rest</a></td> + <td><a href="https://galaxy.ansible.com/vmware/vmware_rest">vmware.vmware_rest</a></td> + <td><a href="https://github.com/ansible/community/wiki/VMware">VMware</a></td> + <td>â</td> + <td>â</td> + <td>â</td> + <td>Zuul</td> + <td>â</td> + <td><a href="https://docs.ansible.com/ansible/devel/dev_guide/platforms/vmware_rest_guidelines.html">VMware REST guide</a></td> + </tr> + + </table> + + +.. note:: + + \* A â under **Open to PRs** means the collection welcomes GitHub issues and PRs for any changes to existing collection content (plugins, roles, and so on). + + \*\* Integration tests are required and unit tests are welcomed but not required for the AWS collections. An exception to this is made in cases where integration tests are logistically not feasible due to external requirements. An example of this is AWS Direct Connect, as this service can not be functionally tested without the establishment of network peering connections. Unit tests are therefore required for modules that interact with AWS Direct Connect. Exceptions to ``amazon.aws`` must be approved by Red Hat, and exceptions to ``community.aws`` must be approved by the AWS community. + + \*\*\* ``ansible.netcommon`` contains all foundational components for enabling many network and security :ref:`platform <platform_options>` collections. It contains all connection and filter plugins required, and installs as a dependency when you install the platform collection. + + \*\*\*\* Unit tests for Windows PowerShell modules are an exception to testing, but unit tests are valid and required for the remainder of the collection, including Ansible-side plugins. + + +.. _which_collection: + +Deciding where your contribution belongs +========================================= + +We welcome contributions to Ansible-maintained collections. Because these collections are part of a downstream supported Red Hat product, the criteria for contribution, testing, and release may be higher than other community collections. The related community collections (such as ``community.general`` and ``community.network``) have less-stringent requirements and are a great place for new functionality that may become part of the Ansible-maintained collection in a future release. + +The following scenarios use the ``arista.eos`` to help explain when to contribute to the Ansible-maintained collection, and when to propose your change or idea to the related community collection: + + +1. You want to fix a problem in the ``arista.eos`` Ansible-maintained collection. Create the PR directly in the `arista.eos collection GitHub repository <https://github.com/ansible-collections/arista.eos>`_. Apply all the :ref:`merge requirements <ansible_collection_merge_requirements>`. + +2. You want to add a new Ansible module for Arista. Your options are one of the following: + + * Propose a new module in the ``arista.eos`` collection (requires approval from Arista and Red Hat). + * Propose a new collection in the ``arista`` namespace (requires approval from Arista and Red Hat). + * Propose a new module in the ``community.network`` collection (requires network community approval). + * Place your new module in a collection in your own namespace (no approvals required). + + +Most new content should go into either a related community collection or your own collection first so that is well established in the community before you can propose adding it to the ``arista`` namespace, where inclusion and maintenance criteria are much higher. + + +.. _ansible_collection_merge_requirements: + +Requirements to merge your PR +============================== + +Your PR must meet the following requirements before it can merge into an Ansible-maintained collection: + + +#. The PR is in the intended scope of the collection. Communicate with the appropriate Ansible sponsor listed in the :ref:`Ansible-maintained collection table <ansible-collection-table>` for help. +#. For network and security domains, the PR follows the :ref:`resource module development principles <developing_resource_modules>`. +#. Passes :ref:`sanity tests and tox <tox_resource_modules>`. +#. Passes unit, and integration tests, as listed in the :ref:`Ansible-maintained collection table <ansible-collection-table>` and described in :ref:`testing_resource_modules`. +#. Follows Ansible guidelines. See :ref:`developing_modules` and :ref:`developing_collections`. +#. Addresses all review comments. +#. Includes an appropriate :ref:`changelog <community_changelogs>`. diff --git a/docs/docsite/rst/community/contributions.rst b/docs/docsite/rst/community/contributions.rst new file mode 100644 index 0000000..e3b3eb8 --- /dev/null +++ b/docs/docsite/rst/community/contributions.rst @@ -0,0 +1,29 @@ +.. _community_contributions: + +******************************** +ansible-core Contributors Guide +******************************** + +.. toctree:: + :maxdepth: 2 + + reporting_bugs_and_features + documentation_contributions + development_process + other_tools_and_programs + + +If you have a specific Ansible interest or expertise (for example, VMware, Linode, and so on, consider joining a :ref:`working group <working_group_list>`. + +Working with the Ansible repo +============================= + +* I want to make my first code changes to a collection or to ``ansible-core``. How do I :ref:`set up my Python development environment <environment_setup>`? +* I would like to get more efficient as a developer. How can I find :ref:`editors, linters, and other tools <other_tools_and_programs>` that will support my Ansible development efforts? +* I want my code to meet Ansible's guidelines. Where can I find guidance on :ref:`coding in Ansible <developer_guide>`? +* I would like to connect Ansible to a new API or other resource. How do I :ref:`create a collection <developing_modules_in_groups>`? +* My pull request is marked ``needs_rebase``. How do I :ref:`rebase my PR <rebase_guide>`? +* I am using an older version of Ansible and want a bug fixed in my version that has already been fixed on the ``devel`` branch. How do I :ref:`backport a bugfix PR <backport_process>`? +* I have an open pull request with a failing test. How do I learn about Ansible's :ref:`testing (CI) process <developing_testing>`? +* I am ready to step up as a collection maintainer. What are the :ref:`guidelines for maintainers <maintainers>`? +* A module in a collection I maintain is obsolete. How do I :ref:`deprecate a module <deprecating_modules>`? diff --git a/docs/docsite/rst/community/contributions_collections.rst b/docs/docsite/rst/community/contributions_collections.rst new file mode 100644 index 0000000..f702d59 --- /dev/null +++ b/docs/docsite/rst/community/contributions_collections.rst @@ -0,0 +1,34 @@ +.. _collections_contributions: + +************************************* +Ansible Collections Contributor Guide +************************************* + +.. toctree:: + :maxdepth: 2 + + collection_development_process + reporting_collections + create_pr_quick_start + collection_contributors/test_index + collection_contributors/collection_reviewing + maintainers + contributing_maintained_collections + steering/steering_index + documentation_contributions + other_tools_and_programs + + + +If you have a specific Ansible interest or expertise (for example, VMware, Linode, and so on, consider joining a :ref:`working group <working_group_list>`. + +Working with the Ansible collection repositories +================================================= + +* How can I find :ref:`editors, linters, and other tools <other_tools_and_programs>` that will support my Ansible development efforts? +* Where can I find guidance on :ref:`coding in Ansible <developer_guide>`? +* How do I :ref:`create a collection <developing_modules_in_groups>`? +* How do I :ref:`rebase my PR <rebase_guide>`? +* How do I learn about Ansible's :ref:`testing (CI) process <developing_testing>`? +* How do I :ref:`deprecate a module <deprecating_modules>`? +* See `Collection developer tutorials <https://www.ansible.com/products/ansible-community-training>`_ for a quick introduction on how to develop and test your collection contributions. diff --git a/docs/docsite/rst/community/contributor_license_agreement.rst b/docs/docsite/rst/community/contributor_license_agreement.rst new file mode 100644 index 0000000..b0a0f11 --- /dev/null +++ b/docs/docsite/rst/community/contributor_license_agreement.rst @@ -0,0 +1,7 @@ +.. _contributor_license_agreement: + +****************************** +Contributors License Agreement +****************************** + +By contributing you agree that these contributions are your own (or approved by your employer) and you grant a full, complete, irrevocable copyright license to all users and developers of the project, present and future, pursuant to the license of the project. diff --git a/docs/docsite/rst/community/contributor_path.rst b/docs/docsite/rst/community/contributor_path.rst new file mode 100644 index 0000000..1245058 --- /dev/null +++ b/docs/docsite/rst/community/contributor_path.rst @@ -0,0 +1,114 @@ +**************** +Contributor path +**************** + +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. + +.. contents:: + :local: + + + +Determine your area of interest +================================= + +First, determine areas that are interesting to you. Consider your current experience and what you'd like to gain. For example, if you use a specific collection, have a look there. See :ref:`how_can_i_help` for more ideas on how to help. + +Find the corresponding project +==================================== + +These are multiple community projects in the Ansible ecosystem you could contribute to: + +- `Ansible Core <https://docs.ansible.com/ansible-core/devel/index.html>`_ +- `Collections <https://docs.ansible.com/ansible/latest/user_guide/collections_using.html>`_ +- `AWX <https://github.com/ansible/awx>`_ +- `Galaxy <https://galaxy.ansible.com/>`_ +- `ansible-lint <https://ansible-lint.readthedocs.io/en/latest/>`_ +- `Molecule <https://molecule.readthedocs.io/en/latest/>`_ + +Learn +===== + +The required skillset depends on the area of interest and the project you'll be working on. Remember that the best way to learn is by doing. + +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 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 in-depth when working on 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. + + +Making your first contribution +============================== + +You can find some ideas on how you can contribute in :ref:`how_can_i_help`. + +If you are interested in contributing to collections, take a look at :ref:`collection contributions<collections_contributions>` and the `collection repository <https://github.com/ansible-collections/>`_'s ``README`` and ``CONTRIBUTING`` files. To make your first experience as smooth as possible, read the repository documentation carefully, then ask the repository maintainers for guidance if you have any questions. + +Take a look at GitHub issues labeled with the ``easyfix`` and ``good_first_issue`` labels for: + +- `Ansible collections repositories <https://github.com/search?q=user%3Aansible-collections+label%3Aeasyfix%2C%22good+first+issue%22+state%3Aopen&type=Issues>`_ +- `All other Ansible projects <https://github.com/search?q=user%3Aansible+user%3Aansible-community+label%3Aeasyfix%2C%22good+first+issue%22+state%3Aopen&type=Issues>`_ + +Issues labeled with the ``docs`` label in `Ansible collections <https://github.com/search?q=user%3Aansible-collections+label%3Adocs+state%3Aopen+type%3Aissue&type=Issues>`_ and `other <https://github.com/search?q=user%3Aansible+user%3Aansible-community+label%3Adocs+state%3Aopen+type%3Aissue&type=Issues>`_ Ansible projects can be also good to start with. + +When you choose an issue to work on, add a comment directly on the GitHub issue to say you are looking at it and let others know to avoid conflicting work. +You can also ask for help in a comment if you need it. + +Continue to contribute +====================== + +We don't expect everybody to know everything. Start small, think big. When you contribute regularly, your proficiency and judgment in the related area will improve quickly and, along with this, the importance of your presence in the project. + +See :ref:`communication` for ways to communicate and engage with the Ansible community, including working group meetings, accessing the Bullhorn news bulletin, and upcoming contributor summits. + + +Teach others +============ + +Share your experience with other contributors through :ref:`improving documentation<community_documentation_contributions>`, 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. + +* :ref:`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 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>`_. + +Become a steering committee member +================================== + +.. note:: + + 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 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: + +* Subscribe to, comment on, and vote on the `Community Topics <https://github.com/ansible-community/community-topics/issues>`_. +* Propose your topics. +* If time permits, join the `Community meetings <https://github.com/ansible/community/blob/main/meetings/README.md#schedule>`_. Note this is **NOT** a requirement. diff --git a/docs/docsite/rst/community/create_pr_quick_start.rst b/docs/docsite/rst/community/create_pr_quick_start.rst new file mode 100644 index 0000000..5e4ed02 --- /dev/null +++ b/docs/docsite/rst/community/create_pr_quick_start.rst @@ -0,0 +1,272 @@ +.. _collection_quickstart: + +******************************************** +Creating your first collection pull request +******************************************** + +This section describes all steps needed to create your first patch and submit a pull request on a collection. + +.. _collection_prepare_local: + +Prepare your environment +======================== + +.. note:: + + These steps assume a Linux work environment with ``git`` installed. + + +1. Install and start ``docker`` or ``podman``. This ensures tests run properly isolated and in the same environment as in CI. + +2. :ref:`Install Ansible or ansible-core <installation_guide>`. You need the ``ansible-test`` utility which is provided by either of these packages. + +3. Create the following directories in your home directory: + + .. code-block:: bash + + $ mkdir -p ~/ansible_collections/NAMESPACE/COLLECTION_NAME + + + For example, if the collection is ``community.mysql``, it would be: + + .. code-block:: bash + + $ mkdir -p ~/ansible_collections/community/mysql + + +4. Fork the collection repository through the GitHub web interface. + +5. Clone the forked repository from your profile to the created path: + + .. code-block:: bash + + $ git clone https://github.com/YOURACC/COLLECTION_REPO.git ~/ansible_collections/NAMESPACE/COLLECTION_NAME + + If you prefer to use the SSH protocol: + + .. code-block:: bash + + $ git clone git@github.com:YOURACC/COLLECTION_REPO.git ~/ansible_collections/NAMESPACE/COLLECTION_NAME + +6. Go to your new cloned repository. + + .. code-block:: bash + + $ cd ~/ansible_collections/NAMESPACE/COLLECTION_NAME + +7. Ensure you are in the default branch (it is usually ``main``): + + .. code-block:: bash + + $ git status + +8. Show remotes. There should be the ``origin`` repository only: + + .. code-block:: bash + + $ git remote -v + +9. Add the ``upstream`` repository: + + .. code-block:: bash + + $ git remote add upstream https://github.com/ansible-collections/COLLECTION_REPO.git + + This is the repository where you forked from. + +10. Update your local default branch. Assuming that it is ``main``: + + .. code-block:: bash + + $ git fetch upstream + $ git rebase upstream/main + +11. Create a branch for your changes: + + .. code-block:: bash + + $ git checkout -b name_of_my_branch + +Change the code +=============== + +.. note:: + + 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. + +.. note:: + + If there are any difficulties with writing or running the tests or you are not sure if the case can be covered, you can skip this step. Other contributors can help you with tests later if needed. + +.. note:: + + Some collections do not have integration tests. In this case, unit tests are required. + +All integration tests are stored in ``tests/integration/targets`` subdirectories. +Go to the subdirectory containing the name of the module you are going to change. +For example, if you are fixing the ``mysql_user`` module in the ``community.mysql`` collection, +its tests are in ``tests/integration/targets/test_mysql_user/tasks``. + +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 that reproduces the bug from the issue. + +Put the reported case in the tests, then run integration tests with the following command: + +.. code-block:: bash + + $ ansible-test integration name_of_test_subdirectory --docker -v + +For example, if the test files you changed are stored in ``tests/integration/targets/test_mysql_user/``, the command is as follows: + +.. code-block:: bash + + $ ansible-test integration test_mysql_user --docker -v + +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 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: + +.. code-block:: bash + + $ ansible-test integration name_of_test_subdirectory --docker fedora35 -v + +.. note:: + + If you are not sure whether you should use the default image for testing or a specific one, skip the entire step - the community can help you later. You can also try to use the collection repository's CI to figure out which containers are used. + +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 have failed as expected showing the reported symptoms. + +Fix the bug +============= + +See :ref:`module_contribution` for some general guidelines about Ansible module development that may help you craft a good code fix for the bug. + +Test your changes +================= + +1. Install ``flake8`` (``pip install flake8``, or install the corresponding package on your operating system). + +2. Run ``flake8`` against a changed file: + + .. code-block:: bash + + $ flake8 path/to/changed_file.py + + + 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. + +3. Run sanity tests: + + .. code-block:: bash + + $ ansible-test sanity path/to/changed_file.py --docker -v + + If they failed, look at the output carefully - it is informative and helps to identify a problem line quickly. + Sanity failings usually relate to incorrect code and documentation formatting. + +4. Run integration tests: + + .. code-block:: bash + + $ ansible-test integration name_of_test_subdirectory --docker -v + + For example, if the test files you changed are stored in ``tests/integration/targets/test_mysql_user/``, the command is: + + .. code-block:: bash + + $ ansible-test integration test_mysql_user --docker -v + + You can use the ``-vv`` or ``-vvv`` argument if you need more detailed output. + + +There are two possible outcomes: + +- 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. + +We use `pytest <https://docs.pytest.org/en/latest/>`_ as a testing framework. + +Files with unit tests are stored in the ``tests/unit/plugins/`` directory. If you want to run unit tests, say, for ``tests/unit/plugins/test_myclass.py``, the command is: + +.. code-block:: bash + + $ ansible-test units tests/unit/plugins/test_myclass.py --docker + +If you want to run all unit tests available in the collection, run: + +.. code-block:: bash + + $ ansible-test units --docker + +Submit a pull request +===================== + +1. Commit your changes with an informative but short commit message: + + .. code-block:: bash + + $ git add /path/to/changed/file + $ git commit -m "module_name_you_fixed: fix crash when ..." + +2. Push the branch to ``origin`` (your fork): + + .. code-block:: bash + + $ git push origin name_of_my_branch + +3. In a browser, navigate to the ``upstream`` repository (http://github.com/ansible-collections/COLLECTION_REPO). + +4. Click the :guilabel:`Pull requests` tab. + + 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. + + a. Fill out the pull request template with all information you want to mention. + + b. Put ``Fixes + link to the issue`` in the pull request's description. + + c. Put ``[WIP] + short description`` in the pull request's title. Mention the name of the module/plugin you are modifying at the beginning of the description. + + d. Click :guilabel:`Create pull request`. + +6. Add a :ref:`changelog fragment <collection_changelog_fragments>` to the ``changelogs/fragments`` directory. It will be published in release notes, so users will know about the fix. + + a. Run the sanity test for the fragment: + + .. code-block:: bash + + $ansible-test sanity changelogs/fragments/ --docker -v + + + b. If the tests passed, commit and push the changes: + + .. code-block:: bash + + $ git add changelogs/fragments/myfragment.yml + $ git commit -m "Add changelog fragment" + $ git push origin name_of_my_branch + +7. Verify the CI tests pass that run automatically on Red Hat infrastructure after every commit. + + 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 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. + +For more in-depth details on this process, see the :ref:`Ansible developer guide <developer_guide>`. diff --git a/docs/docsite/rst/community/development_process.rst b/docs/docsite/rst/community/development_process.rst new file mode 100644 index 0000000..26f8735 --- /dev/null +++ b/docs/docsite/rst/community/development_process.rst @@ -0,0 +1,368 @@ +.. _community_development_process: + +***************************** +The Ansible Development Cycle +***************************** + +Ansible developers (including community contributors) add new features, fix bugs, and update code in many different repositories. The `ansible/ansible repository <https://github.com/ansible/ansible>`_ contains the code for basic features and functions, such as copying module code to managed nodes. This code is also known as ``ansible-core``. Other repositories contain plugins and modules that enable Ansible to execute specific tasks, like adding a user to a particular database or configuring a particular network device. These repositories contain the source code for collections. + +Development on ``ansible-core`` occurs on two levels. At the macro level, the ``ansible-core`` developers and maintainers plan releases and track progress with roadmaps and projects. At the micro level, each PR has its own lifecycle. + +Development on collections also occurs at the macro and micro levels. Each collection has its own macro development cycle. For more information on the collections development cycle, see :ref:`contributing_maintained_collections`. The micro-level lifecycle of a PR is similar in collections and in ``ansible-core``. + +.. contents:: + :local: + +Macro development: ``ansible-core`` roadmaps, releases, and projects +===================================================================== + +If you want to follow the conversation about what features will be added to ``ansible-core`` for upcoming releases and what bugs are being fixed, you can watch these resources: + +* the :ref:`roadmaps` +* the :ref:`Ansible Release Schedule <release_and_maintenance>` +* the :ref:`ansible-core project branches and tags <core_branches_and_tags>` +* various GitHub `projects <https://github.com/ansible/ansible/projects>`_ - for example: + + * the `2.15 release project <https://github.com/ansible/ansible/projects/46>`_ + * the `core documentation project <https://github.com/orgs/ansible/projects/94/views/1>`_ + + +.. _community_pull_requests: + + +Micro development: the lifecycle of a PR +======================================== + +If you want to contribute a feature or fix a bug in ``ansible-core`` or in a collection, you must open a **pull request** ("PR" for short). GitHub provides a great overview of `how the pull request process works <https://help.github.com/articles/about-pull-requests/>`_ in general. The ultimate goal of any pull request is to get merged and become part of a collection or ``ansible-core``. +Here's an overview of the PR lifecycle: + +* Contributor opens a PR (always against the ``devel`` branch) +* Ansibot reviews the PR +* Ansibot assigns labels +* Ansibot pings maintainers +* Azure Pipelines runs the test suite +* Developers, maintainers, community review the PR +* Contributor addresses any feedback from reviewers +* Developers, maintainers, community re-review +* PR merged or closed +* PR :ref:`backported <backport_process>` to one or more ``stable-X.Y`` branches (optional, bugfixes only) + +Automated PR review: ansibullbot +-------------------------------- + +Because Ansible receives many pull requests, and because we love automating things, we have automated several steps of the process of reviewing and merging pull requests with a tool called Ansibullbot, or Ansibot for short. + +`Ansibullbot <https://github.com/ansible/ansibullbot/blob/master/ISSUE_HELP.md>`_ serves many functions: + +- Responds quickly to PR submitters to thank them for submitting their PR +- Identifies the community maintainer responsible for reviewing PRs for any files affected +- Tracks the current status of PRs +- Pings responsible parties to remind them of any PR actions for which they may be responsible +- Provides maintainers with the ability to move PRs through the workflow +- Identifies PRs abandoned by their submitters so that we can close them +- Identifies modules abandoned by their maintainers so that we can find new maintainers + +Ansibot workflow +^^^^^^^^^^^^^^^^ + +Ansibullbot runs continuously. You can generally expect to see changes to your issue or pull request within thirty minutes. Ansibullbot examines every open pull request in the repositories, and enforces state roughly according to the following workflow: + +- If a pull request has no workflow labels, it's considered **new**. Files in the pull request are identified, and the maintainers of those files are pinged by the bot, along with instructions on how to review the pull request. (Note: sometimes we strip labels from a pull request to "reboot" this process.) +- If the module maintainer is not ``$team_ansible``, the pull request then goes into the **community_review** state. +- If the module maintainer is ``$team_ansible``, the pull request then goes into the **core_review** state (and probably sits for a while). +- If the pull request is in **community_review** and has received comments from the maintainer: + + - If the maintainer says ``shipit``, the pull request is labeled **shipit**, whereupon the Core team assesses it for final merge. + - If the maintainer says ``needs_info``, the pull request is labeled **needs_info** and the submitter is asked for more info. + - If the maintainer says **needs_revision**, the pull request is labeled **needs_revision** and the submitter is asked to fix some things. + +- If the submitter says ``ready_for_review``, the pull request is put back into **community_review** or **core_review** and the maintainer is notified that the pull request is ready to be reviewed again. +- If the pull request is labeled **needs_revision** or **needs_info** and the submitter has not responded lately: + + - The submitter is first politely pinged after two weeks, pinged again after two more weeks and labeled **pending action**, and the issue or pull request will be closed two weeks after that. + - If the submitter responds at all, the clock is reset. +- If the pull request is labeled **community_review** and the reviewer has not responded lately: + + - The reviewer is first politely pinged after two weeks, pinged again after two more weeks and labeled **pending_action**, and then may be reassigned to ``$team_ansible`` or labeled **core_review**, or often the submitter of the pull request is asked to step up as a maintainer. +- If Azure Pipelines tests fail, or if the code is not able to be merged, the pull request is automatically put into **needs_revision** along with a message to the submitter explaining why. + +There are corner cases and frequent refinements, but this is the workflow in general. + +PR labels +^^^^^^^^^ + +There are two types of PR Labels generally: **workflow** labels and **information** labels. + +Workflow labels +""""""""""""""" + +- **community_review**: Pull requests for modules that are currently awaiting review by their maintainers in the Ansible community. +- **core_review**: Pull requests for modules that are currently awaiting review by their maintainers on the Ansible Core team. +- **needs_info**: Waiting on info from the submitter. +- **needs_rebase**: Waiting on the submitter to rebase. +- **needs_revision**: Waiting on the submitter to make changes. +- **shipit**: Waiting for final review by the core team for potential merge. + +Information labels +"""""""""""""""""" + +- **backport**: this is applied automatically if the PR is requested against any branch that is not devel. The bot immediately assigns the labels backport and ``core_review``. +- **bugfix_pull_request**: applied by the bot based on the templatized description of the PR. +- **cloud**: applied by the bot based on the paths of the modified files. +- **docs_pull_request**: applied by the bot based on the templatized description of the PR. +- **easyfix**: applied manually, inconsistently used but sometimes useful. +- **feature_pull_request**: applied by the bot based on the templatized description of the PR. +- **networking**: applied by the bot based on the paths of the modified files. +- **owner_pr**: largely deprecated. Formerly workflow, now informational. Originally, PRs submitted by the maintainer would automatically go to **shipit** based on this label. If the submitter is also a maintainer, we notify the other maintainers and still require one of the maintainers (including the submitter) to give a **shipit**. +- **pending_action**: applied by the bot to PRs that are not moving. Reviewed every couple of weeks by the community team, who tries to figure out the appropriate action (closure, asking for new maintainers, and so on). + + +Special Labels +"""""""""""""" + +- **new_plugin**: this is for new modules or plugins that are not yet in Ansible. + +**Note:** `new_plugin` kicks off a completely separate process, and frankly it doesn't work very well at present. We're working our best to improve this process. + +Human PR review +--------------- + +After Ansibot reviews the PR and applies labels, the PR is ready for human review. The most likely reviewers for any PR are the maintainers for the module that PR modifies. + +Each module has at least one assigned :ref:`maintainer <maintainers>`, listed in the `BOTMETA.yml <https://github.com/ansible/ansible/blob/devel/.github/BOTMETA.yml>`_ file. + +The maintainer's job is to review PRs that affect that module and decide whether they should be merged (``shipit``) or revised (``needs_revision``). We'd like to have at least one community maintainer for every module. If a module has no community maintainers assigned, the maintainer is listed as ``$team_ansible``. + +Once a human applies the ``shipit`` label, the :ref:`committers <community_committer_guidelines>` decide whether the PR is ready to be merged. Not every PR that gets the ``shipit`` label is actually ready to be merged, but the better our reviewers are, and the better our guidelines are, the more likely it will be that a PR that reaches **shipit** will be mergeable. + + +Making your PR merge-worthy +=========================== + +We do not merge every PR. Here are some tips for making your PR useful, attractive, and merge-worthy. + +.. _community_changelogs: + +Creating changelog fragments +------------------------------ + +Changelogs help users and developers keep up with changes to ansible-core and Ansible collections. Ansible and many collections build changelogs for each release from fragments. For ansible-core and collections using 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: + +* add new modules and plugins, because Ansible tooling does that automatically; +* contain only documentation changes. + +.. note:: + Some collections require a changelog fragment for every pull request. They use the ``trivial:`` section for entries mentioned above that will be skipped when building a release changelog. + + +More precisely: + +* Every bugfix PR must have a changelog fragment. The only exception are fixes to a change that has not yet been included in a release. +* Every feature PR must have a changelog fragment. +* New modules and plugins (including jinja2 filter and test plugins) must have ``version_added`` entries set correctly in their documentation, and do not need a changelog fragment. The tooling detects new modules and plugins by their ``version_added`` values and announces them in the next release's changelog automatically. + +We build short summary changelogs for minor releases as well as for major releases. If you backport a bugfix, include a changelog fragment with the backport PR. + +.. _changelogs_how_to: + +Creating a changelog fragment +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A basic changelog fragment is a ``.yaml`` or ``.yml`` file placed in the ``changelogs/fragments/`` directory. Each file contains a yaml dict with keys like ``bugfixes`` or ``major_changes`` followed by a list of changelog entries of bugfixes or features. Each changelog entry is rst embedded inside of the yaml file which means that certain constructs would need to be escaped so they can be interpreted by rst and not by yaml (or escaped for both yaml and rst if you prefer). Each PR **must** use a new fragment file rather than adding to an existing one, so we can trace the change back to the PR that introduced it. + +PRs which add a new module or plugin do not necessarily need a changelog fragment. See the previous section :ref:`community_changelogs`. Also see the next section :ref:`changelogs_how_to_format` for the precise format changelog fragments should have. + +To create a changelog entry, create a new file with a unique name in the ``changelogs/fragments/`` directory of the corresponding repository. The file name should include the PR number and a description of the change. It must end with the file extension ``.yaml`` or ``.yml``. For example: ``40696-user-backup-shadow-file.yaml`` + +A single changelog fragment may contain multiple sections but most will only contain one section. The toplevel keys (bugfixes, major_changes, and so on) are defined in the `config file <https://github.com/ansible/ansible/blob/devel/changelogs/config.yaml>`_ for our `release note tool <https://github.com/ansible-community/antsibull-changelog/blob/main/docs/changelogs.rst>`_. Here are the valid sections and a description of each: + +**breaking_changes** + MUST include changes that break existing playbooks or roles. This includes any change to existing behavior that forces users to update tasks. Breaking changes means the user MUST make a change when they update. Breaking changes MUST only happen in a major release of the collection. Write in present tense and clearly describe the new behavior that the end user must now follow. Displayed in both the changelogs and the :ref:`Porting Guides <porting_guides>`. + + .. code-block:: yaml + + breaking_changes: + - ansible-test - automatic installation of requirements for cloud test plugins no longer occurs. The affected test plugins are ``aws``, ``azure``, ``cs``, ``hcloud``, ``nios``, ``opennebula``, ``openshift`` and ``vcenter``. Collections should instead use one of the supported integration test requirements files, such as the ``tests/integration/requirements.txt`` file (https://github.com/ansible/ansible/pull/75605). + + +**major_changes** + Major changes to ansible-core or a collection. SHOULD NOT include individual module or plugin changes. MUST include non-breaking changes that impact all or most of a collection (for example, updates to support a new SDK version across the collection). Major changes mean the user can CHOOSE to make a change when they update but do not have to. Could be used to announce an important upcoming EOL or breaking change in a future release. (ideally 6 months in advance, if known. See `this example <https://github.com/ansible-collections/community.general/blob/stable-1/CHANGELOG.rst#v1313>`_). Write in present tense and describe what is new. Optionally, include a 'Previously..." sentence to help the user identify where old behavior should now change. Displayed in both the changelogs and the :ref:`Porting Guides <porting_guides>`. + + .. code-block:: yaml + + major_changes: + - ansible-test - all cloud plugins which use containers can now be used with all POSIX and Windows hosts. Previously the plugins did not work with Windows at all, and support for hosts created with the ``--remote`` option was inconsistent (https://github.com/ansible/ansible/pull/74216). + +**minor_changes** + Minor changes to ansible-core, modules, or plugins. This includes new parameters added to modules, or non-breaking behavior changes to existing parameters, such as adding additional values to choices[]. Minor changes are enhancements, not bug fixes. Write in present tense. + + .. code-block:: yaml + + minor_changes: + - lineinfile - add warning when using an empty regexp (https://github.com/ansible/ansible/issues/29443). + + +**deprecated_features** + Features that have been deprecated and are scheduled for removal in a future release. Use past tense and include an alternative, where available for what is being deprecated.. Displayed in both the changelogs and the :ref:`Porting Guides <porting_guides>`. + + .. code-block:: yaml + + deprecated_features: + - include action - is deprecated in favor of ``include_tasks``, ``import_tasks`` and ``import_playbook`` (https://github.com/ansible/ansible/pull/71262). + + +**removed_features** + Features that were previously deprecated and are now removed. Use past tense and include an alternative, where available for what is being deprecated. Displayed in both the changelogs and the :ref:`Porting Guides <porting_guides>`. + + .. code-block:: yaml + + removed_features: + - _get_item() alias - removed from callback plugin base class which had been deprecated in favor of ``_get_item_label()`` (https://github.com/ansible/ansible/pull/70233). + + +**security_fixes** + Fixes that address CVEs or resolve security concerns. MUST use security_fixes for any CVEs. Use present tense. Include links to CVE information. + + .. code-block:: yaml + + security_fixes: + - set_options -do not include params in exception when a call to ``set_options`` fails. Additionally, block the exception that is returned from being displayed to stdout. (CVE-2021-3620). + + +**bugfixes** + Fixes that resolve issues. SHOULD not be used for minor enhancements (use ``minor_change`` instead). Use past tense to describe the problem and present tense to describe the fix. + + .. code-block:: yaml + + bugfixes: + - ansible_play_batch - variable included unreachable hosts. Fix now saves unreachable hosts between plays by adding them to the PlayIterator's ``_play._removed_hosts`` (https://github.com/ansible/ansible/issues/66945). + + +**known_issues** + Known issues that are currently not fixed or will not be fixed. Use present tense and where available, use imperative tense for a workaround. + + .. code-block:: yaml + + known_issues: + - ansible-test - tab completion anywhere other than the end of the command with the new composite options provides incorrect results (https://github.com/kislyuk/argcomplete/issues/351). + + +Each changelog entry must contain a link to its issue between parentheses at the end. If there is no corresponding issue, the entry must contain a link to the PR itself. + +Most changelog entries are ``bugfixes`` or ``minor_changes``. The changelog tool also supports ``trivial``, which are not listed in the actual changelog output but are used by collections repositories that require a changelog fragment for each PR. + + + +.. _changelogs_how_to_format: + +Changelog fragment entry format +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When writing a changelog entry, use the following format: + +.. code-block:: yaml + + - scope - description starting with a lowercase letter and ending with a period at the very end. Multiple sentences are allowed (https://github.com/reference/to/an/issue or, if there is no issue, reference to a pull request itself). + +The scope is usually a module or plugin name or group of modules or plugins, for example, ``lookup plugins``. While module names can (and should) be mentioned directly (``foo_module``), plugin names should always be followed by the type (``foo inventory plugin``). + +For changes that are not really scoped (for example, which affect a whole collection), use the following format: + +.. code-block:: yaml + + - Description starting with an uppercase letter and ending with a dot at the very end. Multiple sentences are allowed (https://github.com/reference/to/an/issue or, if there is no issue, reference to a pull request itself). + + +Here are some examples: + +.. code-block:: yaml + + bugfixes: + - apt_repository - fix crash caused by ``cache.update()`` raising an ``IOError`` + due to a timeout in ``apt update`` (https://github.com/ansible/ansible/issues/51995). + +.. code-block:: yaml + + minor_changes: + - lineinfile - add warning when using an empty regexp (https://github.com/ansible/ansible/issues/29443). + +.. code-block:: yaml + + bugfixes: + - copy - the module was attempting to change the mode of files for + remote_src=True even if mode was not set as a parameter. This failed on + filesystems which do not have permission bits (https://github.com/ansible/ansible/issues/29444). + +You can find more example changelog fragments in the `changelog directory <https://github.com/ansible/ansible/tree/stable-2.12/changelogs/fragments>`_ for the 2.12 release. + +After you have written the changelog fragment for your PR, commit the file and include it with the pull request. + +.. _changelogs_how_to_format_playbooks: + +Changelog fragment entry format for new playbooks +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +While new modules, plugins, and roles are mentioned automatically in the generated changelog, playbooks are not. To make sure they are mentioned, a changelog fragment in a specific format is needed: + +.. code-block:: yaml + + # A new playbook: + add object.playbook: + - # This should be the short (non-FQCN) name of the playbook. + name: wipe_server + # The description should be in the same format as short_description for + # plugins and modules: it should start with an upper-case letter and + # not have a period at the end. + description: Wipes a server + +.. _backport_process: + +Backporting merged PRs in ``ansible-core`` +=========================================== + +All ``ansible-core`` PRs must be merged to the ``devel`` branch first. After a pull request has been accepted and merged to the ``devel`` branch, the following instructions will help you create a pull request to backport the change to a previous stable branch. + +We do **not** backport features. + +.. note:: + + These instructions assume that: + + * ``stable-2.14`` is the targeted release branch for the backport + * ``https://github.com/ansible/ansible.git`` is configured as a ``git remote`` named ``upstream``. If you do not use a ``git remote`` named ``upstream``, adjust the instructions accordingly. + * ``https://github.com/<yourgithubaccount>/ansible.git`` is configured as a ``git remote`` named ``origin``. If you do not use a ``git remote`` named ``origin``, adjust the instructions accordingly. + +#. Prepare your devel, stable, and feature branches: + +.. code-block:: shell + + git fetch upstream + git checkout -b backport/2.14/[PR_NUMBER_FROM_DEVEL] upstream/stable-2.14 + +#. Cherry pick the relevant commit SHA from the devel branch into your feature branch, handling merge conflicts as necessary: + +.. code-block:: shell + + git cherry-pick -x [SHA_FROM_DEVEL] + +#. Add a :ref:`changelog fragment <changelogs_how_to>` for the change, and commit it. + +#. Push your feature branch to your fork on GitHub: + +.. code-block:: shell + + git push origin backport/2.14/[PR_NUMBER_FROM_DEVEL] + +#. Submit the pull request for ``backport/2.14/[PR_NUMBER_FROM_DEVEL]`` against the ``stable-2.14`` branch + +#. The Release Manager will decide whether to merge the backport PR before the next minor release. There isn't any need to follow up. Just ensure that the automated tests (CI) are green. + +.. note:: + + The branch name ``backport/2.14/[PR_NUMBER_FROM_DEVEL]`` is somewhat arbitrary but conveys meaning about the purpose of the branch. This branch name format is not required, but it can be helpful, especially when making multiple backport PRs for multiple stable branches. + +.. note:: + + If you prefer, you can use CPython's cherry-picker tool (``pip install --user 'cherry-picker >= 1.3.2'``) to backport commits from devel to stable branches in Ansible. Take a look at the `cherry-picker documentation <https://pypi.org/p/cherry-picker#cherry-picking>`_ for details on installing, configuring, and using it. diff --git a/docs/docsite/rst/community/documentation_contributions.rst b/docs/docsite/rst/community/documentation_contributions.rst new file mode 100644 index 0000000..0f464f1 --- /dev/null +++ b/docs/docsite/rst/community/documentation_contributions.rst @@ -0,0 +1,237 @@ +.. _community_documentation_contributions: + +***************************************** +Contributing to the Ansible Documentation +***************************************** + +Ansible has a lot of documentation and a small team of writers. Community support helps us keep up with new features, fixes, and changes. + +Improving the documentation is an easy way to make your first contribution to the Ansible project. You do not have to be a programmer, since most of our documentation is written in YAML (module documentation) or `reStructuredText <https://docutils.sourceforge.io/rst.html>`_ (rST). Some collection-level documentation is written in a subset of `Markdown <https://github.com/ansible/ansible/issues/68119#issuecomment-596723053>`_. If you are using Ansible, you already use YAML in your playbooks. rST and Markdown are mostly just text. You do not even need git experience, if you use the ``Edit on GitHub`` option. + +If you find a typo, a broken example, a missing topic, or any other error or omission on this documentation website, let us know. Here are some ways to support Ansible documentation: + +.. contents:: + :local: + +Editing docs directly on GitHub +=============================== + +For typos and other quick fixes, you can edit most of the documentation right from the site. Look at the top right corner of this page. That ``Edit on GitHub`` link is available on all the guide pages in the documentation. If you have a GitHub account, you can submit a quick and easy pull request this way. + +.. note:: + + The source files for individual collection plugins exist in their respective repositories. Follow the link to the collection on Galaxy to find where the repository is located and any guidelines on how to contribute to that collection. + +To submit a documentation PR from docs.ansible.com with ``Edit on GitHub``: + +#. Click on ``Edit on GitHub``. +#. If you don't already have a fork of the ansible repo on your GitHub account, you'll be prompted to create one. +#. Fix the typo, update the example, or make whatever other change you have in mind. +#. Enter a commit message in the first rectangle under the heading ``Propose file change`` at the bottom of the GitHub page. The more specific, the better. For example, "fixes typo in my_module description". You can put more detail in the second rectangle if you like. Leave the ``+label: docsite_pr`` there. +#. Submit the suggested change by clicking on the green "Propose file change" button. GitHub will handle branching and committing for you, and open a page with the heading "Comparing Changes". +#. Click on ``Create pull request`` to open the PR template. +#. Fill out the PR template, including as much detail as appropriate for your change. You can change the title of your PR if you like (by default it's the same as your commit message). In the ``Issue Type`` section, delete all lines except the ``Docs Pull Request`` line. +#. Submit your change by clicking on ``Create pull request`` button. +#. Be patient while Ansibot, our automated script, adds labels, pings the docs maintainers, and kicks off a CI testing run. +#. Keep an eye on your PR - the docs team may ask you for changes. + +Reviewing or solving open issues +================================ + +Review or solve open documentation issues for: + +- `Ansible projects <https://github.com/search?q=user%3Aansible+user%3Aansible-community+label%3Adocs+state%3Aopen+type%3Aissue&type=Issues>`_ +- `Ansible collections <https://github.com/search?q=user%3Aansible-collections+label%3Adocs+state%3Aopen+type%3Aissue&type=Issues>`_ + +Reviewing open PRs +================== + +Review open documentation pull requests for: + +- Ansible `projects <https://github.com/search?q=user%3Aansible+user%3Aansible-community+label%3Adocs+state%3Aopen+type%3Apr>`_ +- Ansible `collections <https://github.com/search?q=user%3Aansible-collections+label%3Adocs+state%3Aopen+type%3Apr>`_ + +To add a helpful review, please: + +- Test the change if applicable. +- Think if it can be made better (including wording, structure, fixing typos and so on). +- Suggest improvements. +- Approve the change with the ``looks good to me`` comment. + +Opening a new issue and/or PR +============================= + +If the problem you have noticed is too complex to fix with the ``Edit on GitHub`` option, and no open issue or PR already documents the problem, please open an issue and/or a PR on the correct underlying repo - ``ansible/ansible`` for most pages that are not plugin or module documentation. If the documentation page has no ``Edit on GitHub`` option, check if the page is for a module within a collection. If so, follow the link to the collection on Galaxy and select the ``repo`` button in the upper right corner to find the source repository for that collection and module. The Collection README file should contain information on how to contribute to that collection, or report issues. + +A great documentation GitHub issue or PR includes: + +- a specific title +- a detailed description of the problem (even for a PR - it's hard to evaluate a suggested change unless we know what problem it's meant to solve) +- links to other information (related issues/PRs, external documentation, pages on docs.ansible.com, and so on) + + +Verifying your documentation PR +================================ + +If you make multiple changes to the documentation on ``ansible/ansible``, or add more than a line to it, before you open a pull request, please: + +#. Check that your text follows our :ref:`style_guide`. +#. Test your changes for rST errors. +#. Build the page, and preferably the entire documentation site, locally. + +.. note:: + + The following sections apply to documentation sourced from the ``ansible/ansible`` repo and does not apply to documentation from an individual collection. See the collection README file for details on how to contribute to that collection. + +Setting up your environment to build documentation locally +---------------------------------------------------------- + +To build documentation locally, ensure you have a working :ref:`development environment <environment_setup>`. + +To work with documentation on your local machine, you need to have python-3.9 or greater and install the `Ansible dependencies`_ and `documentation dependencies`_, which are listed in two files to make installation easier: + +.. _Ansible dependencies: https://github.com/ansible/ansible/blob/devel/requirements.txt +.. _documentation dependencies: https://github.com/ansible/ansible/blob/devel/docs/docsite/requirements.txt + +.. code-block:: bash + + pip install --user -r requirements.txt + pip install --user -r docs/docsite/requirements.txt + +The :file:`docs/docsite/requirements.txt` file allows a wide range of versions and may install new releases of required packages. New releases of these packages may cause problems with the Ansible docs build. If you want to install tested versions of these dependencies, use :file:`test/sanity/code-smell/docs-build.requirements.txt` instead, which matches the dependencies used by CI: + +.. code-block:: bash + + pip install --user -r requirements.txt + pip install --user -r test/sanity/code-smell/docs-build.requirements.txt + + + +You can drop ``--user`` if you have set up a virtual environment (venv/virtenv). + +.. note:: + + You may need to install these general pre-requisites separately on some systems: + - ``gcc`` + - ``libyaml`` + - ``make`` + - ``pyparsing`` + - ``six`` + On macOS with Xcode, you may need to install ``six`` and ``pyparsing`` with ``--ignore-installed`` to get versions that work with ``sphinx``. + +.. note:: + + After checking out ``ansible/ansible``, make sure the ``docs/docsite/rst`` directory has strict enough permissions. It should only be writable by the owner's account. If your default ``umask`` is not 022, you can use ``chmod go-w docs/docsite/rst`` to set the permissions correctly in your new branch. Optionally, you can set your ``umask`` to 022 to make all newly created files on your system (including those created by ``git clone``) have the correct permissions. + +.. _testing_documentation_locally: + +Testing the documentation locally +--------------------------------- + +To test an individual file for rST errors: + +.. code-block:: bash + + rstcheck changed_file.rst + +Building the documentation locally +---------------------------------- + +Building the documentation is the best way to check for errors and review your changes. Once `rstcheck` runs with no errors, navigate to ``ansible/docs/docsite`` and then build the page(s) you want to review. + + .. note:: + + If building on macOS with Python 3.8 or later, you must use Sphinx >= 2.2.2. See `#6803 <https://github.com/sphinx-doc/sphinx/pull/6879>`_ for details. + + + +Building a single rST page +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To build a single rST file with the make utility: + +.. code-block:: bash + + make htmlsingle rst=path/to/your_file.rst + +For example: + +.. code-block:: bash + + make htmlsingle rst=community/documentation_contributions.rst + +This process compiles all the links but provides minimal log output. If you're writing a new page or want more detailed log output, refer to the instructions on :ref:`build_with_sphinx-build` + +.. note:: + + ``make htmlsingle`` adds ``rst/`` to the beginning of the path you provide in ``rst=``, so you can't type the filename with autocomplete. Here are the error messages you will see if you get this wrong: + + - If you run ``make htmlsingle`` from the ``docs/docsite/rst/`` directory: ``make: *** No rule to make target `htmlsingle'. Stop.`` + - If you run ``make htmlsingle`` from the ``docs/docsite/`` directory with the full path to your rST document: ``sphinx-build: error: cannot find files ['rst/rst/community/documentation_contributions.rst']``. + + +Building all the rST pages +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To build all the rST files without any module documentation: + +.. code-block:: bash + + MODULES=none make webdocs + +Building module docs and rST pages +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To build documentation for a few modules included in ``ansible/ansible`` plus all the rST files, use a comma-separated list: + +.. code-block:: bash + + MODULES=one_module,another_module make webdocs + +To build all the module documentation plus all the rST files: + +.. code-block:: bash + + make webdocs + +.. _build_with_sphinx-build: + +Building rST files with ``sphinx-build`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Advanced users can build one or more rST files with the sphinx utility directly. ``sphinx-build`` returns misleading ``undefined label`` warnings if you only build a single page, because it does not create internal links. However, ``sphinx-build`` returns more extensive syntax feedback, including warnings about indentation errors and ``x-string without end-string`` warnings. This can be useful, especially if you're creating a new page from scratch. To build a page or pages with ``sphinx-build``: + +.. code-block:: bash + + sphinx-build [options] sourcedir outdir [filenames...] + +You can specify filenames, or ``âa`` for all files, or omit both to compile only new/changed files. + +For example: + +.. code-block:: bash + + sphinx-build -b html -c rst/ rst/dev_guide/ _build/html/dev_guide/ rst/dev_guide/developing_modules_documenting.rst + +Running the final tests +^^^^^^^^^^^^^^^^^^^^^^^ + +When you submit a documentation pull request, automated tests are run. Those same tests can be run locally. To do so, navigate to the repository's top directory and run: + +.. code-block:: bash + + make clean && + bin/ansible-test sanity --test docs-build && + bin/ansible-test sanity --test rstcheck + +Unfortunately, leftover rST-files from previous document-generating can occasionally confuse these tests. It is therefore safest to run them on a clean copy of the repository, which is the purpose of ``make clean``. If you type these three lines one at a time and manually check the success of each, you do not need the ``&&``. + +Joining the documentation working group +======================================= + +The Documentation Working Group (DaWGs) meets weekly on Tuesdays in the Docs chat (using `Matrix <https://matrix.to/#/#docs:ansible.im>`_ or using IRC at `irc.libera.chat <https://libera.chat/>`_). For more information, including links to our agenda and a calendar invite, please visit the `working group page in the community repo <https://github.com/ansible/community/wiki/Docs>`_. + +.. seealso:: + :ref:`More about testing module documentation <testing_module_documentation>` + + :ref:`More about documenting modules <module_documenting>` diff --git a/docs/docsite/rst/community/getting_started.rst b/docs/docsite/rst/community/getting_started.rst new file mode 100644 index 0000000..b352251 --- /dev/null +++ b/docs/docsite/rst/community/getting_started.rst @@ -0,0 +1,33 @@ +.. _community_getting_started: + +**************** +Getting started +**************** + +Welcome and thank you for getting more involved with the Ansible community. Here are some ways you can get started. + +.. toctree:: + :maxdepth: 2 + + code_of_conduct + contributor_license_agreement + communication + how_can_I_help + + + +Other ways to get involved +========================== + +Here are some other ways to connect with the Ansible community: + +* Find an `Ansible Meetup near me <https://www.meetup.com/topics/ansible/>`_ + communication +* Learn more about Ansible: + + * `Read books <https://www.ansible.com/resources/ebooks>`_. + * `Get certified <https://www.ansible.com/products/training-certification>`_. + * `Attend events <https://www.ansible.com/community/events>`_. + * `Review getting started guides <https://www.ansible.com/resources/get-started>`_. + * `Watch videos <https://www.ansible.com/resources/videos>`_ - includes Ansible Automates, AnsibleFest & webinar recordings. +* See where `new releases are announced <https://groups.google.com/forum/#!forum/ansible-announce>`_ diff --git a/docs/docsite/rst/community/github_admins.rst b/docs/docsite/rst/community/github_admins.rst new file mode 100644 index 0000000..802b180 --- /dev/null +++ b/docs/docsite/rst/community/github_admins.rst @@ -0,0 +1,32 @@ +.. _github_admins: + +************* +GitHub Admins +************* + +.. contents:: Topics + +GitHub Admins have more permissions on GitHub than normal contributors or even committers. There are +a few responsibilities that come with that increased power. + + +Adding and removing committers +============================== + +The Ansible Team will periodically review who is actively contributing to Ansible to grant or revoke +contributors' ability to commit on their own. GitHub Admins are the people who have the power to +actually manage the GitHub permissions. + + +Changing branch permissions for releases +======================================== + +When we make releases we make people go through a :ref:`release_managers` to push commits to that +branch. The GitHub admins are responsible for setting the branch so only the Release Manager can +commit to the branch when the release process reaches that stage and later opening the branch once +the release has been made. The Release manager will let the GitHub Admin know when this needs to be +done. + +.. seealso:: The `GitHub Admin Process Docs + <https://docs.google.com/document/d/1gWPtxNX4J39uIzwqQWLIsTZ1dY_AwEZzAd9bJ4XtZso/edit#heading=h.2wezayw9xsqz>`_ for instructions + on how to change branch permissions. diff --git a/docs/docsite/rst/community/how_can_I_help.rst b/docs/docsite/rst/community/how_can_I_help.rst new file mode 100644 index 0000000..38cb1db --- /dev/null +++ b/docs/docsite/rst/community/how_can_I_help.rst @@ -0,0 +1,97 @@ +.. _how_can_i_help: + +*************** +How can I help? +*************** + +.. contents:: + :local: + +Thanks for being interested in helping the Ansible project! + +There are many ways to help the Ansible project...but first, please read and understand the :ref:`code_of_conduct`. + +Become a power user +=================== + +A great way to help the Ansible project is to become a power user: + +* Use Ansible everywhere you can +* Take tutorials and classes +* Read the :ref:`official documentation <ansible_documentation>` +* Study some of the `many excellent books <https://www.amazon.com/s/ref=nb_sb_ss_c_2_7?url=search-alias%3Dstripbooks&field-keywords=ansible&sprefix=ansible%2Caps%2C260>`_ about Ansible +* `Get certified <https://www.ansible.com/products/training-certification>`_. + +When you become a power user, your ability and opportunities to help the Ansible project in other ways will multiply quickly. + +Ask and answer questions online +=============================== + +There are many forums online where Ansible users ask and answer questions. Reach out and communicate with your fellow Ansible users. + +You can find the official :ref:`Ansible communication channels <communication>`. + +Review, fix, and maintain the documentation +=========================================== + +Typos are everywhere, even in the Ansible documentation. We work hard to keep the documentation up-to-date, but you may also find outdated examples. We offer easy ways to :ref:`report and/or fix documentation errors <community_documentation_contributions>`. + +.. _ansible_community_meetup: + +Participate in your local meetup +================================ + +There are Ansible meetups `all over the world <https://www.meetup.com/topics/ansible/>`_. Join your local meetup. Attend regularly. Ask good questions. Volunteer to give a presentation about how you use Ansible. + +If there is no meetup near you, we are happy to help you `start one <https://www.ansible.com/community/events/ansible-meetups>`_. + +File and verify issues +====================== + +All software has bugs, and Ansible is no exception. When you find a bug, you can help tremendously by telling us about it: + +* Filing :ref:`issues for ansible-core <reporting_bugs_and_features>`. +* Filing :ref:`issues for collections <reporting_bugs_in_collections>`. + + +If the bug you found already exists in an issue, you can help by verifying the behavior of the reported bug with a comment in that issue, or by reporting any additional information. + +Review and submit pull requests +=============================== + +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. + +You can also get started with solving GitHub issues labeled with the ``easyfix`` and ``good_first_issue`` labels for: + +- `Ansible collections <https://github.com/search?q=user%3Aansible-collections+label%3Aeasyfix%2C%22good+first+issue%22+state%3Aopen&type=Issues>`_ +- `All other Ansible projects <https://github.com/search?q=user%3Aansible+user%3Aansible-community+label%3Aeasyfix%2C%22good+first+issue%22+state%3Aopen&type=Issues>`_ + +When you choose an issue to work on, add a comment directly on the GitHub issue to say you are looking at it and let others know to avoid conflicting work. +You can also ask for help in a comment if you need it. + +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. + +Become a collection maintainer +============================== + +Once you have learned about the development process and have contributed code to a collection, we encourage you to become a maintainer of that collection. There are hundreds of modules in dozens of Ansible collections, and the vast majority of them are written and maintained entirely by members of the Ansible community. + + See :ref:`collection maintainer guidelines <maintainers>` to learn more about the responsibilities of being an Ansible collection maintainer. + +.. _community_working_groups: + +Join a working group +==================== + +Working groups are a way for Ansible community members to self-organize around particular topics of interest. We have working groups around various topics. To join or create a working group, please read the :ref:`Ansible Working Groups<working_group_list>`. + + +Teach Ansible to others +======================= + +We are working on a standardized `Ansible workshop <https://ansible.github.io/workshops/>`_ that can provide a good hands-on introduction to Ansible usage and concepts. + +Social media +============ + +If you like Ansible and just want to spread the good word, feel free to share on your social media platform of choice, and let us know by using ``@ansible`` or ``#ansible``. We'll be looking for you. diff --git a/docs/docsite/rst/community/index.rst b/docs/docsite/rst/community/index.rst new file mode 100644 index 0000000..b5ddb51 --- /dev/null +++ b/docs/docsite/rst/community/index.rst @@ -0,0 +1,24 @@ +.. _ansible_community_guide: + +*********************** +Ansible Community Guide +*********************** + +.. note:: + + **Making Open Source More Inclusive** + + Red Hat is committed to replacing problematic language in our code, documentation, and web properties. We are beginning with these four terms: master, slave, blacklist, and whitelist. We ask that you open an issue or pull request if you come upon a term that we have missed. For more details, see `our CTO Chris Wright's message <https://www.redhat.com/en/blog/making-open-source-more-inclusive-eradicating-problematic-language>`_. + +Welcome to the Ansible Community Guide! + +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. + + +.. _community_toc: + +.. toctree:: + :maxdepth: 2 + + getting_started + contributor_path diff --git a/docs/docsite/rst/community/maintainers.rst b/docs/docsite/rst/community/maintainers.rst new file mode 100644 index 0000000..bef1567 --- /dev/null +++ b/docs/docsite/rst/community/maintainers.rst @@ -0,0 +1,19 @@ +.. _maintainers: + +*************************************** +Guidelines for collection maintainers +*************************************** + +Thank you for being a community collection maintainer. This guide offers an overview of your responsibilities as a maintainer along with resources for additional information. The Ansible community hopes that you will find that maintaining a collection is as rewarding for you as having the collection content is for the wider community. + +.. toctree:: + :maxdepth: 1 + + maintainers_guidelines + maintainers_workflow + collection_contributors/collection_releasing + +In addition to the information here, module maintainers should be familiar with: + +* :ref:`General Ansible community development practices <ansible_community_guide>` +* Documentation on :ref:`module development <developing_modules>` diff --git a/docs/docsite/rst/community/maintainers_guidelines.rst b/docs/docsite/rst/community/maintainers_guidelines.rst new file mode 100644 index 0000000..43a0e69 --- /dev/null +++ b/docs/docsite/rst/community/maintainers_guidelines.rst @@ -0,0 +1,162 @@ +.. _maintainer_requirements: + +Maintainer responsibilities +=========================== + +.. contents:: + :depth: 1 + :local: + +An Ansible collection maintainer is a contributor trusted by the community who makes significant and regular contributions to the project and who has shown themselves as a specialist in the related area. +Collection maintainers have :ref:`extended permissions<collection_maintainers>` in the collection scope. + +Ansible collection maintainers provide feedback, responses, or actions on pull requests or issues to the collection(s) they maintain in a reasonably timely manner. They can also update the contributor guidelines for that collection, in collaboration with the Ansible community team and the other maintainers of that collection. + +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 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. +- :ref:`Release collections <Releasing>`. +- Ensure that collections adhere to the `Collection Requirements <https://github.com/ansible-collections/overview/blob/main/collection_requirements.rst>`_, +- Track changes announced in `News for collection contributors and maintainers <https://github.com/ansible-collections/news-for-maintainers>`_ and update a collection in accordance with these changes. +- Subscribe and submit news to the `Bullhorn newsletter <https://github.com/ansible/community/wiki/News#the-bullhorn>`_. +- :ref:`Build a healthy community <expanding_community>` to increase the number of active contributors and maintainers around collections. +- Revise these guidelines to improve the maintainer experience for yourself and others. + +Multiple maintainers can divide responsibilities among each other. + +How to become a 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. + +Communicating as a collection maintainer +----------------------------------------- + + Maintainers MUST subscribe to the `"Changes impacting collection contributors and maintainers" GitHub repo <https://github.com/ansible-collections/news-for-maintainers>`_ and the `Bullhorn newsletter <https://github.com/ansible/community/wiki/News#the-bullhorn>`_. If you have something important to announce through the newsletter (for example, recent releases), see the `Bullhorn's wiki page <https://github.com/ansible/community/wiki/News#the-bullhorn>`_ to learn how. + + +Collection contributors and maintainers should also communicate through: + +* :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. +* Ansiblefest and local meetups. + +See :ref:`communication` for more details on these communication channels. + +.. _wg_and_real_time_chat: + +Establishing working group communication +---------------------------------------------------------------- + +Working groups depend on efficient, real-time communication. +Project maintainers can use the following techniques to establish communication for working groups: + +* Find an existing :ref:`working_group_list` that is similar to your project and join the conversation. +* `Request <https://github.com/ansible/community/blob/main/WORKING-GROUPS.md>`_ a new working group for your project. +* `Create <https://hackmd.io/@ansible-community/community-matrix-faq#How-do-I-create-a-public-community-room>`_ a public chat for your working group or `ask <https://github.com/ansible/community/issues/new>`_ the community team. +* Provide working group details and links to chat rooms in the contributor section of your project ``README.md``. +* Encourage contributors to join the chats and add themselves to the working group. + +See the :ref:`Communication guide <communication_irc>` to learn more about real-time chat. + +Community Topics +---------------- + +The Community and the `Steering Committee <https://docs.ansible.com/ansible/devel/community/steering/community_steering_committee.html>`_ asynchronously discuss and vote on the `Community Topics <https://github.com/ansible-community/community-topics/issues>`_ which impact the whole project or its parts including collections and packaging. + +Share your opinion and vote on the topics to help the community make the best decisions. + +.. _expanding_community: + +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. + +Weekly community Matrix/IRC meetings +------------------------------------ + +The Community and the Steering Committee come together at weekly meetings in the ``#ansible-community`` `Libera.Chat IRC <https://docs.ansible.com/ansible/devel/community/communication.html#ansible-community-on-irc>`_ channel or in the bridged `#community:ansible.com <https://matrix.to/#/#community:ansible.com>`_ room on `Matrix <https://docs.ansible.com/ansible/devel/community/communication.html#ansible-community-on-matrix>`_ to discuss important project questions. Join us! Here is our `schedule <https://github.com/ansible/community/blob/main/meetings/README.md#schedule>`_. + +Expanding the collection community +=================================== + +.. note:: + + If you discover good ways to expand a community or make it more robust, edit this section with your ideas to share with other collection maintainers. + +Here are some ways you can expand the community around your collection: + + * Give :ref:`newcomers a positive first experience <collection_new_contributors>`. + * Invite contributors to join :ref:`real-time chats <wg_and_real_time_chat>` related to your project. + * Have :ref:`good documentation <maintainer_documentation>` with guidelines for new contributors. + * Make people feel welcome personally and individually. + * Use labels to show easy fixes and leave non-critical easy fixes to newcomers and offer to mentor them. + * Be responsive in issues, PRs and other communication. + * Conduct PR days regularly. + * Maintain a zero-tolerance policy towards behavior violating the :ref:`code_of_conduct`. + * Put information about how people can register code of conduct violations in your ``README`` and ``CONTRIBUTING`` files. + * Include quick ways contributors can help and other documentation in your ``README``. + * Add and keep updated the ``CONTRIBUTORS`` and ``MAINTAINERS`` files. + * Create a pinned issue to announce that the collection welcomes new maintainers and contributors. + * Look for new maintainers among active contributors. + * Announce that your collection welcomes new maintainers. + * Take part and congratulate new maintainers in Contributor Summits. + + +.. _collection_new_contributors: + +Encouraging new contributors +----------------------------- + +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 easy-fix issues, you could ask the issue reporter whether they want to fix the issue themselves providing the link to a quick start guide for creating PRs. + +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. + +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. + +Some other general guidelines to encourage contributors: + +* Welcome the author and thank them for the issue or pull request. +* 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 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. + +See the :ref:`review_checklist` for a list of items to check before you merge a PR. + +.. _maintainer_documentation: + +Maintaining good collection documentation +========================================== + +Maintainers look after the collection documentation to ensure it matches the :ref:`style_guide`. This includes keeping the following documents accurate and updated regularly: + +* Collection module and plugin documentation that adheres to the :ref:`Ansible documentation format <module_documenting>`. +* Collection user guides that follow the :ref:`Collection documentation format <collections_doc_dir>`. +* Repository files that includes at least a ``README`` and ``CONTRIBUTING`` file. + +A good ``README`` includes a description of the collection, a link to the :ref:`code_of_conduct`, and details on how to contribute or a pointer to the ``CONTRIBUTING`` file. If your collection is a part of Ansible (is shipped with Ansible package), highlight that fact at the top of the collection's ``README``. + + 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 quick start 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. diff --git a/docs/docsite/rst/community/maintainers_workflow.rst b/docs/docsite/rst/community/maintainers_workflow.rst new file mode 100644 index 0000000..6754d12 --- /dev/null +++ b/docs/docsite/rst/community/maintainers_workflow.rst @@ -0,0 +1,95 @@ +.. _maintainers_workflow: + + +Backporting and Ansible inclusion +================================== + +Each collection community can set its own rules and workflow for managing pull requests, bug reports, documentation issues, and feature requests, as well as adding and replacing maintainers. Maintainers review and merge pull requests following the: + +* :ref:`code_of_conduct` +* :ref:`maintainer_requirements` +* :ref:`Committer guidelines <committer_general_rules>` +* :ref:`PR review checklist<review_checklist>` + +There can be two kinds of maintainers: :ref:`collection_maintainers` and :ref:`module_maintainers`. + +.. _collection_maintainers: + +Collection maintainers +---------------------- + +Collection-scope maintainers are contributors who have the ``write`` or higher access level in a collection. They have commit rights and can merge pull requests, among other permissions. + +When a collection maintainer considers a contribution to a file significant enough +(for example, fixing a complex bug, adding a feature, providing regular reviews, and so on), +they can invite the author to become a module maintainer. + + +.. _module_maintainers: + +Module 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>`_ +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. + +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 +which changes a module they maintain, the collection bot merges the pull request automatically. + +For more information about the collection bot and its interface, +see to the `Collection bot overview <https://github.com/ansible-community/collection_bot/blob/main/ISSUE_HELP.md>`_. + + +Releasing a collection +---------------------- + +Collection maintainers are responsible for releasing new versions of a collection. Generally, releasing a collection consists of: + +#. Planning and announcement. +#. Generating a changelog. +#. Creating a release git tag and pushing it. +#. Automatically publishing the release tarball on `Ansible Galaxy <https://galaxy.ansible.com/>`_ through the `Zuul dashboard <https://dashboard.zuul.ansible.com/t/ansible/builds?pipeline=release>`_. +#. Final announcement. +#. Optionally, `file a request to include a new collection into the Ansible package <https://github.com/ansible-collections/ansible-inclusion>`_. + +See :ref:`releasing_collections` for details. + +.. _Backporting: + +Backporting +------------ + +Collection maintainers backport merged pull requests to stable branches +following the `semantic versioning <https://semver.org/>`_ and release policies of the collections. + +The manual backport process is similar to the :ref:`ansible-core backporting guidelines <backport_process>`. + +For convenience, backporting can be implemented automatically using GitHub bots (for example, with the `Patchback app <https://github.com/apps/patchback>`_) and labeling as it is done in `community.general <https://github.com/ansible-collections/community.general>`_ and `community.network <https://github.com/ansible-collections/community.network>`_. + + +.. _including_collection_ansible: + +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 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: + +- 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``. +- Look at active contributors in the collection to find new maintainers among them. Discuss the potential candidates with other maintainers or with the community team. +- If you failed to find a replacement, create a pinned issue in the collection, announcing that the collection needs new maintainers. +- Make the same announcement through the `Bullhorn newsletter <https://github.com/ansible/community/wiki/News#the-bullhorn>`_. +- Please be around to discuss potential candidates found by other maintainers or by the community team. + +Remember, this is a community, so you can come back at any time in the future. diff --git a/docs/docsite/rst/community/other_tools_and_programs.rst b/docs/docsite/rst/community/other_tools_and_programs.rst new file mode 100644 index 0000000..954d621 --- /dev/null +++ b/docs/docsite/rst/community/other_tools_and_programs.rst @@ -0,0 +1,124 @@ +.. _other_tools_and_programs: + +************************ +Other Tools and Programs +************************ + +.. contents:: + :local: + +The Ansible community uses a range of tools for working with the Ansible project. This is a list of some of the most popular of these tools. + +If you know of any other tools that should be added, this list can be updated by clicking "Edit on GitHub" on the top right of this page. + +*************** +Popular editors +*************** + +Atom +==== + +An open-source, free GUI text editor created and maintained by GitHub. You can keep track of git project +changes, commit from the GUI, and see what branch you are on. You can customize the themes for different colors and install syntax highlighting packages for different languages. You can install Atom on Linux, macOS and Windows. Useful Atom plugins include: + +* `language-yaml <https://atom.io/packages/language-yaml>`_ - YAML highlighting for Atom (built-in). +* `linter-js-yaml <https://atom.io/packages/linter-js-yaml>`_ - parses your YAML files in Atom through js-yaml. + + +Emacs +===== + +A free, open-source text editor and IDE that supports auto-indentation, syntax highlighting and built in terminal shell(among other things). + +* `yaml-mode <https://github.com/yoshiki/yaml-mode>`_ - YAML highlighting and syntax checking. +* `jinja2-mode <https://github.com/paradoxxxzero/jinja2-mode>`_ - Jinja2 highlighting and syntax checking. +* `magit-mode <https://github.com/magit/magit>`_ - Git porcelain within Emacs. +* `lsp-mode <https://emacs-lsp.github.io/lsp-mode/page/lsp-ansible/>`_ - Ansible syntax highlighting, auto-completion and diagnostics. + + +PyCharm +======= + +A full IDE (integrated development environment) for Python software development. It ships with everything you need to write python scripts and complete software, including support for YAML syntax highlighting. It's a little overkill for writing roles/playbooks, but it can be a very useful tool if you write modules and submit code for Ansible. Can be used to debug the Ansible engine. + + +Sublime +======= + +A closed-source, subscription GUI text editor. You can customize the GUI with themes and install packages for language highlighting and other refinements. You can install Sublime on Linux, macOS and Windows. Useful Sublime plugins include: + +* `GitGutter <https://packagecontrol.io/packages/GitGutter>`_ - shows information about files in a git repository. +* `SideBarEnhancements <https://packagecontrol.io/packages/SideBarEnhancements>`_ - provides enhancements to the operations on Sidebar of Files and Folders. +* `Sublime Linter <https://packagecontrol.io/packages/SublimeLinter>`_ - a code-linting framework for Sublime Text 3. +* `Pretty YAML <https://packagecontrol.io/packages/Pretty%20YAML>`_ - prettifies YAML for Sublime Text 2 and 3. +* `Yamllint <https://packagecontrol.io/packages/SublimeLinter-contrib-yamllint>`_ - a Sublime wrapper around yamllint. + + +Visual studio code +================== + +An open-source, free GUI text editor created and maintained by Microsoft. Useful Visual Studio Code plugins include: + +* `Ansible extension by Red Hat <https://marketplace.visualstudio.com/items?itemName=redhat.ansible>`_ - provides autocompletion, syntax highlighting, hover, diagnostics, goto support, and command to run ansible-playbook and ansible-navigator tool for both local and execution-environment setups. +* `YAML Support by Red Hat <https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml>`_ - provides YAML support through yaml-language-server with built-in Kubernetes and Kedge syntax support. + +vim +=== + +An open-source, free command-line text editor. Useful vim plugins include: + +* `Ansible vim <https://github.com/pearofducks/ansible-vim>`_ - vim syntax plugin for Ansible 2.x, it supports YAML playbooks, Jinja2 templates, and Ansible's hosts files. +* `Ansible vim and neovim plugin <https://www.npmjs.com/package/@yaegassy/coc-ansible>`_ - vim plugin (lsp client) for Ansible, it supports autocompletion, syntax highlighting, hover, diagnostics, and goto support. + +JetBrains +========= + +An open-source Community edition and closed-source Enterprise edition, integrated development environments based on IntelliJ's framework including IDEA, AppCode, CLion, GoLand, PhpStorm, PyCharm and others. Useful JetBrains platform plugins include: + +* `Ansible <https://plugins.jetbrains.com/plugin/14893-ansible>`_ - general Ansible plugin provides auto-completion, role name suggestion and other handy features for working with playbooks and roles. + +* `Ansible Vault Editor <https://plugins.jetbrains.com/plugin/14278-ansible-vault-editor>`_ - Ansible Vault Editor with auto encryption/decryption. + +***************** +Development tools +***************** + +Finding related issues and PRs +============================== + +There are various ways to find existing issues and pull requests (PRs) + +- `PR by File <https://ansible.sivel.net/pr/byfile.html>`_ - shows a current list of all open pull requests by individual file. An essential tool for Ansible module maintainers. +- `jctanner's Ansible Tools <https://github.com/jctanner/ansible-tools>`_ - miscellaneous collection of useful helper scripts for Ansible development. + +.. _validate-playbook-tools: + +****************************** +Tools for validating playbooks +****************************** + +- `Ansible Lint <https://docs.ansible.com/ansible-lint/index.html>`_ - a highly configurable linter for Ansible playbooks. +- `Ansible Review <https://github.com/willthames/ansible-review>`_ - an extension of Ansible Lint designed for code review. +- `Molecule <https://molecule.readthedocs.io/en/latest/>`_ - a testing framework for Ansible plays and roles. +- `yamllint <https://yamllint.readthedocs.io/en/stable/>`__ - a command-line utility to check syntax validity including key repetition and indentation issues. + + +*********** +Other tools +*********** + +- `Ansible cmdb <https://github.com/fboender/ansible-cmdb>`_ - takes the output of Ansible's fact gathering and converts it into a static HTML overview page containing system configuration information. +- `Ansible Inventory Grapher <https://github.com/willthames/ansible-inventory-grapher>`_ - visually displays inventory inheritance hierarchies and at what level a variable is defined in inventory. +- `Ansible Language Server <https://www.npmjs.com/package/@ansible/ansible-language-server>`_ - a server that implements `language server protocol <https://microsoft.github.io/language-server-protocol/>`_ for Ansible. +- `Ansible Playbook Grapher <https://github.com/haidaraM/ansible-playbook-grapher>`_ - a command line tool to create a graph representing your Ansible playbook tasks and roles. +- `Ansible Shell <https://github.com/dominis/ansible-shell>`_ - an interactive shell for Ansible with built-in tab completion for all the modules. +- `Ansible Silo <https://github.com/groupon/ansible-silo>`_ - a self-contained Ansible environment by Docker. +- `Ansigenome <https://github.com/nickjj/ansigenome>`_ - a command line tool designed to help you manage your Ansible roles. +- `ARA <https://github.com/ansible-community/ara>`_ - ARA Records Ansible playbooks and makes them easier to understand and troubleshoot with a reporting API, UI and CLI. +- `Awesome Ansible <https://github.com/jdauphant/awesome-ansible>`_ - a collaboratively curated list of awesome Ansible resources. +- `AWX <https://github.com/ansible/awx>`_ - provides a web-based user interface, REST API, and task engine built on top of Ansible. Red Hat Ansible Automation Platform includes code from AWX. +- `Mitogen for Ansible <https://mitogen.networkgenomics.com/ansible_detailed.html>`_ - uses the `Mitogen <https://github.com/dw/mitogen/>`_ library to execute Ansible playbooks in a more efficient way (decreases the execution time). +- `nanvault <https://github.com/marcobellaccini/nanvault>`_ - a standalone tool to encrypt and decrypt files in the Ansible Vault format, featuring UNIX-style composability. +- `OpsTools-ansible <https://github.com/centos-opstools/opstools-ansible>`_ - uses Ansible to configure an environment that provides the support of `OpsTools <https://wiki.centos.org/SpecialInterestGroup/OpsTools>`_, namely centralized logging and analysis, availability monitoring, and performance monitoring. +- `TD4A <https://github.com/cidrblock/td4a>`_ - a template designer for automation. TD4A is a visual design aid for building and testing jinja2 templates. It will combine data in yaml format with a jinja2 template and render the output. +- `PHP-Ansible <https://github.com/maschmann/php-ansible>`_ - an object oriented Ansible wrapper for PHP. diff --git a/docs/docsite/rst/community/release_managers.rst b/docs/docsite/rst/community/release_managers.rst new file mode 100644 index 0000000..97949a5 --- /dev/null +++ b/docs/docsite/rst/community/release_managers.rst @@ -0,0 +1,81 @@ +.. _release_managers: + +************************** +Release Manager Guidelines +************************** + +.. contents:: Topics + +The release manager's purpose is to ensure a smooth release. To achieve that goal, they need to +coordinate between: + +* Developers with commit privileges on the `Ansible GitHub repository <https://github.com/ansible/ansible/>`_ +* Contributors without commit privileges +* The community +* Ansible documentation team + +Pre-releases: what and why +========================== + +Pre-releases exist to draw testers. They give people who don't feel comfortable running from source +control a means to get an early version of the code to test and give us feedback. To ensure we get +good feedback about a release, we need to make sure all major changes in a release are put into +a pre-release. Testers must be given time to test those changes before the final release. Ideally we +want there to be sufficient time between pre-releases for people to install and test one version for +a span of time. Then they can spend more time using the new code than installing the latest +version. + +The right length of time for a tester is probably around two weeks. However, for our three-to-four month +development cycle to work, we compress this down to one week; any less runs the risk +of people spending more time installing the code instead of running it. However, if there's a time +crunch (with a release date that cannot slip), it is better to release with new changes than to hold +back those changes to give people time to test between. People cannot test what is not released, so +we have to get those tarballs out there even if people feel they have to install more frequently. + + +Beta releases +------------- + +In a beta release, we know there are still bugs. We will continue to accept fixes for these. +Although we review these fixes, sometimes they can be invasive or potentially destabilize other +areas of the code. + +During the beta, we will no longer accept feature submissions. + + +Release candidates +------------------ + +In a release candidate, we've fixed all known blockers. Any remaining bugfixes are +ones that we are willing to leave out of the release. At this point we need user testing to +determine if there are any other blocker bugs lurking. + +Blocker bugs generally are those that cause significant problems for users. Regressions are +more likely to be considered blockers because they will break present users' usage of Ansible. + +The Release Manager will cherry-pick fixes for new release blockers. The release manager will also +choose whether to accept bugfixes for isolated areas of the code or defer those to the next minor +release. By themselves, non-blocker bugs will not trigger a new release; they will only make it +into the next major release if blocker bugs require that a new release be made. + +The last RC should be as close to the final as possible. The following things may be changed: + + * Version numbers are changed automatically and will differ as the pre-release tags are removed from + the versions. + * Tests and :file:`docs/docsite/` can differ if really needed as they do not break runtime. + However, the release manager may still reject them as they have the potential to cause + breakage that will be visible during the release process. + +.. note:: We want to specifically emphasize that code (in :file:`bin/`, :file:`lib/ansible/`, and + :file:`setup.py`) must be the same unless there are extraordinary extenuating circumstances. If + there are extenuating circumstances, the Release Manager is responsible for notifying groups + which would want to test the code. + + +Ansible release process +======================= + +The release process is kept in a `separate document +<https://docs.google.com/document/d/10EWLkMesi9s_CK_GmbZlE_ZLhuQr6TBrdMLKo5dnMAI/edit#heading=h.ooo3izcel3cz>`_ +so that it can be easily updated during a release. If you need access to edit this, please ask one +of the current release managers to add you. diff --git a/docs/docsite/rst/community/reporting_bugs_and_features.rst b/docs/docsite/rst/community/reporting_bugs_and_features.rst new file mode 100644 index 0000000..a972603 --- /dev/null +++ b/docs/docsite/rst/community/reporting_bugs_and_features.rst @@ -0,0 +1,59 @@ + +.. _reporting_bugs_and_features: + +************************************** +Reporting bugs and requesting features +************************************** + +.. contents:: + :local: + +.. _reporting_bugs: + +Reporting a bug +=============== + +Security bugs +------------- + +Ansible practices responsible disclosure. To report security-related bugs, send an email to `security@ansible.com <mailto:security@ansible.com>`_ for an immediate response. Do not submit a ticket or post to any public groups. + +Bugs in ansible-core +-------------------- + +Before reporting a bug, search in GitHub for `already reported issues <https://github.com/ansible/ansible/issues>`_ and `open pull requests <https://github.com/ansible/ansible/pulls>`_ to see if someone has already addressed your issue. Unsure if you found a bug? Report the behavior on the :ref:`mailing list or community chat first <communication>`. + +Also, use the mailing list or chat to discuss whether the problem is in ``ansible-core`` or a collection, and for "how do I do this" type questions. + +You need a free GitHub account to `report bugs <https://github.com/ansible/ansible/issues>`_ that affect: + +- multiple plugins +- a plugin that remained in the ansible/ansible repo +- the overall functioning of Ansible + +How to write a good bug report +------------------------------ + +If you find a bug, open an issue using the `issue template <https://github.com/ansible/ansible/issues/new?assignees=&labels=&template=bug_report.yml>`_. + +Fill out the issue template as completely and as accurately as possible. Include: + +* your Ansible version +* the expected behavior and what you've tried, including the exact commands you were using or tasks you are running. +* the current behavior and why you think it is a bug +* the steps to reproduce the bug +* a minimal reproducible example and comments describing examples +* any relevant configurations and the components you used +* any relevant output plus ``ansible -vvvv`` (debugging) output +* add the output of ``ansible-test-env --show`` when filing bug reports involving ``ansible-test``. + +When sharing YAML in playbooks, ensure that you preserve formatting using `code blocks <https://help.github.com/articles/creating-and-highlighting-code-blocks/>`_. For multiple-file content, use gist.github.com, more durable than Pastebin content. + +.. _request_features: + +Requesting a feature +==================== + +Before you request a feature, check what is :ref:`planned for future Ansible Releases <roadmaps>`. Check `existing pull requests tagged with feature <https://github.com/ansible/ansible/issues?q=is%3Aissue+is%3Aopen+label%3Afeature>`_. + +To get your feature into Ansible, :ref:`submit a pull request <community_pull_requests>`, either against ansible-core or a collection. See also :ref:`ansible_collection_merge_requirements`. For ``ansible-core``, you can also open an issue in `ansible/ansible <https://github.com/ansible/ansible/issues>`_ or in a corresponding collection repository (To find the correct issue tracker, refer to :ref:`Bugs in collections<reporting_bugs_in_collections>` ). diff --git a/docs/docsite/rst/community/reporting_collections.rst b/docs/docsite/rst/community/reporting_collections.rst new file mode 100644 index 0000000..1d8c2e6 --- /dev/null +++ b/docs/docsite/rst/community/reporting_collections.rst @@ -0,0 +1,36 @@ +.. _reporting_bugs_in_collections: + +*********************************** +Requesting changes to a collection +*********************************** + +.. contents:: + :local: + +Reporting a bug +=============== + +Security bugs +------------- + +Ansible practices responsible disclosure - if this is a security-related bug, email `security@ansible.com <mailto:security@ansible.com>`_ instead of filing a ticket or posting to any public groups, and you will receive a prompt response. + + +Bugs in collections +------------------- + +Many bugs only affect a single module or plugin. If you find a bug that affects a module or plugin hosted in a collection, file the bug in the repository of the :ref:`collection <collections>`: + + #. Find the collection on `Galaxy <https://galaxy.ansible.com>`_. + #. Click on the Issue Tracker link for that collection. + #. Follow the contributor guidelines or instructions in the collection repo. + +If you are not sure whether a bug is in ansible-core or in a collection, you can report the behavior on the :ref:`mailing list or community chat channel first <communication>`. + +Requesting a feature +==================== + +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 the :ref:`ansible_collection_merge_requirements`. + +You can also submit a feature request by opening an issue in the collection repository. diff --git a/docs/docsite/rst/community/steering/community_steering_committee.rst b/docs/docsite/rst/community/steering/community_steering_committee.rst new file mode 100644 index 0000000..282d0ca --- /dev/null +++ b/docs/docsite/rst/community/steering/community_steering_committee.rst @@ -0,0 +1,165 @@ + +.. _steering_responsibilities: + +Steering Committee mission and responsibilities +=============================================== + +The Steering Committee mission is to provide continuity, guidance, and suggestions to the Ansible community to ensure the delivery and high quality of the Ansible package. In addition, the committee helps decide the technical direction of the Ansible project. It is responsible for approving new proposals and policies in the community, package, and community collections world, new community collection-inclusion requests, and other technical aspects regarding inclusion and packaging. +The Committee should reflect the scope and breadth of the Ansible community. + +Steering Committee responsibilities +------------------------------------ + +The Committee: + +* Designs policies and procedures for the community collections world. +* Votes on approval changes to established policies and procedures. +* Reviews community collections for compliance with the policies. +* Helps create and define roadmaps for our deliverables such as the ``ansible`` package, major community collections, and documentation. +* Reviews community collections submitted for inclusion in the Ansible package and decides whether to include them or not. +* Review other proposals of importance that need the Committee's attention and provide feedback. + +.. _steering_members: + +Current Steering Committee members +----------------------------------- + +The following table lists the current Steering Committee members. See :ref:`steering_past_members` for a list of past members. + + + +.. table:: Current Steering committee members + + +------------------+---------------+-------------+ + | Name | GitHub | Start year | + +==================+===============+=============+ + | Alexei Znamensky | russoz | 2022 | + +------------------+---------------+-------------+ + | Alicia Cozine | acozine | 2021 | + +------------------+---------------+-------------+ + | Andrew Klychkov | Andersson007 | 2021 | + +------------------+---------------+-------------+ + | Brad Thornton | cidrblock | 2021 | + +------------------+---------------+-------------+ + | Brian Scholer | briantist | 2022 | + +------------------+---------------+-------------+ + | Dylan Silva | thaumos | 2021 | + +------------------+---------------+-------------+ + | Felix Fontein | felixfontein | 2021 | + +------------------+---------------+-------------+ + | James Cassell | jamescassell | 2021 | + +------------------+---------------+-------------+ + | John Barker | gundalow | 2021 | + +------------------+---------------+-------------+ + | Mario Lenz | mariolenz | 2022 | + +------------------+---------------+-------------+ + | Markus Bergholz | markuman | 2022 | + +------------------+---------------+-------------+ + | Maxwell G | gotmax23 | 2022 | + +------------------+---------------+-------------+ + | Sorin Sbarnea | ssbarnea | 2021 | + +------------------+---------------+-------------+ + + +John Barker (`gundalow <https://github.com/gundalow>`_) has been elected by the Committee as its :ref:`chairperson`. + +Committee members are selected based on their active contribution to the Ansible Project and its community. See :ref:`community_steering_guidelines` to learn details. + +Creating new policy proposals & inclusion requests +---------------------------------------------------- + +The Committee uses the `community-topics repository <https://github.com/ansible-community/community-topics/issues>`_ to asynchronously discuss with the Community and vote on Community topics in corresponding issues. + +You can create a new issue in the `community-topics repository <https://github.com/ansible-community/community-topics/issues>`_ as a discussion topic if you want to discuss an idea that impacts any of the following: + + * Ansible Community + * Community collection best practices and requirements + * Community collection inclusion policy + * The Community governance + * Other proposals of importance that need the Committee's or overall Ansible community attention + + +To request changes to the inclusion policy and collection requirements: + +#. Submit a new pull request to the `ansible-collections/overview <https://github.com/ansible-collections/overview>`_ repository. + +#. Create a corresponding issue containing the rationale behind these changes in the `community-topics repository <https://github.com/ansible-community/community-topics/issues>`_ repository. + +To submit new collections for inclusion into the Ansible package: + +* Submit the new collection inclusion requests through a new discussion in the `ansible-inclusion <https://github.com/ansible-collections/ansible-inclusion/discussions/new>`_ repository. + +Depending on a topic you want to discuss with the Community and the Committee, as you prepare your proposal, please consider the requirements established by: + +* :ref:`code_of_conduct`. +* `Ansible Collection Requirements <https://github.com/ansible-collections/overview/blob/main/collection_requirements.rst>`_. +* `Ansible Collection Inclusion Checklist <https://github.com/ansible-collections/overview/blob/main/collection_checklist.md>`_. + +Community topics workflow +^^^^^^^^^^^^^^^^^^^^^^^^^ + +The Committee uses the `Community-topics workflow <https://github.com/ansible-community/community-topics/blob/main/community_topics_workflow.md>`_ to asynchronously discuss and vote on the `community-topics <https://github.com/ansible-community/community-topics/issues>`_. + +The quorum, the minimum number of Committee members who must vote on a topic in order for a decision to be officially made, is half of the whole number of the Committee members. If the quorum number contains a fractional part, it is rounded up to the next whole number. For example, if there are thirteen members currently in the committee, the quorum will be seven. + +Votes must always have "no change" as an option. + +In case of equal numbers of votes for and against a topic, the chairperson's vote will break the tie. For example, if there are six votes for and six votes against a topic, and the chairperson's vote is among those six which are for the topic, the final decision will be positive. If the chairperson has not voted yet, other members ask them to vote. + +For votes with more than two options, one choice must have at least half of the votes. If two choices happen to both have half of the votes, the chairperson's vote will break the tie. If no choice has at least half of the votes, the vote choices have to be adjusted so that a majority can be found for a choice in a new vote. + +Community topics triage +^^^^^^^^^^^^^^^^^^^^^^^ + +The Committee conducts a triage of `community topics <https://github.com/ansible-community/community-topics/issues>`_ periodically (every three to six months). + +The triage goals are: + +* Sparking interest for forgotten topics. +* Identifying and closing irrelevant topics, for example, when the reason of the topic does not exist anymore or the topic is out of the Committee responsibilities scope. +* Identifying and closing topics that the Community are not interested in discussing. As indicators, it can be absence of comments or no activity in comments, at least, for the last six months. +* Identifying and closing topics that were solved and implemented but not closed (in this case, such a topic can be closed on the spot with a comment that it has been implemented). +* Identifying topics that have been in pending state for a long time, for example, when it is waiting for actions from someone for several months or when the topics were solved but not implemented. + +A person starting the triage: + +#. Identifies the topics mentioned above. +#. Creates a special triage topic containing an enumerated list of the topics-candidates for closing. +#. Establishes a vote date considering a number of topics, their complexity and comment-history size giving the Community sufficient time to go through and discuss them. +#. The Community and the Committee vote on each topic-candidate listed in the triage topic whether to close it or keep it open. + +Collection inclusion requests workflow +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When reviewing community collection `inclusion requests <https://github.com/ansible-collections/ansible-inclusion/discussions>`_, the Committee members check if a collection adheres to the `Community collection requirements <https://github.com/ansible-collections/overview/blob/main/collection_requirements.rst>`_. + +#. A Committee member who conducts the inclusion review copies the `Ansible community collection checklist <https://github.com/ansible-collections/overview/blob/main/collection_checklist.md>`_ into a corresponding `discussion <https://github.com/ansible-collections/ansible-inclusion/discussions>`_. + +#. In the course of the review, the Committee member marks items as completed or leaves a comment saying whether the reviewer expects an issue to be addressed or whether it is optional (for example, it could be **MUST FIX:** <what> or **SHOULD FIX:** <what> under an item). + +#. For a collection to be included in the Ansible community package, the collection: + + * MUST be reviewed and approved by at least two persons, where at least one person is a Steering Committee member. + * For a Non-Steering Committee review to be counted for inclusion, it MUST be checked and approved by *another* Steering Committee member. + * Reviewers must not be involved significantly in development of the collection. They must declare any potential conflict of interest (for example, being friends/relatives/coworkers of the maintainers/authors, being users of the collection, or having contributed to that collection recently or in the past). + +#. After the collection gets two or more Committee member approvals, a Committee member creates a `community topic <https://github.com/ansible-community/community-topics/issues>`_ linked to the corresponding inclusion request. The issue's description says that the collection has been approved by two or more Committee members and establishes a date (a week by default) when the inclusion decision will be considered made. This time period can be used to raise concerns. + +#. If no objections are raised up to the established date, the inclusion request is considered successfully resolved. In this case, a Committee member: + + #. Declares the decision in the topic and in the inclusion request. + #. Moves the request to the ``Resolved reviews`` category. + #. Adds the collection to the ``ansible.in`` file in a corresponding directory of the `ansible-build-data repository <https://github.com/ansible-community/ansible-build-data>`_. + #. Announces the inclusion through the `Bullhorn newsletter <https://github.com/ansible/community/wiki/News#the-bullhorn>`_. + #. Closes the topic. + +Community Working Group meetings +--------------------------------- + +See the Community Working Group meeting `schedule <https://github.com/ansible/community/blob/main/meetings/README.md#wednesdays>`_. Meeting summaries are posted in the `Community Working Group Meeting Agenda <https://github.com/ansible/community/issues?q=is%3Aopen+label%3Ameeting_agenda+label%3Acommunity+>`_ issue. + +.. note:: + + Participation in the Community Working Group meetings is optional for Committee members. Decisions on community topics are made asynchronously in the `community-topics <https://github.com/ansible-community/community-topics/issues>`_ repository. + +The meeting minutes can be found at the `fedora meetbot site <https://meetbot.fedoraproject.org/sresults/?group_id=ansible-community&type=channel>`_ and the same is posted to `Ansible Devel Mailing List <https://groups.google.com/g/ansible-devel>`_ after every meeting. diff --git a/docs/docsite/rst/community/steering/steering_committee_membership.rst b/docs/docsite/rst/community/steering/steering_committee_membership.rst new file mode 100644 index 0000000..1b636f1 --- /dev/null +++ b/docs/docsite/rst/community/steering/steering_committee_membership.rst @@ -0,0 +1,139 @@ +.. _community_steering_guidelines: + +Steering Committee membership guidelines +========================================== + +This document describes the expectations and policies related to membership in the :ref:`Ansible Community Steering Committee <steering_responsibilities>` (hereinafter the Committee). + +.. contents:: Topics: + +.. _steering_expectations: + +Expectations of a Steering Committee member +------------------------------------------- + + +As a Committee member, you agree to: + +#. Abide by the :ref:`code_of_conduct` in all your interactions with the Community. +#. Be a Community ambassador by representing its needs within the Committee and throughout the decision making process. +#. Asynchronously participate in discussions and voting on the `Community Topics <https://github.com/ansible-community/community-topics/issues>`_. +#. Review other proposals of importance that need the Committee's attention and provide feedback. +#. Act for the sake of the Community by not promoting corporate or individual agenda during the decision making process. +#. Engage with the Community in a professional and positive manner, encourage community members to express their opinion. + +.. _Joining the committee: + +Joining the Steering Committee +------------------------------- + +Eligibility +^^^^^^^^^^^ + +A person is eligible to become a Committee member if they have: + +#. A wide knowledge of Ansible and/or its related projects. +#. Active contributions to Ansible and/or related projects in any form described in the :ref:`collections_contributions`. +#. A consent to follow the :ref:`steering_expectations`. + +Process +^^^^^^^^ + +The process to join the Steering Committee consists of the following steps: + +#. Any community member may nominate someone or themselves for Committee membership by contacting one of the :ref:`current Committee members <steering_members>`) or by sending an email to ``ansible-community@redhat.com``. +#. A Committee member who receives the nomination must inform the Committee about it by forwarding the full message. +#. The vote is conducted by email. Nominees must receive a majority of votes from the present Committee members to be added to the Committee. +#. Provided that the vote result is positive, it is announced via the `Bullhorn <https://github.com/ansible/community/wiki/News#the-bullhorn>`_ newsletter and the new member is added to the :ref:`Committee member list <steering_members>`. + +Leaving the Steering Committee +------------------------------- + +Steering Committee members can resign voluntarily or be removed by the +rest of the Steering Committee under certain circumstances. See the details +below. + +.. _Voluntarily leaving process: + +Voluntarily leaving the Steering Committee +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A Committee member can voluntarily leave the Committee. +In this case, they notify the other members, create an issue in the `Community Topics <https://github.com/ansible-community/community-topics/issues>`_ repository announcing the resignation, and after that they are no longer considered Committee members. + +Committee members who resign and later change their mind can +rejoin the Committee by following the :ref:`Process for joining the Steering Committee<Joining the committee>`. + +Involuntarily leaving the Steering Committee +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A Committee member will be removed from the Committee if they: + +#. Do not participate in asynchronous discussions and voting on the `Community Topics <https://github.com/ansible-community/community-topics/issues>`_ for more than 3 months in a row. +#. Participate unreasonably irregularly (for example, once a month for several months). Unreasonably is defined by other Committee members considering circumstances in each particular case. +#. Violate the :ref:`code_of_conduct`. + +.. _Absence or irregular participation removal process: + +Absence or irregular participation in discussing topics and votes +.................................................................. + +In case of absence or irregular participation, the involuntarily removal process consists of the following steps: + +#. Another Committee member (hereinafter the initiator) contacts the person by email asking if they are still interested in fulfilling their Committee member's duties. +#. If they respond that they are not interested, the initiator asks the person to step down on their own following the :ref:`Voluntarily leaving process<Voluntarily leaving process>`. +#. If there has been no response or stepping down issue created by the person within a reasonable time, the initiator notifies other Committee members about the situation. +#. In case of agreement among the Committee about the need for removal, the initiator provides a draft of a corresponding topic's description to the Committee via email for discussion and approval. + + * The topic's title is ``Steering Committee member audit.``. It must not contain the person's name or other identifying information. + + * The description must not contain or imply any forms of condemnation. + + * It must mention that the person has been inactive for an unknown reason for the last N months and that, in accordance with the Steering Committee policies, their place should be freed for another person who can continue their great job. + + * The description must mention person's achievements and thanks for their time and effort they spent serving for the Community, Committee, and the Project, and a hope that one day they will come back. + +#. The initiator creates the topic in the `Community Topics <https://github.com/ansible-community/community-topics/issues>`_ repository containing the description and the title from the draft. +#. The Committee members vote on the topic. + +Ansible Community Code of Conduct violations +............................................. + +In case of the `Ansible Community Code of Conduct <https://docs.ansible.com/ansible/latest/community/code_of_conduct.html>`_ violations, the process is the same as above except steps 1-2. Instead: + +#. The initiator reports the case to the Committee via email. + +#. The Committee discusses the case internally, evaluates its severity, and possible solutions. + +#. If the Committee concludes that the violation is not severe, it develops a proposal to the person on how the situation can be corrected and further interactions with the Community improved. + +#. A Committee representative reaches out to the person with the proposal. + +#. The removal process starts if: + + * The Committee decided that the severity of the violation excludes a possibility of further membership. + + * The person does not respond to the proposal. + + * The person explicitly rejects the proposal. + +In case of starting the removal process, the topic's description in the reason's part changes correspondingly. + +.. _chairperson: + +Chairperson +------------ + +The chairperson election will happen once a year around the time of +Ansible Fest. If the current chairperson has to step down early, the election happens immediately. + +The process of the election consist of the following steps: + +#. Members interested in being the chairperson will inform a + person responsible for arranging the election about that. +#. Conduct anonymous voting somewhere. +#. Internally and publicly announce the elected candidate. + +The chairperson has the following powers unlike regular members: + +* The chairperson's vote breaks ties to resolve deadlocks when equal numbers of steering committee members vote for and against a `community topic <https://github.com/ansible-community/community-topics/issues>`_. diff --git a/docs/docsite/rst/community/steering/steering_committee_past_members.rst b/docs/docsite/rst/community/steering/steering_committee_past_members.rst new file mode 100644 index 0000000..2126173 --- /dev/null +++ b/docs/docsite/rst/community/steering/steering_committee_past_members.rst @@ -0,0 +1,31 @@ +.. _steering_past_members: + +Steering Committee past members +================================ + +The Ansible Community is very grateful to these amazing **nonreplaceable** +people for their great service to the Community and the project! + + +.. table:: Steering Committee past members + + +------------------+-----------+-------------------+ + | Name | GitHub | Years of service | + +==================+===========+===================+ + | Jill Rouleau | jillr | 2021-2022 | + +------------------+-----------+-------------------+ + | Tadej BorovÅ¡ak | tadeboro | 2021-2022 | + +------------------+-----------+-------------------+ + | Toshio Kuratomi | abadger | 2021 | + +------------------+-----------+-------------------+ + + +We'd also like to thank our past chairpersons for their contributions to Ansible. + +.. table:: Steering Committee past chairpersons + + +------------------+-----------+-------------------+ + | Name | GitHub | Years of service | + +==================+===========+===================+ + | Tadej BorovÅ¡ak | tadeboro | 2021-2022 | + +------------------+-----------+-------------------+ diff --git a/docs/docsite/rst/community/steering/steering_index.rst b/docs/docsite/rst/community/steering/steering_index.rst new file mode 100644 index 0000000..78d435a --- /dev/null +++ b/docs/docsite/rst/community/steering/steering_index.rst @@ -0,0 +1,14 @@ +.. _community_steering_committee: + +************************************ +Ansible Community Steering Committee +************************************ + +This section focuses on the guidelines and membership of the Ansible Community Steering Committee. + +.. toctree:: + :maxdepth: 1 + + community_steering_committee + steering_committee_membership + steering_committee_past_members |