From a6d7eb8710ce8336555092b2b6adfbe49dc28301 Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Fri, 13 May 2022 17:59:00 -0400 Subject: [PATCH] [docs][backport] 5 06 docs backportapalooza (#77749) * Docsite: move a stepped down steering committee member to past members (#77715) (cherry picked from commit a1ddb83fc1936ced9e79c5b4e2fc64abe0ccc310) * add collection pr review checklist (#77661) Co-authored-by: Emmanuel Ugwu <32464178+ugwutotheeshoes@users.noreply.github.com> Co-authored-by: Andrew Klychkov (cherry picked from commit ef2fe6823c43bfb629a1c68c7e6c8124d9149297) * clarify latest release (#77577) * clarify latest release * fix tables (cherry picked from commit f633b62cbc995befe47d98c735d57baacb9cda2e) * typo in doc (#77672) (cherry picked from commit c71faec59578fff019b1cd80e8ad3db24eea1aae) * Docs: `ansible-test sanity` example with a folder ##### SUMMARY The docs mentions explicitly that you can run the tests against certain files which might not relay that it works on folders too! Let's make this clear :) ##### ISSUE TYPE - Docs Pull Request +label: docsite_pr (cherry picked from commit 52bd59c481008688134b03855c3110e84dd382b9) * docs: update porting guide for ansible 6.0.0a2 (#77736) (cherry picked from commit 0cfc29157352550dd87a74cb3819498f694c66d1) * simplify developing modules (#77647) (cherry picked from commit 255745b3e6460558d7fae4492e14b570c0569631) * Mention admin requirement for runas become (#77722) (cherry picked from commit dd094a4413ff7f8af018f105c296005675215236) * core branch descriptions (#76152) (cherry picked from commit d352f2ec21dd2f08cf2653a22293c59419ecb479) * Fix ansible-test import analysis warning. Fix overlooked in https://github.com/ansible/ansible/pull/68372/ (cherry picked from commit 77732ed50db3b8e27d463663f347088334094bed) * Revert "Fix ansible-test import analysis warning." This reverts commit 676f1056cb47ef78aeeaf87d220d0667d9589fcc. Co-authored-by: Andrew Klychkov Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> Co-authored-by: Kristian Heljas <11139388+kristianheljas@users.noreply.github.com> Co-authored-by: David Moreau Simard Co-authored-by: Brian Coca Co-authored-by: Jordan Borean Co-authored-by: Matt Davis <6775756+nitzmahone@users.noreply.github.com> Co-authored-by: Matt Clay --- .../collection_reviewing.rst | 74 +++++++ .../community/contributions_collections.rst | 1 + .../rst/community/development_process.rst | 5 +- .../rst/community/maintainers_guidelines.rst | 18 +- .../steering/community_steering_committee.rst | 2 - .../steering_committee_past_members.rst | 4 +- .../rst/dev_guide/core_branches_and_tags.rst | 58 +++++ .../docsite/rst/dev_guide/developing_core.rst | 1 + .../developing_modules_documenting.rst | 5 +- .../dev_guide/developing_modules_general.rst | 135 ++++-------- docs/docsite/rst/dev_guide/testing_sanity.rst | 5 +- .../rst/porting_guides/porting_guide_6.rst | 200 ++++++++++++++++-- docs/docsite/rst/user_guide/become.rst | 21 +- docs/docsite/sphinx_conf/ansible_conf.py | 1 + docs/docsite/sphinx_conf/core_conf.py | 1 + 15 files changed, 408 insertions(+), 123 deletions(-) create mode 100644 docs/docsite/rst/community/collection_contributors/collection_reviewing.rst create mode 100644 docs/docsite/rst/dev_guide/core_branches_and_tags.rst 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 00000000000..d4a410af38f --- /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 made a mistake in the code they put in the Steps to reproduce issue's section? We often see user errors reported as bugs. +* Did the user assume an unexpected behavior? Ensure that the related documentation is clear. If not, the issue is useful to help us improve documentation. +* Is there a minimal reproducer? If not, ask the reporter to reduce the complexity to help pinpoint the issue. +* Is the issue a consequence of wrong-configured environment? +* If it seems to be real bug, does the behaviour still exist in the most recent release or the development branch? +* Reproduce the bug, or if you do not have a suitable infrastructure, ask other contributors to reproduce the bug. + + +Reviewing suggested changes +--------------------------- + +When reviewing PRs, verify the suggested changes first. Do not: + +* Unnecessarily break backwards 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 `. + + +Other standards to check for in a PR include: + +* A pull request MUST NOT contain a mix of bugfixes and new features that are not tightly related. If yes, ask the author to split the pull request into separate PRs. +* If the pull request is not a documentation fix, it must include a :ref:`changelog fragment `. 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 `_. + * 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 `_. +* The changes follow the :ref:`Ansible documentation standards ` and the :ref:`style_guide`. +* The changes follow the :ref:`Development conventions `. +* If a new plugin is added, it is one of the `allowed plugin types `_. +* Documentation, examples, and return sections use FQCNs for the ``M(..)`` :ref:`format macros ` when referring to modules. +* Modules and plugins from ansible-core use ``ansible.builtin.`` as an FQCN prefix when mentioned. +* When a new option, module, plugin, or return value is added, the corresponding documentation or return sections use ``version_added:`` containing the *collection* version which they will be first released in. + + * 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 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/contributions_collections.rst b/docs/docsite/rst/community/contributions_collections.rst index 4e0d7ba9347..557293fe7ab 100644 --- a/docs/docsite/rst/community/contributions_collections.rst +++ b/docs/docsite/rst/community/contributions_collections.rst @@ -11,6 +11,7 @@ Ansible Collections Contributor Guide reporting_collections create_pr_quick_start collection_contributors/test_index + collection_contributors/collection_reviewing maintainers contributing_maintained_collections steering/steering_index diff --git a/docs/docsite/rst/community/development_process.rst b/docs/docsite/rst/community/development_process.rst index 9ed2e3b7512..1e24a4cfda5 100644 --- a/docs/docsite/rst/community/development_process.rst +++ b/docs/docsite/rst/community/development_process.rst @@ -20,11 +20,13 @@ If you want to follow the conversation about what features will be added to ``an * the :ref:`roadmaps` * the :ref:`Ansible Release Schedule ` +* the :ref:`ansible-core project branches and tags ` * various GitHub `projects `_ - for example: * the `2.12 release project `_ * the `core documentation project `_ + .. _community_pull_requests: @@ -34,7 +36,7 @@ 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 `_ 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 +* Contributor opens a PR (always against the ``devel`` branch) * Ansibot reviews the PR * Ansibot assigns labels * Ansibot pings maintainers @@ -43,6 +45,7 @@ Here's an overview of the PR lifecycle: * Contributor addresses any feedback from reviewers * Developers, maintainers, community re-review * PR merged or closed +* PR `backported `_ to one or more ``stable-X.Y`` branches (optional, bugfixes only) Automated PR review: ansibullbot -------------------------------- diff --git a/docs/docsite/rst/community/maintainers_guidelines.rst b/docs/docsite/rst/community/maintainers_guidelines.rst index 7a51de24f90..47b82a25d89 100644 --- a/docs/docsite/rst/community/maintainers_guidelines.rst +++ b/docs/docsite/rst/community/maintainers_guidelines.rst @@ -3,6 +3,10 @@ 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` in the collection scope. @@ -28,14 +32,14 @@ Multiple maintainers can divide responsibilities among each other. How to become a maintainer -------------------------- -A person who is interested in becoming a maintainer and satisfies the :ref:`requirements` may either self-nominate or be nominated by another maintainer. +A person interested in becoming a maintainer and satisfies the :ref:`requirements` may either self-nominate or be nominated by another maintainer. -To nominate a candidate, please 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 `_ repository. +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 `_ repository. Communicating as a collection maintainer ----------------------------------------- - Maintainers must subscribe to the `"Changes impacting collection contributors and maintainers" GitHub repo `_ and the `Bullhorn newsletter `_. If you have something important to announce through the newsletter (for example, recent releases ), see the `Bullhorn's wiki page `_ to learn how. + Maintainers MUST subscribe to the `"Changes impacting collection contributors and maintainers" GitHub repo `_ and the `Bullhorn newsletter `_. If you have something important to announce through the newsletter (for example, recent releases), see the `Bullhorn's wiki page `_ to learn how. Collection contributors and maintainers should also communicate through: @@ -61,7 +65,7 @@ Contributor Summits ------------------- -The quarterly Ansible Contributor Summit is a global event that provides our contributors a great opportunity to meet each other, communicate, share ideas, and see that there are other real persons behind the messages on Matrix/Libera.Chat IRC or GitHub. In other words, it gives a sense of community. Watch the `Bullhorn newsletter `_ for information when the next contributor summit, invite contributors you know, and take part in the event together. +The quarterly Ansible Contributor Summit is a global event that provides our contributors a great opportunity to meet each other, communicate, share ideas, and see that there are other real people behind the messages on Matrix or Libera Chat IRC or GitHub. This gives a sense of community. Watch the `Bullhorn newsletter `_ for information when the next contributor summit, invite contributors you know, and take part in the event together. Weekly community Matrix/IRC meetings ------------------------------------ @@ -98,7 +102,7 @@ Here are some ways you can expand the community around your collection: 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 would like to contribute. +Easy fix items are the best way to attract and mentor new contributors. You should triage incoming issues to mark them with labels such as ``easyfix``, ``waiting_on_contributor``, and ``docs``. where appropriate. Do not fix these trivial non-critical bugs yourself. Instead, mentor a person who wants to contribute. For some easy fix issues, you could ask the issue reporter whether they want to fix the issue themselves providing the link to a quickstart guide for creating PRs. @@ -119,6 +123,8 @@ Some other general guidelines to encourage contributors: * 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 @@ -126,7 +132,7 @@ 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/plugin documentation that adheres to the :ref:`Ansible documentation format `. +* Collection module and plugin documentation that adheres to the :ref:`Ansible documentation format `. * Collection user guides that follow the :ref:`Collection documentation format `. * Repository files that includes at least a ``README`` and ``CONTRIBUTING`` file. diff --git a/docs/docsite/rst/community/steering/community_steering_committee.rst b/docs/docsite/rst/community/steering/community_steering_committee.rst index f21ad24e6c5..8e9bd0200f5 100644 --- a/docs/docsite/rst/community/steering/community_steering_committee.rst +++ b/docs/docsite/rst/community/steering/community_steering_committee.rst @@ -51,8 +51,6 @@ The following table lists the current Steering Committee members. See :ref:`stee +------------------+---------------+-------------+ | James Cassell | jamescassell | 2021 | +------------------+---------------+-------------+ - | Jill Rouleau | jillr | 2021 | - +------------------+---------------+-------------+ | John Barker | gundalow | 2021 | +------------------+---------------+-------------+ | Mario Lenz | mariolenz | 2022 | diff --git a/docs/docsite/rst/community/steering/steering_committee_past_members.rst b/docs/docsite/rst/community/steering/steering_committee_past_members.rst index 3bdd89089c2..212617372a6 100644 --- a/docs/docsite/rst/community/steering/steering_committee_past_members.rst +++ b/docs/docsite/rst/community/steering/steering_committee_past_members.rst @@ -12,10 +12,12 @@ people for their great service to the Community and the project! +------------------+-----------+-------------------+ | Name | GitHub | Years of service | +==================+===========+===================+ - | Toshio Kuratomi | abadger | 2021 | + | 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. diff --git a/docs/docsite/rst/dev_guide/core_branches_and_tags.rst b/docs/docsite/rst/dev_guide/core_branches_and_tags.rst new file mode 100644 index 00000000000..aaef4aa5695 --- /dev/null +++ b/docs/docsite/rst/dev_guide/core_branches_and_tags.rst @@ -0,0 +1,58 @@ +.. _core_branches_and_tags: + +****************************************** +``ansible-core`` project branches and tags +****************************************** + +``devel`` branch +================ + +All new development on the next version of ``ansible-core`` occurs exclusively in the ``devel`` branch, +and all bugfixes to prior releases must first be merged to devel before being backported to one or more stable branches +for inclusion in servicing releases. Around the Beta 1 milestone, a new ``stable-X.Y`` branch is cut from ``devel``, +which is then updated to host development of the ``X.Y+1`` release. External automated testing of Ansible content from +``devel`` is not generally recommended. + +``stable-X.Y`` branches +======================= + +All ``ansible-core`` ``X.Y.Z`` releases are created from a corresponding ``stable-X.Y`` branch. A +release's stable branch is typically cut from ``devel`` around ``X.Y.0 beta 1`` (when the release is feature complete). +All further bugfixes (no enhancements!) must be made against ``devel`` and backported to applicable stable branches. + +``vX.Y.Z`` tags +=============== + +Each ``ansible-core vX.Y.Z`` release is tagged from the release commit in the corresponding ``stable-X.Y`` branch, +allowing access to the exact source used to create the release. As of ``ansible-core`` 2.13, the auto-generated GitHub +tarball of the tag contents is considered the official canonical release artifact. + + +.. _milestone_branch: + +``milestone`` branch +==================== + +A ``milestone`` branch is a slow-moving stream of the ``devel`` branch, intended for external testing of ``ansible-core`` +features under active development. As described in the :ref:`ansible_core_roadmaps` for a given release, development is +typically split into three phases of decreasing duration, with larger and more invasive changes targeted to be merged to +``devel`` in earlier phases. The ``milestone`` branch is updated to the contents of ``devel`` at the end of each +development phase. This allows testing of semi-stable unreleased features on a predictable schedule without the exposure +to the potential instability of the daily commit "fire hose" from ``devel``. When a release reaches the Beta 1 milestone, +the ``milestone`` branch will be updated to the first ``devel`` commit after the version number has been increased. +Further testing of the same release should be done from the new ``stable-X.Y`` branch that was created. If a severe issue +that significantly affects community testing or stability is discovered in the ``milestone`` branch, the branch contents +may require unscheduled adjustment, but not in a way that prevents fast-forward updates (for example, ``milestone``-only +commits will not be created or cherry-picked from ``devel``). + +The following example is for illustrative purposes only. See the :ref:`ansible_core_roadmaps` for accurate dates. For example, the ``milestone`` branch in 2.13 ``ansible-core`` roadmap updated as follows: + +* 27-Sep-2021: 2.13 Development Phase 1 begins; ``milestone`` contents are updated to 2.12.0b1 with version number set to + ``2.13.0.dev0``. Automated content testing that includes version-specific ignore files (e.g., ``ignore-2.12.txt``) + should copy them for the current version (e.g., ``ignore-2.13.txt``) before this point to ensure that automated sanity + testing against the ``milestone`` branch will continue to pass. +* 13-Dec-2021: 2.13 Development Phase 2 begins; ``milestone`` contents are updated to the final commit from Development Phase 1 +* 14-Feb-2022: 2.13 Development Phase 3 begins; ``milestone`` contents are updated to the final commit from Development Phase 2 +* 11-Apr-2022: ``stable-2.13`` branch created with results from Development Phase 3 and freeze. ``2.13.0b1`` is released from + ``stable-2.13``. Automated content testing should continue 2.13 series testing against the new branch. The ``devel`` + version number is updated to ``2.14.0.dev0``, and ``milestone`` is updated to that point. diff --git a/docs/docsite/rst/dev_guide/developing_core.rst b/docs/docsite/rst/dev_guide/developing_core.rst index eeee30fc73f..a6c8bfe4904 100644 --- a/docs/docsite/rst/dev_guide/developing_core.rst +++ b/docs/docsite/rst/dev_guide/developing_core.rst @@ -7,6 +7,7 @@ Although ``ansible-core`` (the code hosted in the `ansible/ansible repository `` html tag) in the documentation. +* ``B()`` currently has no standardized usage. It is displayed in boldface in the documentation. +* ``HORIZONTALLINE`` is used sparingly as a separator in long descriptions. It becomes a horizontal rule (the ``
`` html tag) in the documentation. .. note:: diff --git a/docs/docsite/rst/dev_guide/developing_modules_general.rst b/docs/docsite/rst/dev_guide/developing_modules_general.rst index 7572d6d8d9d..3f1f27fd061 100644 --- a/docs/docsite/rst/dev_guide/developing_modules_general.rst +++ b/docs/docsite/rst/dev_guide/developing_modules_general.rst @@ -1,14 +1,16 @@ .. _developing_modules_general: .. _module_dev_tutorial_sample: -************************** -Developing Ansible modules -************************** +****************** +Developing modules +****************** A module is a reusable, standalone script that Ansible runs on your behalf, either locally or remotely. Modules interact with your local machine, an API, or a remote system to perform specific tasks like changing a database password or spinning up a cloud instance. Each module can be used by the Ansible API, or by the :command:`ansible` or :command:`ansible-playbook` programs. A module provides a defined interface, accepts arguments, and returns information to Ansible by printing a JSON string to stdout before exiting. If you need functionality that is not available in any of the thousands of Ansible modules found in collections, you can easily write your own custom module. When you write a module for local use, you can choose any programming language and follow your own rules. Use this topic to learn how to create an Ansible module in Python. After you create a module, you must add it locally to the appropriate directory so that Ansible can find and execute it. For details about adding a module locally, see :ref:`developing_locally`. +If you are developing a module in a :ref:`collection `, see those documents instead. + .. contents:: :local: @@ -17,48 +19,27 @@ If you need functionality that is not available in any of the thousands of Ansib Preparing an environment for developing Ansible modules ======================================================= -Installing prerequisites via apt (Ubuntu) ------------------------------------------ - -Due to dependencies (for example ansible -> paramiko -> pynacl -> libffi): - -.. code:: bash - - sudo apt update - sudo apt install build-essential libssl-dev libffi-dev python-dev - -Installing prerequisites via yum (CentOS) ------------------------------------------ - -Due to dependencies (for example ansible -> paramiko -> pynacl -> libffi): +You just need ``ansible-core`` installed to test the module. Modules can be written in any language, +but most of the following guide is assuming you are using Python. +Modules for inclusion in Ansible itself must be Python or Powershell. -.. code:: bash +One advantage of using Python or Powershell for your custom modules is being able to use the ``module_utils`` common code that does a lot of the +heavy lifting for argument processing, logging and response writing, among other things. - sudo yum check-update - sudo yum update - sudo yum group install "Development Tools" - sudo yum install python3-devel openssl-devel libffi libffi-devel +Creating a module +================= -Creating a development environment (platform-independent steps) ---------------------------------------------------------------- +It is highly recommended that you use a ``venv`` or ``virtualenv`` for Python development. -1. Clone the Ansible repository: - ``$ git clone https://github.com/ansible/ansible.git`` -2. Change directory into the repository root dir: ``$ cd ansible`` -3. Create a virtual environment: ``$ python3 -m venv venv`` (or for - Python 2 ``$ virtualenv venv``. Note, this requires you to install - the virtualenv package: ``$ pip install virtualenv``) -4. Activate the virtual environment: ``$ . venv/bin/activate`` -5. Install development requirements: - ``$ pip install -r requirements.txt`` -6. Run the environment setup script for each new development shell process: - ``$ . hacking/env-setup`` +To create a module: -.. note:: After the initial setup above, every time you are ready to start - developing Ansible you should be able to just run the following from the - root of the Ansible repo: - ``$ . venv/bin/activate && . hacking/env-setup`` +1. Create a ``library`` directory in your workspace, your test play should live in the same directory. +2. Create your new module file: ``$ touch library/my_test.py``. Or just open/create it with your editor of choice. +3. Paste the content below into your new module file. It includes the :ref:`required Ansible format and documentation `, a simple :ref:`argument spec for declaring the module options `, and some example code. +4. Modify and extend the code to do what you want your new module to do. See the :ref:`programming tips ` and :ref:`Python 3 compatibility ` pages for pointers on writing clean and concise module code. +.. literalinclude:: ../../../../examples/scripts/my_test.py + :language: python Creating an info or a facts module ================================== @@ -83,33 +64,7 @@ Info and facts modules, are just like any other Ansible Module, with a few minor 5. They MUST NOT make any changes to the system. 6. They MUST document the :ref:`return fields` and :ref:`examples`. -To create an info module: - -1. Navigate to the correct directory for your new module: ``$ cd lib/ansible/modules/``. If you are developing module using collection, ``$ cd plugins/modules/`` inside your collection development tree. -2. Create your new module file: ``$ touch my_test_info.py``. -3. Paste the content below into your new info module file. It includes the :ref:`required Ansible format and documentation `, a simple :ref:`argument spec for declaring the module options `, and some example code. -4. Modify and extend the code to do what you want your new info module to do. See the :ref:`programming tips ` and :ref:`Python 3 compatibility ` pages for pointers on writing clean and concise module code. - -.. literalinclude:: ../../../../examples/scripts/my_test_info.py - :language: python - -Use the same process to create a facts module. - -.. literalinclude:: ../../../../examples/scripts/my_test_facts.py - :language: python - -Creating a module -================= - -To create a module: - -1. Navigate to the correct directory for your new module: ``$ cd lib/ansible/modules/``. If you are developing a module in a :ref:`collection `, ``$ cd plugins/modules/`` inside your collection development tree. -2. Create your new module file: ``$ touch my_test.py``. -3. Paste the content below into your new module file. It includes the :ref:`required Ansible format and documentation `, a simple :ref:`argument spec for declaring the module options `, and some example code. -4. Modify and extend the code to do what you want your new module to do. See the :ref:`programming tips ` and :ref:`Python 3 compatibility ` pages for pointers on writing clean and concise module code. - -.. literalinclude:: ../../../../examples/scripts/my_test.py - :language: python +The rest is just like creating a normal module. Verifying your module code ========================== @@ -121,9 +76,21 @@ Our :ref:`debugging tips ` will help if you run into bugs as Verifying your module code locally ---------------------------------- +The simplest way is to use ``ansible`` adhoc command: + +.. code:: shell + + ansible -m library/my_test.py -a 'name=hello new=true' remotehost + If your module does not need to target a remote host, you can quickly and easily exercise your code locally like this: -- Create an arguments file, a basic JSON config file that passes parameters to your module so that you can run it. Name the arguments file ``/tmp/args.json`` and add the following content: +.. code:: shell + + ansible -m library/my_test.py -a 'name=hello new=true' localhost + +- If for any reason (pdb, using print(), faster iteration, etc) you want to avoid going through Ansible, + another way is to create an arguments file, a basic JSON config file that passes parameters to your module so that you can run it. + Name the arguments file ``/tmp/args.json`` and add the following content: .. code:: json @@ -134,23 +101,24 @@ If your module does not need to target a remote host, you can quickly and easily } } -- If you are using a virtual environment (which is highly recommended for - development) activate it: ``$ . venv/bin/activate`` -- Set up the environment for development: ``$ . hacking/env-setup`` -- Run your test module locally and directly: - ``$ python -m ansible.modules.my_test /tmp/args.json`` +- Then the module can be tested locally and directly. This skips the packing steps and uses module_utils files directly: + +.. code:: console -This should return output like this: + ``$ python library/my_test.py /tmp/args.json`` + +It should return output like this: .. code:: json {"changed": true, "state": {"original_message": "hello", "new_message": "goodbye"}, "invocation": {"module_args": {"name": "hello", "new": true}}} + Verifying your module code in a playbook ---------------------------------------- -The next step in verifying your new module is to consume it with an Ansible playbook. +You can easily run a full test by including it in a playbook, as long as the ``library`` directory is in the same directory as the play: - Create a playbook in any directory: ``$ touch testmod.yml`` - Add the following to the new playbook file: @@ -178,7 +146,7 @@ The following two examples will get you started with testing your module code. P information, including instructions for :ref:`testing module documentation `, adding :ref:`integration tests `, and more. .. note:: - Every new module and plugin should have integration tests, even if the tests cannot be run on Ansible CI infrastructure. + If contributing to Ansible, every new module and plugin should have integration tests, even if the tests cannot be run on Ansible CI infrastructure. In this case, the tests should be marked with the ``unsupported`` alias in `aliases file `_. Performing sanity tests @@ -186,26 +154,11 @@ Performing sanity tests You can run through Ansible's sanity checks in a container: -``$ ansible-test sanity -v --docker --python 2.7 MODULE_NAME`` +``$ ansible-test sanity -v --docker --python 3.10 MODULE_NAME`` .. note:: Note that this example requires Docker to be installed and running. If you'd rather not use a container for this, you can choose to use ``--venv`` instead of ``--docker``. -Adding unit tests ------------------ - -You can add unit tests for your module in ``./test/units/modules``. You must first set up your testing environment. In this example, we're using Python 3.5. - -- Install the requirements (outside of your virtual environment): ``$ pip3 install -r ./test/lib/ansible_test/_data/requirements/units.txt`` -- Run ``. hacking/env-setup`` -- To run all tests do the following: ``$ ansible-test units --python 3.5``. If you are using a CI environment, these tests will run automatically. - -.. note:: Ansible uses pytest for unit testing. - -To run pytest against a single test module, you can run the following command. Ensure that you are providing the correct path of the test module: - -``$ pytest -r a --cov=. --cov-report=html --fulltrace --color yes -test/units/modules/.../test/my_test.py`` Contributing back to Ansible ============================ diff --git a/docs/docsite/rst/dev_guide/testing_sanity.rst b/docs/docsite/rst/dev_guide/testing_sanity.rst index a97dec3f22d..01b167bc3c5 100644 --- a/docs/docsite/rst/dev_guide/testing_sanity.rst +++ b/docs/docsite/rst/dev_guide/testing_sanity.rst @@ -36,8 +36,11 @@ How to run # Run all sanity tests including disabled ones ansible-test sanity --allow-disabled - # Run all sanity tests against against certain files + # Run all sanity tests against certain file(s) ansible-test sanity lib/ansible/modules/files/template.py + + # Run all sanity tests against certain folder(s) + ansible-test sanity lib/ansible/modules/files/ # Run all tests inside docker (good if you don't have dependencies installed) ansible-test sanity --docker default diff --git a/docs/docsite/rst/porting_guides/porting_guide_6.rst b/docs/docsite/rst/porting_guides/porting_guide_6.rst index 418f64ca654..88943cb9e85 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_6.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_6.rst @@ -99,6 +99,193 @@ Networking No notable changes +Porting Guide for v6.0.0a2 +========================== + +Known Issues +------------ + +ansible.netcommon +~~~~~~~~~~~~~~~~~ + +- eos - When using eos modules on Ansible 2.9, tasks will occasionally fail with ``import_modules`` enabled. This can be avoided by setting ``import_modules: no`` + +community.general +~~~~~~~~~~~~~~~~~ + +- pacman - ``update_cache`` cannot differentiate between up to date and outdated package lists and will report ``changed`` in both situations (https://github.com/ansible-collections/community.general/pull/4318). +- pacman - binaries specified in the ``executable`` parameter must support ``--print-format`` in order to be used by this module. In particular, AUR helper ``yay`` is known not to currently support it (https://github.com/ansible-collections/community.general/pull/4312). + +dellemc.openmanage +~~~~~~~~~~~~~~~~~~ + +- idrac_user - Issue(192043) The 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. +- ome_application_alerts_smtp - Issue(212310) - The module does not provide a proper error message if the destination_address is more than 255 characters. +- ome_application_alerts_syslog - Issue(215374) - The module does not provide a proper error message if the destination_address is more than 255 characters. +- ome_application_console_preferences - Issue(224690) - The module does not display a proper error message when an unsupported value is provided for the parameters report_row_limit, email_sender_settings, and metric_collection_settings, and the value is applied on OpenManage Enterprise. +- ome_device_local_access_configuration - Issue(215035) - The module reports ``Successfully updated the local access setting`` if an unsupported value is provided for the parameter timeout_limit. However, this value is not actually applied on OpenManage Enterprise Modular. +- ome_device_local_access_configuration - Issue(217865) - The module does not display a proper error message if an unsupported value is provided for the user_defined and lcd_language parameters. +- ome_device_network_services - Issue(212681) - The module does not provide a proper error message if unsupported values are provided for the parameters- port_number, community_name, max_sessions, max_auth_retries, and idle_timeout. +- ome_device_power_settings - Issue(212679) - The module displays the following message if the value provided for the parameter ``power_cap`` is not within the supported range of 0 to 32767, ``Unable to complete the request because PowerCap does not exist or is not applicable for the resource URI.`` +- ome_device_quick_deploy - Issue(216352) - The module does not display a proper error message if an unsupported value is provided for the ipv6_prefix_length and vlan_id parameters. +- ome_smart_fabric_uplink - Issue(186024) - The module does not allow the creation of multiple uplinks of the same name even though it is supported by OpenManage Enterprise Modular. If an uplink is created using the same name as an existing uplink, the existing uplink is modified. + +Breaking Changes +---------------- + +ansible.netcommon +~~~~~~~~~~~~~~~~~ + +- httpapi - Change default value of ``import_modules`` option from ``no`` to ``yes`` +- netconf - Change default value of ``import_modules`` option from ``no`` to ``yes`` +- network_cli - Change default value of ``import_modules`` option from ``no`` to ``yes`` + +arista.eos +~~~~~~~~~~ + +- httpapi - the ``eos_use_sessions`` option is now a boolean instead of an integer. + +community.general +~~~~~~~~~~~~~~~~~ + +- Parts of this collection do not work with ansible-core 2.11 on Python 3.12+. Please either upgrade to ansible-core 2.12+, or use Python 3.11 or earlier (https://github.com/ansible-collections/community.general/pull/3988). +- The symbolic links used to implement flatmapping for all modules were removed and replaced by ``meta/runtime.yml`` redirects. This effectively breaks compatibility with Ansible 2.9 for all modules (without using their "long" names, which is discouraged and which can change without previous notice since they are considered an implementation detail) (https://github.com/ansible-collections/community.general/pull/4548). +- a_module test plugin - remove Ansible 2.9 compatibility code (https://github.com/ansible-collections/community.general/pull/4548). +- archive - remove Ansible 2.9 compatibility code (https://github.com/ansible-collections/community.general/pull/4548). +- git_config - remove Ansible 2.9 and early ansible-base 2.10 compatibility code (https://github.com/ansible-collections/community.general/pull/4548). +- java_keystore - remove Ansible 2.9 compatibility code (https://github.com/ansible-collections/community.general/pull/4548). +- lists_mergeby filter plugin - remove Ansible 2.9 compatibility code (https://github.com/ansible-collections/community.general/pull/4548). +- maven_artifact - remove Ansible 2.9 compatibility code (https://github.com/ansible-collections/community.general/pull/4548). +- memcached cache plugin - remove Ansible 2.9 compatibility code (https://github.com/ansible-collections/community.general/pull/4548). +- path_join filter plugin shim - remove Ansible 2.9 compatibility code (https://github.com/ansible-collections/community.general/pull/4548). +- redis cache plugin - remove Ansible 2.9 compatibility code (https://github.com/ansible-collections/community.general/pull/4548). + +Major Changes +------------- + +ansible.netcommon +~~~~~~~~~~~~~~~~~ + +- cli_parse - this module has been moved to the ansible.utils collection. ``ansible.netcommon.cli_parse`` will continue to work to reference the module in its new location, but this redirect will be removed in a future release +- network_cli - Change default value of `ssh_type` option from `paramiko` to `auto`. This value will use libssh if the ansible-pylibssh module is installed, otherwise will fallback to paramiko. + +arista.eos +~~~~~~~~~~ + +- Minimum required ansible.netcommon version is 2.5.1. +- Updated base plugin references to ansible.netcommon. +- `eos_facts` - change default gather_subset to `min` from `!config` (https://github.com/ansible-collections/arista.eos/issues/306). + +cisco.ios +~~~~~~~~~ + +- Minimum required ansible.netcommon version is 2.5.1. +- Updated base plugin references to ansible.netcommon. +- `facts` - default value for `gather_subset` is changed to min instead of !config. + +cisco.iosxr +~~~~~~~~~~~ + +- Minimum required ansible.netcommon version is 2.5.1. +- Updated base plugin references to ansible.netcommon. +- `facts` - default value for `gather_subset` is changed to min instead of !config. + +cisco.nxos +~~~~~~~~~~ + +- The minimum required ansible.netcommon version has been bumped to v2.6.1. +- Updated base plugin references to ansible.netcommon. +- `nxos_facts` - change default gather_subset to `min` from `!config` (https://github.com/ansible-collections/cisco.nxos/issues/418). +- nxos_file_copy has been rewritten as a module. This change also removes the dependency on pexpect for file_pull operation. Since this now uses AnsibleModule class for argspec validation, the validation messages will be slighlty different. Expect changes in the return payload in some cases. All functionality remains unchanged. + +community.general +~~~~~~~~~~~~~~~~~ + +- The community.general collection no longer supports Ansible 2.9 and ansible-base 2.10. While we take no active measures to prevent usage, we will remove a lot of compatibility code and other compatility measures that will effectively prevent using most content from this collection with Ansible 2.9, and some content of this collection with ansible-base 2.10. Both Ansible 2.9 and ansible-base 2.10 will very soon be End of Life and if you are still using them, you should consider upgrading to ansible-core 2.11 or later as soon as possible (https://github.com/ansible-collections/community.general/pull/4548). + +community.postgresql +~~~~~~~~~~~~~~~~~~~~ + +- The community.postgresql collection no longer supports ``Ansible 2.9`` and ``ansible-base 2.10``. While we take no active measures to prevent usage and there are no plans to introduce incompatible code to the modules, we will stop testing against ``Ansible 2.9`` and ``ansible-base 2.10``. Both will very soon be End of Life and if you are still using them, you should consider upgrading to the ``latest Ansible / ansible-core 2.11 or later`` as soon as possible (https://github.com/ansible-collections/community.postgresql/pull/245). + +community.vmware +~~~~~~~~~~~~~~~~ + +- Drop VCSIM as a test target (https://github.com/ansible-collections/community.vmware/pull/1294). + +ibm.qradar +~~~~~~~~~~ + +- Minimum required ansible.netcommon version is 2.5.1. +- Updated base plugin references to ansible.netcommon. + +junipernetworks.junos +~~~~~~~~~~~~~~~~~~~~~ + +- Minimum required ansible.netcommon version is 2.5.1. +- Updated base plugin references to ansible.netcommon. +- `junos_facts` - change default gather_subset to `min` from `!config`. + +splunk.es +~~~~~~~~~ + +- Minimum required ansible.netcommon version is 2.5.1. +- Updated base plugin references to ansible.netcommon. + +vyos.vyos +~~~~~~~~~ + +- Minimum required ansible.netcommon version is 2.5.1. +- Updated base plugin references to ansible.netcommon. +- `vyos_facts` - change default gather_subset to `min` from `!config` (https://github.com/ansible-collections/vyos.vyos/issues/231). + +Removed Collections +------------------- + +- community.kubernetes (previously included version: 2.0.1) +- community.kubevirt (previously included version: 1.0.0) + +Removed Features +---------------- + +- The community.kubernetes collection has been removed from Ansible 6. It has been deprecated since Ansible 4.2, and version 2.0.0 included since Ansible 5 is only a set of deprecated redirects from community.kubernetes to kubernetes.core. If you still need the redirects, you can manually install community.kubernetes with ``ansible-galaxy collection install community.kubernetes`` (https://github.com/ansible-community/community-topics/issues/93). +- The community.kubevirt collection has been removed from Ansible 6. It has not been working with the community.kubernetes collection included since Ansible 5.0.0, and unfortunately nobody managed to adjust the collection to work with kubernetes.core >= 2.0.0. If you need to use this collection, you need to manually install community.kubernetes < 2.0.0 together with community.kubevirt with ``ansible-galaxy collection install community.kubevirt 'community.kubernetes:<2.0.0'`` (https://github.com/ansible-community/community-topics/issues/92). + +community.general +~~~~~~~~~~~~~~~~~ + +- ali_instance_info - removed the options ``availability_zone``, ``instance_ids``, and ``instance_names``. Use filter item ``zone_id`` instead of ``availability_zone``, filter item ``instance_ids`` instead of ``instance_ids``, and filter item ``instance_name`` instead of ``instance_names`` (https://github.com/ansible-collections/community.general/pull/4516). +- apt_rpm - removed the deprecated alias ``update-cache`` of ``update_cache`` (https://github.com/ansible-collections/community.general/pull/4516). +- compose - removed various deprecated aliases. Use the version with ``_`` instead of ``-`` instead (https://github.com/ansible-collections/community.general/pull/4516). +- dnsimple - remove support for dnsimple < 2.0.0 (https://github.com/ansible-collections/community.general/pull/4516). +- github_deploy_key - removed the deprecated alias ``2fa_token`` of ``otp`` (https://github.com/ansible-collections/community.general/pull/4516). +- homebrew, homebrew_cask - removed the deprecated alias ``update-brew`` of ``update_brew`` (https://github.com/ansible-collections/community.general/pull/4516). +- linode - removed the ``backupsenabled`` option. Use ``backupweeklyday`` or ``backupwindow`` to enable backups (https://github.com/ansible-collections/community.general/pull/4516). +- opkg - removed the deprecated alias ``update-cache`` of ``update_cache`` (https://github.com/ansible-collections/community.general/pull/4516). +- pacman - if ``update_cache=true`` is used with ``name`` or ``upgrade``, the changed state will now also indicate if only the cache was updated. To keep the old behavior - only indicate ``changed`` when a package was installed/upgraded -, use ``changed_when`` as indicated in the module examples (https://github.com/ansible-collections/community.general/pull/4516). +- pacman - removed the deprecated alias ``update-cache`` of ``update_cache`` (https://github.com/ansible-collections/community.general/pull/4516). +- proxmox, proxmox_kvm, proxmox_snap - no longer allow to specify a VM name that matches multiple VMs. If this happens, the modules now fail (https://github.com/ansible-collections/community.general/pull/4516). +- serverless - removed the ``functions`` option. It was not used by the module (https://github.com/ansible-collections/community.general/pull/4516). +- slackpkg - removed the deprecated alias ``update-cache`` of ``update_cache`` (https://github.com/ansible-collections/community.general/pull/4516). +- urpmi - removed the deprecated alias ``no-recommends`` of ``no_recommends`` (https://github.com/ansible-collections/community.general/pull/4516). +- urpmi - removed the deprecated alias ``update-cache`` of ``update_cache`` (https://github.com/ansible-collections/community.general/pull/4516). +- xbps - removed the deprecated alias ``update-cache`` of ``update_cache`` (https://github.com/ansible-collections/community.general/pull/4516). +- xfconf - the ``get`` state has been removed. Use the ``xfconf_info`` module instead (https://github.com/ansible-collections/community.general/pull/4516). + +Deprecated Features +------------------- + +community.general +~~~~~~~~~~~~~~~~~ + +- gem - the default of the ``norc`` option has been deprecated and will change to ``true`` in community.general 6.0.0. Explicitly specify a value to avoid a deprecation warning (https://github.com/ansible-collections/community.general/pull/4517). +- 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). +- module_helper module utils - deprecated the attribute ``ModuleHelper.VarDict`` (https://github.com/ansible-collections/community.general/pull/3801). +- nmcli - deprecate default hairpin mode for a bridge. This so we can change it to ``false`` in community.general 7.0.0, as this is also the default in ``nmcli`` (https://github.com/ansible-collections/community.general/pull/4334). +- pacman - from community.general 5.0.0 on, the ``changed`` status of ``update_cache`` will no longer be ignored if ``name`` or ``upgrade`` is specified. To keep the old behavior, add something like ``register: result`` and ``changed_when: result.packages | length > 0`` to your task (https://github.com/ansible-collections/community.general/pull/4329). +- proxmox inventory plugin - the current default ``true`` of the ``want_proxmox_nodes_ansible_host`` option has been deprecated. The default will change to ``false`` in community.general 6.0.0. To keep the current behavior, explicitly set ``want_proxmox_nodes_ansible_host`` to ``true`` in your inventory configuration. We suggest to already switch to the new behavior by explicitly setting it to ``false``, and by using ``compose:`` to set ``ansible_host`` to the correct value. See the examples in the plugin documentation for details (https://github.com/ansible-collections/community.general/pull/4466). +- vmadm - deprecated module parameter ``debug`` that was not used anywhere (https://github.com/ansible-collections/community.general/pull/4580). + Porting Guide for v6.0.0a1 ========================== @@ -115,12 +302,6 @@ Ansible-core - get_url - document ``check_mode`` correctly with unreliable changed status (https://github.com/ansible/ansible/issues/65687). -community.general -~~~~~~~~~~~~~~~~~ - -- pacman - ``update_cache`` cannot differentiate between up to date and outdated package lists and will report ``changed`` in both situations (https://github.com/ansible-collections/community.general/pull/4318). -- pacman - binaries specified in the ``executable`` parameter must support ``--print-format`` in order to be used by this module. In particular, AUR helper ``yay`` is known not to currently support it (https://github.com/ansible-collections/community.general/pull/4312). - dellemc.openmanage ~~~~~~~~~~~~~~~~~~ @@ -460,13 +641,6 @@ cisco.nxos - Deprecated nxos_snmp_traps module. - Deprecated nxos_snmp_user module. -community.general -~~~~~~~~~~~~~~~~~ - -- 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). -- module_helper module utils - deprecated the attribute ``ModuleHelper.VarDict`` (https://github.com/ansible-collections/community.general/pull/3801). -- pacman - from community.general 5.0.0 on, the ``changed`` status of ``update_cache`` will no longer be ignored if ``name`` or ``upgrade`` is specified. To keep the old behavior, add something like ``register: result`` and ``changed_when: result.packages | length > 0`` to your task (https://github.com/ansible-collections/community.general/pull/4329). - community.hashi_vault ~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/docsite/rst/user_guide/become.rst b/docs/docsite/rst/user_guide/become.rst index cdf2c40b205..4c40d383600 100644 --- a/docs/docsite/rst/user_guide/become.rst +++ b/docs/docsite/rst/user_guide/become.rst @@ -284,6 +284,12 @@ To force ``become`` to open a new systemd session that goes through For more information, see `this systemd issue `_. +Resolving Temporary File Error Messsages +---------------------------------------- + +* Failed to set permissions on the temporary files Ansible needs to create when becoming an unprivileged user" +* This error can be resolved by installing the package that provides the ``setfacl`` command. (This is frequently the ``acl`` package but check your OS documentation.) + .. _become_network: Become and network automation @@ -389,12 +395,17 @@ delegation or accessing forbidden system calls like the WUA API. You can use ``become`` with the same user as ``ansible_user`` to bypass these limitations and run commands that are not normally accessible in a WinRM session. +.. Note:: + On Windows you cannot connect with an underprivileged account and use become + to elevate your rights. Become can only be used if your connection account + is already an Administrator of the target host. + Administrative rights --------------------- Many tasks in Windows require administrative privileges to complete. When using the ``runas`` become method, Ansible will attempt to run the module with the -full privileges that are available to the remote user. If it fails to elevate +full privileges that are available to the become user. If it fails to elevate the user token, it will continue to use the limited token during execution. A user must have the ``SeDebugPrivilege`` to run a become process with elevated @@ -749,11 +760,9 @@ Limitations of become on Windows * The Secondary Logon service ``seclogon`` must be running to use ``ansible_become_method: runas`` -Resolving Temporary File Error Messsages ----------------------------------------- - -"Failed to set permissions on the temporary files Ansible needs to create when becoming an unprivileged user" -* This error can be resolved by installing the package that provides the ``setfacl`` command. (This is frequently the ``acl`` package but check your OS documentation. +* The connection user must already be an Administrator on the Windows host to + use ``runas``. The target become user does not need to be an Administrator + though. .. seealso:: diff --git a/docs/docsite/sphinx_conf/ansible_conf.py b/docs/docsite/sphinx_conf/ansible_conf.py index 7cc7d24eb30..8c6c895c826 100644 --- a/docs/docsite/sphinx_conf/ansible_conf.py +++ b/docs/docsite/sphinx_conf/ansible_conf.py @@ -94,6 +94,7 @@ exclude_patterns = [ '2.10_index.rst', 'ansible_index.rst', 'core_index.rst', + 'dev_guide/core_branches_and_tags.rst', 'porting_guides/core_porting_guides.rst', 'porting_guides/porting_guide_base_2.10.rst', 'porting_guides/porting_guide_core_*', diff --git a/docs/docsite/sphinx_conf/core_conf.py b/docs/docsite/sphinx_conf/core_conf.py index bd3fe06151d..4bb7d749198 100644 --- a/docs/docsite/sphinx_conf/core_conf.py +++ b/docs/docsite/sphinx_conf/core_conf.py @@ -104,6 +104,7 @@ exclude_patterns = [ 'community/collection_contributors/collection_test_pr_locally.rst', 'community/collection_contributors/collection_integration_tests.rst', 'community/collection_contributors/collection_integration_running.rst', + 'community/collection_contributors/collection_reviewing.rst', 'community/collection_contributors/collection_unit_tests.rst', 'community/maintainers.rst', 'community/contributions_collections.rst',