New release v2.13.2 (#78276)

* Pr 72292- Add context to inventory plugins (#78070)

* Add context to inventory plugins documentation

* Show how to add the inventory plugin to the `enable_plugins` configuration item - not just replace it.
* Show adding tags to `keyed_groups` without specifying the separator.
* Show adding more complex `groups` and `compose` statements, including using the ternary filter.
* As I added an additional group, I've updated the resulting `ansible-inventory` output accordingly.

(cherry picked from commit a77fc2e822)

* Update dpkg_selections.py (#78177)

* Update dpkg_selections.py to include an syntax example showing how to remove package holds

* Fix pep8 issue: dpkg_selections.py

Missed some trailing spaces when adding example text.

(cherry picked from commit 489b7f1859)

* fix ternary problem (#78186)

(cherry picked from commit 7ec8916097)

* documentation: become plugins: correct pluralization in description (#78196)

fixes #78195

(cherry picked from commit e10851d495)

* Update python_3_support.rst (#78239)

Fix invalid characters warning when using example group names. (Replace dashes in example group name with underscores.)

(cherry picked from commit be88250a83)

* Adding applicable licensing requirements (#78162)

(cherry picked from commit 6ddccc1604)

* Document choice to use Ansible Project in copyright lines (#78164)

Co-authored-by: Sviatoslav Sydorenko <wk.cvs.github@sydorenko.org.ua>
(cherry picked from commit c9a341902b)

* stat only returns pw_name/gr_name if those can be looked up (#78183)

(cherry picked from commit 221af7640d)

* example showing how to deal with keys w/o apt_key (#78206)

(cherry picked from commit 0590ce065c)

* Migrate vmware.vmware_rest Dev Guide to collection (#78255)

(cherry picked from commit 048adac5b7)

* Updated release_and_maintenance.rst (#78272)

(cherry picked from commit 358a8ad7af)

Co-authored-by: Micah Beasley <MBfromOK@users.noreply.github.com>
Co-authored-by: Alex Willmer <alex@moreati.org.uk>
Co-authored-by: Nathan Hyde <nathanhyde@gmail.com>
Co-authored-by: Desmond Obisi <51109125+DesmondSanctity@users.noreply.github.com>
Co-authored-by: Evgeni Golov <evgeni@golov.de>
Co-authored-by: Brian Coca <bcoca@users.noreply.github.com>
Co-authored-by: Mario Lenz <m@riolenz.de>
Co-authored-by: Ompragash Viswanathan <21008429+Ompragash@users.noreply.github.com>

.azure-pipelines/azure-pipelines.yml

@@ -34,7 +34,7 @@ variables:
 resources:
   containers:
     - container: default
-      image: quay.io/ansible/azure-pipelines-test-container:1.9.0
+      image: quay.io/ansible/azure-pipelines-test-container:3.0.0
 
 pool: Standard
 
@@ -94,6 +94,8 @@ stages:
               test: rhel/8.5@3.6
             - name: RHEL 8.5 py38
               test: rhel/8.5@3.8
+            - name: RHEL 9.0
+              test: rhel/9.0
             - name: FreeBSD 12.3
               test: freebsd/12.3
             - name: FreeBSD 13.0

.gitignore

@@ -38,6 +38,7 @@ docs/docsite/rst/cli/ansible-*.rst
 docs/docsite/rst/cli/ansible.rst
 docs/docsite/rst/dev_guide/collections_galaxy_meta.rst
 docs/docsite/rst/dev_guide/testing/sanity/index.rst.new
+docs/docsite/rst/dev_guide/index.rst
 docs/docsite/rst/modules/*.rst
 docs/docsite/rst/collections/*.rst
 !docs/docsite/rst/collections/all_plugins.rst

MANIFEST.in

@@ -7,6 +7,7 @@ include docs/docsite/rst/collections/all_plugins.rst
 exclude docs/docsite/rst_warnings
 exclude docs/docsite/rst/conf.py
 exclude docs/docsite/rst/index.rst
+exclude docs/docsite/rst/dev_guide/index.rst
 exclude docs/docsite/rst/dev_guide/testing/sanity/bin-symlinks.rst
 exclude docs/docsite/rst/dev_guide/testing/sanity/botmeta.rst
 exclude docs/docsite/rst/dev_guide/testing/sanity/integration-aliases.rst

changelogs/CHANGELOG-v2.13.rst

@@ -0,0 +1,444 @@
+=========================================================
+ansible-core 2.13 "Nobody's Fault but Mine" Release Notes
+=========================================================
+
+.. contents:: Topics
+
+
+v2.13.2
+=======
+
+Release Summary
+---------------
+
+| Release Date: 2022-07-18
+| `Porting Guide <https://docs.ansible.com/ansible/devel/porting_guides.html>`__
+
+
+Minor Changes
+-------------
+
+- ansible-test - An improved error message is shown when the download of a pip bootstrap script fails. The download now uses ``urllib2`` instead of ``urllib`` on Python 2.
+
+Bugfixes
+--------
+
+- Move undefined check from concat to finalize (https://github.com/ansible/ansible/issues/78156)
+- ansible-doc - no longer list module and plugin aliases that are created with symlinks (https://github.com/ansible/ansible/pull/78137).
+- ansible-doc - when listing modules in collections, proceed recursively. This fixes module listing for community.general 5.x.y and community.network 4.x.y (https://github.com/ansible/ansible/pull/78137).
+- ansible-doc will not add 'website for' in ":ref:" substitutions as it made them confusing.
+- file backed cache plugins now handle concurrent access by making atomic updates to the files.
+- password lookup does not ignore k=v arguments anymore.
+- user - Fix error "Permission denied" in user module while generating SSH keys (https://github.com/ansible/ansible/issues/78017).
+
+v2.13.1
+=======
+
+Release Summary
+---------------
+
+| Release Date: 2022-06-20
+| `Porting Guide <https://docs.ansible.com/ansible/devel/porting_guides.html>`__
+
+
+Minor Changes
+-------------
+
+- Add an 'action_plugin' field for modules in runtime.yml plugin_routing.
+
+  This fixes module_defaults by supporting modules-as-redirected-actions
+  without redirecting module_defaults entries to the common action.
+
+  .. code: yaml
+
+     plugin_routing:
+       action:
+         facts:
+           redirect: ns.coll.eos
+         command:
+           redirect: ns.coll.eos
+       modules:
+         facts:
+           redirect: ns.coll.eos_facts
+         command:
+           redirect: ns.coll.eos_command
+
+  With the runtime.yml above for ns.coll, a task such as
+
+  .. code: yaml
+
+     - hosts: all
+       module_defaults:
+         ns.coll.eos_facts: {'valid_for_eos_facts': 'value'}
+         ns.coll.eos_command: {'not_valid_for_eos_facts': 'value'}
+       tasks:
+         - ns.coll.facts:
+
+  will end up with defaults for eos_facts and eos_command
+  since both modules redirect to the same action.
+
+  To select an action plugin for a module without merging
+  module_defaults, define an action_plugin field for the resolved
+  module in the runtime.yml.
+
+  .. code: yaml
+
+     plugin_routing:
+       modules:
+         facts:
+           redirect: ns.coll.eos_facts
+           action_plugin: ns.coll.eos
+         command:
+           redirect: ns.coll.eos_command
+           action_plugin: ns.coll.eos
+
+  The action_plugin field can be a redirected action plugin, as
+  it is resolved normally.
+
+  Using the modified runtime.yml, the example task will only use
+  the ns.coll.eos_facts defaults.
+- ansible-galaxy - Support resolvelib versions 0.6.x, 0.7.x, and 0.8.x. The full range of supported versions is now >= 0.5.3, < 0.9.0.
+- ansible-test - Add RHEL 9.0 remote support.
+- ansible-test - Add support for Ubuntu VMs using the ``--remote`` option.
+- ansible-test - Add support for exporting inventory with ``ansible-test shell --export {path}``.
+- ansible-test - Add support for multi-arch remotes.
+- ansible-test - Add support for running non-interactive commands with ``ansible-test shell``.
+- ansible-test - Avoid using the ``mock_use_standalone_module`` setting for unit tests running on Python 3.8 or later.
+- ansible-test - Blocking mode is now enforced for stdin, stdout and stderr. If any of these are non-blocking then ansible-test will exit during startup with an error.
+- ansible-test - Improve consistency of output messages by using stdout or stderr for most output, but not both.
+- ansible-test - The ``shell`` command can be used outside a collection if no controller delegation is required.
+
+Bugfixes
+--------
+
+- Add PyYAML >= 5.1 as a dependency of ansible-core to be compatible with Python 3.8+.
+- ansible-config dump - Only display plugin type headers when plugin options are changed if --only-changed is specified.
+- ansible-galaxy - handle unsupported versions of resolvelib gracefully.
+- ansible-test - Fix internal validation of remote completion configuration.
+- ansible-test - Prevent ``--target-`` prefixed options for the ``shell`` command from being combined with legacy environment options.
+- ansible-test - Sanity test output with the ``--lint`` option is no longer mixed in with bootstrapping output.
+- ansible-test - Subprocesses are now isolated from the stdin, stdout and stderr of ansible-test. This avoids issues with subprocesses tampering with the file descriptors, such as SSH making them non-blocking. As a result of this change, subprocess output from unit and integration tests on stderr now go to stdout.
+- ansible-test - Subprocesses no longer have access to the TTY ansible-test is connected to, if any. This maintains consistent behavior between local testing and CI systems, which typically do not provide a TTY. Tests which require a TTY should use pexpect or another mechanism to create a PTY.
+- apt module now correctly handles virtual packages.
+- lookup plugin - catch KeyError when lookup returns dictionary (https://github.com/ansible/ansible/pull/77789).
+- pip - fix cases where resolution of pip Python module fails when importlib.util has not already been imported
+- plugin loader - Sort results when fuzzy matching plugin names (https://github.com/ansible/ansible/issues/77966).
+- plugin loader will now load config data for plugin by name instead of by file to avoid issues with the same file being loaded under different names (fqcn + short name).
+- psrp connection now handles default to inventory_hostname correctly.
+- winrm connection now handles default to inventory_hostname correctly.
+
+v2.13.0
+=======
+
+Release Summary
+---------------
+
+| Release Date: 2022-05-16
+| `Porting Guide <https://docs.ansible.com/ansible/devel/porting_guides.html>`__
+
+
+Major Changes
+-------------
+
+- Jinja2 Controller Requirement - Jinja2 3.0.0 or newer is required for the control node (the machine that runs Ansible) (https://github.com/ansible/ansible/pull/75881)
+- Templating - remove ``safe_eval`` in favor of using ``NativeEnvironment`` but utilizing ``literal_eval`` only in cases when ``safe_eval`` was used (https://github.com/ansible/ansible/pull/75587)
+
+Minor Changes
+-------------
+
+- Action Plugins - Add helper method for argument spec validation, and extend to pause and async_wrapper
+- Added AIX root CA certs folders - enhance the TLS support in ``uri`` task on AIX
+- Added ``module_utils.compat.typing`` to facilitate type-hinting on all supported Python versions.
+- Ansible.Basic - small changes to allow use in PowerShell modules running on non-Windows platforms (https://github.com/ansible/ansible/pull/76924).
+- AnsibleModule.run_command() now has a toggle to allow caller to decide to handle exceptions from executing the command itself
+- Attach concat function to an environment class (https://github.com/ansible/ansible/pull/76282)
+- Clarify in a comment that unrolling an iterator in ``Templar._finalize`` is actually necessary. Also switch to using the ``_unroll_iterator`` decorator directly to deduplicate code in ``Templar._finalize``. (https://github.com/ansible/ansible/pull/76436)
+- Installation - modernize our python installation, to reduce dynamic code in setup.py, and migrate what is feasible to setup.cfg. This will enable shipping wheels in the future.
+- PlayIterator - introduce public methods to access ``PlayIterator._host_states`` (https://github.com/ansible/ansible/pull/74416)
+- PlayIterator - use enums for Iterating and Failed states (https://github.com/ansible/ansible/pull/74511)
+- Reduce number of iterations through PlayIterator (https://github.com/ansible/ansible/pull/74175)
+- Remove more Python 2.x compatibility code from controller (https://github.com/ansible/ansible/pull/77320).
+- Start of moving away from using Six, Python 2 and 3 compatibility library (https://github.com/ansible/ansible/pull/75863)
+- The collection loader now reports a Python warning if an attempt is made to install the Ansible collection loader a second time. Previously this condition was reported using an Ansible warning.
+- ``ansible-galaxy collection [install|verify]`` - allow user-provided signature sources in addition to those from the Galaxy server. Each collection entry in a requirements file can specify a ``signatures`` key followed by a list of sources. Collection name(s) provided on the CLI can specify additional signature sources by using the ``--signatures`` CLI option. Signature sources should be URIs that can be opened with ``urllib.request.urlopen()``, such as "https://example.com/path/to/detached_signature.asc" or "file:///path/to/detached_signature.asc". The ``--keyring`` option must be specified if signature sources are provided.
+- ``ansible-galaxy collection [install|verify]`` - use gpg to verify the authenticity of the signed ``MANIFEST.json`` with ASCII armored detached signatures provided by the Galaxy server. The keyring (which is not managed by ``ansible-galaxy``) must be provided with the ``--keyring`` option to use signature verification. If no ``--keyring`` is specified and the collection to ``install|verify`` has associated detached signatures on the Galaxy server, a warning is provided.
+- ``ansible-galaxy collection install`` - Add a global configuration to modify the required number of signatures that must verify the authenticity of the collection. By default, the number of required successful signatures is 1. Set this option to ``all`` to require all signatures verify the collection. To ensure signature verification fails if there are no valid signatures, prepend the value with '+', such as ``+all`` or ``+1``.
+- ``ansible-galaxy collection install`` - Add a global ignore list for gpg signature errors. This can be used to ignore certain signatures when the number of required successful signatures is all. When the required number of successful signatures is a positive integer, the only effect this has is to display fewer errors to the user on failure (success is determined by having the minimum number of successful signatures, in which case all errors are disregarded).
+- ``ansible-galaxy collection install`` - Add a global toggle to turn off GPG signature verification.
+- ``ansible-galaxy collection install`` - Store Galaxy server metadata alongside installed collections for provenance. Signatures obtained from the Galaxy server can be used for offline verification with ``ansible-galaxy collection verify --offline``.
+- ansible-console - Provide a  way to customize the stdout callback
+- ansible-core modules - Remove unused Python shebangs from built-in modules.
+- ansible-doc metadata dump - add option ``--no-fail-on-errors`` which allows to not fail the ansible-doc invocation when errors happen during docs parsing or processing. Instead they are reported in the JSON result in an ``error`` key for the affected plugins (https://github.com/ansible/ansible/pull/77035).
+- ansible-galaxy - the option to skip certificate verification now also applies when cloning via SCM (git/hg) (https://github.com/ansible/ansible/issues/41077)
+- ansible-test - Accept new-style Python modules without a shebang.
+- ansible-test - Add ``--version`` support to show the ansible-core version.
+- ansible-test - Add support for ``rhel/8.5`` remote instances.
+- ansible-test - Add support for remote testing of FreeBSD 12.3.
+- ansible-test - Add support for running container tests with ``podman remote`` (https://github.com/ansible/ansible/pull/75753)
+- ansible-test - Added the ``fedora35`` test container.
+- ansible-test - Change the maximum number of open files in a test container from the default to ``10240``.
+- ansible-test - Declare public dependencies of ansible-core and use to limit unguarded imports in plugins.
+- ansible-test - Importing ``distutils`` now results in an error.
+- ansible-test - Installation of ``cryptography`` is no longer version constrained when ``openssl`` 1.1.0 or later is installed.
+- ansible-test - Miscellaneous code cleanup and type hint fixes.
+- ansible-test - PowerShell in the ``base`` and ``default`` containers has been upgraded to version 7.1.4.
+- ansible-test - Remove RHEL 8.4 remote (``rhel/8.4``) support.
+- ansible-test - Remove ``idna`` constraint.
+- ansible-test - Remove obsolete ``MAXFD`` display.
+- ansible-test - Remove obsolete constraints for Python 2.6.
+- ansible-test - Remove support for FreeBSD 12.2 remote provisioning.
+- ansible-test - Remove support for macOS 11.1 remote provisioning.
+- ansible-test - Remove support for provisioning remote AIX instances.
+- ansible-test - Remove the ``centos8`` test container since CentOS 8 will reach end-of-life soon.
+- ansible-test - Remove the ``fedora33`` test container since Fedora 33 will reach end-of-life soon.
+- ansible-test - Remove unused Python 2.x compatibility code.
+- ansible-test - Removed support for Sherlock from the Azure provisioning plugin.
+- ansible-test - Removed used ``MarkupSafe`` constraint for Python 3.5 and earlier.
+- ansible-test - Requirements for the plugin import test are now frozen.
+- ansible-test - Shellcheck in the ``base`` and ``default`` containers has been upgraded to version 0.7.0.
+- ansible-test - Stop early with an error if the current working directory contains an invalid collection namespace or name.
+- ansible-test - The ``--help`` option is now available when an unsupported cwd is in use.
+- ansible-test - The ``--help`` output now shows the same instructions about cwd as would be shown in error messages if the cwd is unsupported.
+- ansible-test - The ``pip`` and ``wheel`` packages are removed from all sanity test virtual environments after installation completes to reduce their size. Previously they were only removed from the environments used for the ``import`` sanity test.
+- ansible-test - The explanation about cwd usage has been improved to explain more clearly what is required.
+- ansible-test - The hash for all managed sanity test virtual environments has changed. Containers that include ``ansible-test sanity --prime-venvs`` will need to be rebuilt to continue using primed virtual environments.
+- ansible-test - Update ``base`` container to version 2.1.0.
+- ansible-test - Update ``base`` container to version 2.2.0.
+- ansible-test - Update ``default`` containers to version 5.2.0.
+- ansible-test - Update ``default`` containers to version 5.4.0.
+- ansible-test - Update ``default`` containers to version 5.5.0.
+- ansible-test - Update ``default`` containers to version 5.6.2.
+- ansible-test - Update ``default`` containers to version 5.7.0.
+- ansible-test - Update ``default`` containers to version 5.8.0.
+- ansible-test - Update ``default`` containers to version 5.9.0.
+- ansible-test - Update ``pip`` used to bootstrap remote FreeBSD instances from version 20.3.4 to 21.3.1.
+- ansible-test - Update sanity test requirements.
+- ansible-test - Update the NIOS test plugin container to version 1.4.0.
+- ansible-test - Update the ``alpine`` container to version 3.3.0. This updates the base image from 3.14.2 to 3.15.0, which includes support for installing binary wheels using pip.
+- ansible-test - Update the ``base`` and ``default`` containers from Python 3.10.0rc2 to 3.10.0.
+- ansible-test - Update the ``base`` and ``default`` containers from a Ubuntu 18.04 to Ubuntu 20.04 base image.
+- ansible-test - Update the ``default`` containers to version 5.1.0.
+- ansible-test - Update the ``galaxy`` test plugin to get its container from a copy on quay.io.
+- ansible-test - Update the ``openshift`` test plugin to get its container from a copy on quay.io.
+- ansible-test - Use Python 3.10 as the default Python version for the ``base`` and ``default`` containers.
+- ansible-test - add macOS 12.0 as a remote target (https://github.com/ansible/ansible/pull/76328)
+- ansible-test - handle JSON decode error gracefully in podman environment.
+- ansible-test pslint - Added the `AvoidLongLines <https://github.com/PowerShell/PSScriptAnalyzer/blob/master/docs/Rules/AvoidLongLines.md>`_ rule set to a length of 160.
+- ansible-test pslint - Added the `PlaceCloseBrace <https://github.com/PowerShell/PSScriptAnalyzer/blob/master/docs/Rules/PlaceCloseBrace.md>`_ rule set to enforce close braces on a newline.
+- ansible-test pslint - Added the `PlaceOpenBrace <https://github.com/PowerShell/PSScriptAnalyzer/blob/master/docs/Rules/PlaceOpenBrace.md>`_ rule set to enforce open braces on the same line and a subsequent newline.
+- ansible-test pslint - Added the `UseConsistentIndentation <https://github.com/PowerShell/PSScriptAnalyzer/blob/master/docs/Rules/UseConsistentIndentation.md>`_ rule to enforce indentation is done with 4 spaces.
+- ansible-test pslint - Added the `UseConsistentWhitespace <https://github.com/PowerShell/PSScriptAnalyzer/blob/master/docs/Rules/UseConsistentWhitespace.md>`_ rule to enforce whitespace consistency in PowerShell.
+- ansible-test pslint - Updated ``PowerShellScriptAnalyzer`` to 1.20.0
+- ansible-test sanity validate-modules - the validate-modules sanity test now also checks the documentation of documentable plugin types (https://github.com/ansible/ansible/pull/71734).
+- ansible-test validate-modules sanity test - add more schema checks to improve quality of plugin documentation (https://github.com/ansible/ansible/pull/77268).
+- ansible-test validate_modules - allow ``choices`` for return values (https://github.com/ansible/ansible/pull/76009).
+- apt - Add support for using ">=" in package version number matching.
+- apt - Adds APT option ``--allow-change-held-packages`` as module parameter ``allow_change_held_packages`` to allow APT up- or downgrading a package which is on APTs hold list (https://github.com/ansible/ansible/issues/65325)
+- auto inventory plugin will now give plugin loading information on verbose output
+- callbacks - Add result serialization format options to ``_dump_results`` allowing plugins such as the ``default`` callback to emit ``YAML`` serialized task results in addition to ``JSON``
+- dnf - add more specific error message for GPG validation (https://github.com/ansible/ansible/issues/76192)
+- env lookup, add default option
+- facts - report prefix length for IPv4 addresses in Linux network facts.
+- get_parsable_locale now logs result when in debug mode.
+- git - display the destination directory path in error msg when local_mods detects local modifications conflict so that users see the exact location
+- iptables - add the ``chain_management`` parameter that controls iptables chain creation and deletion
+- jinja2_native - keep same behavior on Python 3.10.
+- junit callback - Add support for replacing the directory portion of out-of-tree relative task paths with a placeholder.
+- k8s - scenario guides for kubernetes migrated to ``kubernetes.core`` collection.
+- module_utils.distro - Add missing ``typing`` import from original code.
+- package_facts - add pkg_info support for OpenBSD and NetBSD (https://github.com/ansible/ansible/pull/76580)
+- services_facts - Add support for openrc (https://github.com/ansible/ansible/pull/76373).
+- setting DEFAULT_FACT_PATH is being deprecated in favor of the generic module_defaults keyword
+- uri - Avoid reading the response body when not needed
+- uri - Eliminate multiple requests to determine the final URL for file naming with ``dest``
+- validate-modules - do some basic validation on the ``M(...)``, ``U(...)``, ``L(..., ...)`` and ``R(..., ...)`` documentation markups (https://github.com/ansible/ansible/pull/76262).
+- vmware - migrated vmware scenario guides to `community.vmware` repo.
+- yum, dnf - add sslverify option to temporarily disable certificate validation for a repository
+
+Breaking Changes / Porting Guide
+--------------------------------
+
+- Module Python Dependency - Drop support for Python 2.6 in module execution.
+- Templating - it is no longer allowed to perform arithmetic and concatenation operations outside of the jinja template (https://github.com/ansible/ansible/pull/75587)
+- The ``finalize`` method is no longer exposed in the globals for use in templating.
+
+Deprecated Features
+-------------------
+
+- ansible-core - Remove support for Python 2.6.
+- ansible-test - Remove support for Python 2.6.
+- ssh connection plugin option scp_if_ssh in favor of ssh_transfer_method.
+
+Removed Features (previously deprecated)
+----------------------------------------
+
+- Remove deprecated ``Templar.set_available_variables()`` method (https://github.com/ansible/ansible/issues/75828)
+- cli - remove deprecated ability to set verbosity before the sub-command (https://github.com/ansible/ansible/issues/75823)
+- copy - remove deprecated ``thirsty`` alias (https://github.com/ansible/ansible/issues/75824)
+- psrp - Removed fallback on ``put_file`` with older ``pypsrp`` versions. Users must have at least ``pypsrp>=0.4.0``.
+- url_argument_spec - remove deprecated ``thirsty`` alias for ``get_url`` and ``uri`` modules (https://github.com/ansible/ansible/issues/75825, https://github.com/ansible/ansible/issues/75826)
+
+Security Fixes
+--------------
+
+- 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
+--------
+
+- Add a YAML representer for ``NativeJinjaText``
+- Add a YAML representer for ``NativeJinjaUnsafeText``
+- AnsiballZ - Ensure we use the full python package in the module cache filename to avoid a case where ``collections:`` is used to execute a module via short name, where the short name duplicates another module from ``ansible.builtin`` or another collection that was executed previously.
+- Ansible.ModuleUtils.LinkUtil - Ignore the ``LIB`` environment variable when loading the ``LinkUtil`` code
+- Ansible.ModuleUtils.SID - Use user principal name as is for lookup in the ``Convert-ToSID`` function - https://github.com/ansible/ansible/issues/77316
+- Detect package manager for Amazon Linux 2022 (AL2022) as dnf
+- Ensure the correct ``environment_class`` is set on ``AnsibleJ2Template``
+- Fix ``AttributeError`` when providing password file via ``--connection-password-file`` (https://github.com/ansible/ansible/issues/76530)
+- Fix ``end_play`` to end the current play only (https://github.com/ansible/ansible/issues/76672)
+- Fix collection filter/test plugin redirects (https://github.com/ansible/ansible/issues/77192).
+- Fix executing includes in the always section in the free strategy (https://github.com/ansible/ansible/issues/75642)
+- Fix for when templating empty template file resulted in file with string 'None' (https://github.com/ansible/ansible/issues/76610)
+- Fix help message for the 'ansible-galaxy collection verify' positional argument. The positional argument must be a collection name (https://github.com/ansible/ansible/issues/76087).
+- Fix module logging issue when using custom module on WSL2 (https://github.com/ansible/ansible/issues/76320)
+- Fix task debugger to work with ``run_once`` using ``linear`` strategy (https://github.com/ansible/ansible/issues/76049)
+- Fix traceback when installing a collection from a git repository and git is not installed (https://github.com/ansible/ansible/issues/77479).
+- Interpreter Discovery - Fallback to OS family if the distro is not found in ``INTERPRETER_PYTHON_DISTRO_MAP`` (https://github.com/ansible/ansible/issues/75560)
+- Interpreter discovery - Add ``RHEL`` to ``OS_FAMILY_MAP`` for correct family fallback for interpreter discovery (https://github.com/ansible/ansible/issues/77368)
+- Make include_role/include_tasks work with any_errors_fatal (https://github.com/ansible/ansible/issues/50897)
+- Parser errors from within includes should not be rescueable (https://github.com/ansible/ansible/issues/73657)
+- Prevent losing unsafe on results returned from lookups (https://github.com/ansible/ansible/issues/77535)
+- Templating - Ensure we catch exceptions when getting ``.filters`` and ``.tests`` attributes on their respective plugins and properly error, instead of aborting which results in no filters being added to the jinja2 environment
+- Trigger an undefined error when an undefined variable is detected within a dictionary and/or list (https://github.com/ansible/ansible/pull/75587)
+- _run_loop - Add the task name to the warning (https://github.com/ansible/ansible/issues/76011)
+- ``Templar.copy_with_new_env`` - set the ``finalize`` method of the new ``Templar`` object for the new environment (https://github.com/ansible/ansible/issues/76379)
+- add_host/group_by: fix using changed_when in a loop (https://github.com/ansible/ansible/issues/71627)
+- ansible - Exclude Python 2.6 from Python interpreter discovery.
+- ansible-config avoid showing _terms and _input when --only-changed.
+- ansible-doc - Fix ansible-doc -l ansible.builtin / ansible.legacy not returning anything
+- ansible-doc - ignore plugin deprecation warnings (https://github.com/ansible/ansible/issues/75671)
+- ansible-galaxy - Add galaxy_collection_skeleton/galaxy_collection_skeleton_ignore configuration options
+- ansible-galaxy - Fix using the '--ignore-certs' option when there is no server-specific configuration for the Galaxy server.
+- ansible-galaxy - installing/downloading collections with invalid versions in git repositories and directories now gives a formatted error message (https://github.com/ansible/ansible/issues/76425, https://github.com/ansible/ansible/issues/75404).
+- ansible-galaxy - when installing a role properly raise an error when inaccessible path is specified multiple times in roles_path (e.g. via environment variable and command line option) (https://github.com/ansible/ansible/issues/76316)
+- ansible-galaxy collection build - Ignore any existing ``MANIFEST.json`` and ``FILES.json`` in the root directory when building a collection.
+- ansible-galaxy collection verify - display files/directories not included in the FILES.json as modified content.
+- ansible-galaxy publish - Fix warning and error detection in import messages to properly display them in Ansible
+- ansible-pull handle case where hostname and nodename are empty
+- ansible-test - Add default entry for Windows remotes to be used with unknown versions.
+- ansible-test - All virtual environments managed by ansible-test are marked as usable after being bootstrapped, to avoid errors caused by use of incomplete environments. Previously this was only done for sanity tests. Existing environments from previous versions of ansible-test will be recreated on demand due to lacking the new marker.
+- ansible-test - Automatic target requirements installation is now based on the target environment instead of the controller environment.
+- ansible-test - Correctly detect when running as the ``root`` user (UID 0) on the origin host. The result of the detection was incorrectly being inverted.
+- ansible-test - Don't fail if network cannot be disconnected (https://github.com/ansible/ansible/pull/77472)
+- ansible-test - Fix Python real prefix detection when running in a ``venv`` virtual environment.
+- ansible-test - Fix ``windows-integration`` and ``network-integration`` when used with the ``--docker`` option and user-provided inventory.
+- ansible-test - Fix installation and usage of ``pyyaml`` requirement for the ``import`` sanity test for collections.
+- ansible-test - Fix path to inventory file for ``windows-integration`` and ``network-integration`` commands for collections.
+- ansible-test - Fix plugin loading.
+- ansible-test - Fix skipping of tests marked ``needs/python`` on the origin host.
+- ansible-test - Fix skipping of tests marked ``needs/root`` on the origin host.
+- ansible-test - Fix the ``import`` sanity test to work properly when Ansible's built-in vendoring support is in use.
+- ansible-test - Fix the ``validate-modules`` sanity test to avoid double-loading the collection loader and possibly failing on import of the ``packaging`` module.
+- ansible-test - Fix traceback in ``import`` sanity test on Python 2.7 when ``pip`` is not available.
+- ansible-test - Fix traceback in the ``validate-modules`` sanity test when testing an Ansible module without any callables.
+- ansible-test - Fix traceback when running from an install and delegating execution to a different Python interpreter.
+- ansible-test - Fix traceback when using the ``--all`` option with PowerShell code coverage.
+- ansible-test - Fix type hints.
+- ansible-test - Import ``yaml.cyaml.CParser`` instead of ``_yaml.CParser`` in the ``yamllint`` sanity test.
+- ansible-test - Limit ``paramiko`` installation to versions before 2.9.0. This is required to maintain support for systems which do not support RSA SHA-2 algorithms.
+- ansible-test - Pylint Deprecated Plugin - Use correct message symbols when date or version is not a float or str (https://github.com/ansible/ansible/issues/77085)
+- ansible-test - Relocate constants to eliminate symlink.
+- ansible-test - Replace the directory portion of out-of-tree paths in JUnit files from integration tests with the ``out-of-tree:`` prefix.
+- ansible-test - Sanity tests run with the ``--requirements` option for Python 2.x now install ``virtualenv`` when it is missing or too old. Previously it was only installed if missing. Version 16.7.12 is now installed instead of the latest version.
+- ansible-test - Set the ``pytest`` option ``--rootdir`` instead of letting it be auto-detected.
+- ansible-test - Show an error message instead of a traceback when running outside of a supported directory.
+- ansible-test - Target integration test requirements are now correctly installed for target environments running on the controller.
+- ansible-test - The ``import`` sanity test no longer reports errors about ``packaging`` being missing when testing collections.
+- ansible-test - Update distribution test containers to version 3.1.0.
+- ansible-test - Update help links to reference ``ansible-core`` instead of ``ansible``.
+- ansible-test - Update unit tests to use the ``--forked`` option instead of the deprecated ``--boxed`` option.
+- ansible-test - Use https://ci-files.testing.ansible.com/ for instance bootstrapping instead of an S3 endpoint.
+- ansible-test - Use relative paths in JUnit files generated during integration test runs.
+- ansible-test - Use the correct variable to reference the client's SSH key when generating inventory.
+- ansible-test - Use the legacy collection loader for ``import`` sanity tests on target-only Python versions.
+- ansible-test - Virtual environments managed by ansible-test now use consistent versions of ``pip``, ``setuptools`` and ``wheel``. This avoids issues with virtual environments containing outdated or dysfunctional versions of these tools. The initial bootstrapping of ``pip`` is done by ansible-test from an HTTPS endpoint instead of creating the virtual environment with it already present.
+- ansible-test - fix a typo in validate-modules.
+- ansible-test - fixed support container failures (eg http-test-container) under podman
+- ansible-test compile sanity test - do not crash if a column could not be determined for an error (https://github.com/ansible/ansible/pull/77465).
+- ansible-test pslint - Fix error when encountering validation results that are highly nested - https://github.com/ansible/ansible/issues/74151
+- ansible-vault encrypt_string - fix ``--output`` option to correctly write encrypted string into given file (https://github.com/ansible/ansible/issues/75101)
+- ansible.builtin.file modification_time supports check_mode
+- ansible_facts.devices - Fix parsing of device serial number detected via sg_inq for rhel8 (https://github.com/ansible/ansible/issues/75420)
+- apt - fails to deploy deb file to old debian systems using python-apt < 0.8.9 (https://github.com/ansible/ansible/issues/47277)
+- arg_spec - Fix incorrect ``no_log`` warning when a parameter alias is used (https://github.com/ansible/ansible/pull/77576)
+- async - Improve performance of sending async callback events by never sending the full task through the queue (https://github.com/ansible/ansible/issues/76729)
+- catch the case that cowsay is broken which would lead to missing output
+- cleaning facts will now only warn about the variable name and not post the content, which can be undesireable to disclose
+- collection_loader - Implement 'find_spec' and 'exec_module' to override deprecated importlib methods 'find_module' and 'load_module' when applicable (https://github.com/ansible/ansible/issues/74660).
+- correctly inherit vars from parent in block (https://github.com/ansible/ansible/issues/75286).
+- default callback - Ensure we compare FQCN also in lockstep logic, to ensure using the FQCN of a strategy plugin triggers the correct behavior in the default callback plugin. (https://github.com/ansible/ansible/issues/76782)
+- distribution - add EuroLinux to fact gathering (https://github.com/ansible/ansible/pull/76624).
+- distribution - detect tencentos and gather correct facts on the distro.
+- dnf - ensure releasever is passed into libdnf as string (https://github.com/ansible/ansible/issues/77010)
+- extend timeout for ansible-galaxy when communicating with the galaxy server api, and apply it to all interactions with the api
+- facts - add support for deepin distro information detection (https://github.com/ansible/ansible/issues/77286).
+- first_found - fix to allow for spaces in file names (https://github.com/ansible/ansible/issues/77136)
+- gather_facts - Fact gathering now continues even if it fails to read a file
+- gather_facts action now handles the move of base connection plugin types into collections to add/prevent subset argument correctly
+- gather_facts/setup will not fail anymore if capsh is present but not executable
+- git module fix docs and proper use of ssh wrapper script and GIT_SSH_COMMAND depending on version.
+- git module is more consistent and clearer about which ssh options are added to git calls.
+- git module no longer uses wrapper script for ssh options.
+- hacking - fix incorrect usage of deprecated fish-shell redirection operators that failed to honor ``--quiet`` flag when sourced (https://github.com/ansible/ansible/pull/77180).
+- hostname - Do not require SystemdStrategy subclasses for every distro (https://github.com/ansible/ansible/issues/76792)
+- hostname - Fix Debian strategy KeyError, use `SystemdStrategy` (https://github.com/ansible/ansible/issues/76124)
+- hostname - Update the systemd strategy in the ``hostname`` module to not interfere with NetworkManager (https://github.com/ansible/ansible/issues/76958)
+- hostname - add hostname support for openEuler distro (https://github.com/ansible/ansible/pull/76619).
+- hostname - use ``file_get_content()`` to read the file containing the host name in the ``FileStrategy.get_permanent_hostname()`` method. This prevents a ``TypeError`` from being raised when the strategy is used (https://github.com/ansible/ansible/issues/77025).
+- include_vars, properly initialize variable as there is corner case in which it can end up referenced and not defined
+- inventory - parameterize ``disable_lookups`` in ``Constructable`` (https://github.com/ansible/ansible/issues/76769).
+- inventory manager now respects --flush-cache
+- junit callback - Fix traceback during automatic fact gathering when using relative paths.
+- junit callback - Fix unicode error when handling non-ASCII task paths.
+- module_utils.common.yaml - The ``SafeLoader``, ``SafeDumper`` and ``Parser`` classes now fallback to ``object`` when ``yaml`` is not available. This fixes tracebacks when inheriting from these classes without requiring a ``HAS_YAML`` guard around class definitions.
+- parameters - handle blank values when argument is a list (https://github.com/ansible/ansible/issues/77108).
+- play_context now compensates for when a conneciton sets the default to inventory_hostname but skips adding it to the vars.
+- playbook/strategy have more informative 'attribute' based errors for playbook objects and handlers.
+- python modules (new type) will now again prefer the specific python stated in the module's shebang instead of hardcoding to /usr/bin/python.
+- replace - Always return ``rc`` to ensure return values are consistent - https://github.com/ansible/ansible/pull/71963
+- script - skip in check mode if the plugin cannot determine if a change will occur (i.e. neither `creates` or `removes` are provided).
+- service - Fixed handling of sleep arguments during service restarts on AIX. (https://github.com/ansible/ansible/issues/76877)
+- service - Fixed service restarts with arguments on AIX. (https://github.com/ansible/ansible/issues/76840)
+- service_facts module will now give more meaningful warnings when it fails to gather data.
+- set_fact/include_vars correctly handle delegation assignments within loops
+- setup - detect docker container with check for ./dockerenv or ./dockinit (https://github.com/ansible/ansible/pull/74349).
+- shell/command - only return changed as True if the task has not been skipped.
+- shell/command - only skip in check mode if the options `creates` and `removes` are both None.
+- ssh connection - properly quote controlpersist path given by user to avoid issues with spaces and other characters
+- ssh connection avoid parsing ssh cli debug lines as they can match expected output at high verbosities.
+- ssh connection now uses more correct host source as play_context can ignore loop/delegation variations.
+- sudo become plugin, fix handling of non interactive flags, previous substitution was too naive
+- systemd - check if service is alias so it gets enabled (https://github.com/ansible/ansible/issues/75538).
+- systemd - check if service is indirect so it gets enabled (https://github.com/ansible/ansible/issues/76453).
+- task_executor reverts the change to push facts into delegated vars on loop finalization as result managing code already handles this and was duplicating effort to wrong result.
+- template lookup - restore inadvertently deleted default for ``convert_data`` (https://github.com/ansible/ansible/issues/77004)
+- to_json/to_nice_json filters defaults back to unvaulting/no unsafe packing.
+- unarchive - Fix zip archive file listing that caused issues with content postprocessing (https://github.com/ansible/ansible/issues/76067).
+- unarchive - Make extraction work when the LANGUAGE environment variable is set to a non-English locale.
+- unarchive - apply ``owner`` and ``group`` permissions to top folder (https://github.com/ansible/ansible/issues/35426)
+- unarchive - include the original error when a handler cannot manage the archive (https://github.com/ansible/ansible/issues/28977).
+- unarchive - the ``io_buffer_size`` option added in 2.12 was not accepted by the module (https://github.com/ansible/ansible/pull/77271).
+- urls - Allow ``ca_path`` to point to a bundle containing multiple PEM certs (https://github.com/ansible/ansible/issues/75015)
+- urls/uri - Address case where ``HTTPError`` isn't fully initialized due to the error, and is missing certain methods and attributes (https://github.com/ansible/ansible/issues/76386)
+- user - allow ``password_expiry_min`` and ``password_expiry_min`` to be set to ``0`` (https://github.com/ansible/ansible/issues/75017)
+- user - allow password min and max to be set at the same time (https://github.com/ansible/ansible/issues/75017)
+- user - update logic to check if user exists or not in MacOS.
+- validate_argument_spec - Skip suboption validation if the top level option is an invalid type (https://github.com/ansible/ansible/issues/75612).
+- variablemanager, more efficient read of vars files
+- vault - Warn instead of fail for missing vault IDs if at least one valid vault secret is found.
+- winrm - Ensure ``kinit`` is run with the same ``PATH`` env var as the Ansible process
+- yum - prevent storing unnecessary cache data by running `yum makecache fast` (https://github.com/ansible/ansible/issues/76336)
+
+Known Issues
+------------
+
+- get_url - document ``check_mode`` correctly with unreliable changed status (https://github.com/ansible/ansible/issues/65687).

changelogs/changelog.yaml

@@ -1,2 +1,926 @@
 ancestor: 2.12.0
-releases: {}
+releases:
+  2.13.0:
+    changes:
+      release_summary: '| Release Date: 2022-05-16
+
+        | `Porting Guide <https://docs.ansible.com/ansible/devel/porting_guides.html>`__
+
+        '
+    codename: Nobody's Fault but Mine
+    fragments:
+    - v2.13.0_summary.yaml
+    release_date: '2022-05-16'
+  2.13.0b0:
+    changes:
+      breaking_changes:
+      - Module Python Dependency - Drop support for Python 2.6 in module execution.
+      - Templating - it is no longer allowed to perform arithmetic and concatenation
+        operations outside of the jinja template (https://github.com/ansible/ansible/pull/75587)
+      - The ``finalize`` method is no longer exposed in the globals for use in templating.
+      bugfixes:
+      - Add a YAML representer for ``NativeJinjaText``
+      - Add a YAML representer for ``NativeJinjaUnsafeText``
+      - AnsiballZ - Ensure we use the full python package in the module cache filename
+        to avoid a case where ``collections:`` is used to execute a module via short
+        name, where the short name duplicates another module from ``ansible.builtin``
+        or another collection that was executed previously.
+      - Ansible.ModuleUtils.LinkUtil - Ignore the ``LIB`` environment variable when
+        loading the ``LinkUtil`` code
+      - Ansible.ModuleUtils.SID - Use user principal name as is for lookup in the
+        ``Convert-ToSID`` function - https://github.com/ansible/ansible/issues/77316
+      - Detect package manager for Amazon Linux 2022 (AL2022) as dnf
+      - Ensure the correct ``environment_class`` is set on ``AnsibleJ2Template``
+      - Fix ``AttributeError`` when providing password file via ``--connection-password-file``
+        (https://github.com/ansible/ansible/issues/76530)
+      - Fix ``end_play`` to end the current play only (https://github.com/ansible/ansible/issues/76672)
+      - Fix collection filter/test plugin redirects (https://github.com/ansible/ansible/issues/77192).
+      - Fix executing includes in the always section in the free strategy (https://github.com/ansible/ansible/issues/75642)
+      - Fix for when templating empty template file resulted in file with string 'None'
+        (https://github.com/ansible/ansible/issues/76610)
+      - Fix help message for the 'ansible-galaxy collection verify' positional argument.
+        The positional argument must be a collection name (https://github.com/ansible/ansible/issues/76087).
+      - Fix module logging issue when using custom module on WSL2 (https://github.com/ansible/ansible/issues/76320)
+      - Fix task debugger to work with ``run_once`` using ``linear`` strategy (https://github.com/ansible/ansible/issues/76049)
+      - Fix traceback when installing a collection from a git repository and git is
+        not installed (https://github.com/ansible/ansible/issues/77479).
+      - Interpreter Discovery - Fallback to OS family if the distro is not found in
+        ``INTERPRETER_PYTHON_DISTRO_MAP`` (https://github.com/ansible/ansible/issues/75560)
+      - Interpreter discovery - Add ``RHEL`` to ``OS_FAMILY_MAP`` for correct family
+        fallback for interpreter discovery (https://github.com/ansible/ansible/issues/77368)
+      - Make include_role/include_tasks work with any_errors_fatal (https://github.com/ansible/ansible/issues/50897)
+      - Parser errors from within includes should not be rescueable (https://github.com/ansible/ansible/issues/73657)
+      - Templating - Ensure we catch exceptions when getting ``.filters`` and ``.tests``
+        attributes on their respective plugins and properly error, instead of aborting
+        which results in no filters being added to the jinja2 environment
+      - Trigger an undefined error when an undefined variable is detected within a
+        dictionary and/or list (https://github.com/ansible/ansible/pull/75587)
+      - _run_loop - Add the task name to the warning (https://github.com/ansible/ansible/issues/76011)
+      - '``Templar.copy_with_new_env`` - set the ``finalize`` method of the new ``Templar``
+        object for the new environment (https://github.com/ansible/ansible/issues/76379)'
+      - 'add_host/group_by: fix using changed_when in a loop (https://github.com/ansible/ansible/issues/71627)'
+      - ansible-config avoid showing _terms and _input when --only-changed.
+      - ansible-doc - Fix ansible-doc -l ansible.builtin / ansible.legacy not returning
+        anything
+      - ansible-doc - ignore plugin deprecation warnings (https://github.com/ansible/ansible/issues/75671)
+      - ansible-galaxy - Add galaxy_collection_skeleton/galaxy_collection_skeleton_ignore
+        configuration options
+      - ansible-galaxy - Fix using the '--ignore-certs' option when there is no server-specific
+        configuration for the Galaxy server.
+      - ansible-galaxy - installing/downloading collections with invalid versions
+        in git repositories and directories now gives a formatted error message (https://github.com/ansible/ansible/issues/76425,
+        https://github.com/ansible/ansible/issues/75404).
+      - ansible-galaxy - when installing a role properly raise an error when inaccessible
+        path is specified multiple times in roles_path (e.g. via environment variable
+        and command line option) (https://github.com/ansible/ansible/issues/76316)
+      - ansible-galaxy collection build - Ignore any existing ``MANIFEST.json`` and
+        ``FILES.json`` in the root directory when building a collection.
+      - ansible-galaxy collection verify - display files/directories not included
+        in the FILES.json as modified content.
+      - ansible-galaxy publish - Fix warning and error detection in import messages
+        to properly display them in Ansible
+      - ansible-pull handle case where hostname and nodename are empty
+      - ansible-test - Add default entry for Windows remotes to be used with unknown
+        versions.
+      - ansible-test - All virtual environments managed by ansible-test are marked
+        as usable after being bootstrapped, to avoid errors caused by use of incomplete
+        environments. Previously this was only done for sanity tests. Existing environments
+        from previous versions of ansible-test will be recreated on demand due to
+        lacking the new marker.
+      - ansible-test - Automatic target requirements installation is now based on
+        the target environment instead of the controller environment.
+      - ansible-test - Correctly detect when running as the ``root`` user (UID 0)
+        on the origin host. The result of the detection was incorrectly being inverted.
+      - ansible-test - Don't fail if network cannot be disconnected (https://github.com/ansible/ansible/pull/77472)
+      - ansible-test - Fix Python real prefix detection when running in a ``venv``
+        virtual environment.
+      - ansible-test - Fix ``windows-integration`` and ``network-integration`` when
+        used with the ``--docker`` option and user-provided inventory.
+      - ansible-test - Fix installation and usage of ``pyyaml`` requirement for the
+        ``import`` sanity test for collections.
+      - ansible-test - Fix path to inventory file for ``windows-integration`` and
+        ``network-integration`` commands for collections.
+      - ansible-test - Fix plugin loading.
+      - ansible-test - Fix skipping of tests marked ``needs/python`` on the origin
+        host.
+      - ansible-test - Fix skipping of tests marked ``needs/root`` on the origin host.
+      - ansible-test - Fix the ``import`` sanity test to work properly when Ansible's
+        built-in vendoring support is in use.
+      - ansible-test - Fix the ``validate-modules`` sanity test to avoid double-loading
+        the collection loader and possibly failing on import of the ``packaging``
+        module.
+      - ansible-test - Fix traceback in ``import`` sanity test on Python 2.7 when
+        ``pip`` is not available.
+      - ansible-test - Fix traceback in the ``validate-modules`` sanity test when
+        testing an Ansible module without any callables.
+      - ansible-test - Fix traceback when running from an install and delegating execution
+        to a different Python interpreter.
+      - ansible-test - Fix traceback when using the ``--all`` option with PowerShell
+        code coverage.
+      - ansible-test - Fix type hints.
+      - ansible-test - Import ``yaml.cyaml.CParser`` instead of ``_yaml.CParser``
+        in the ``yamllint`` sanity test.
+      - ansible-test - Limit ``paramiko`` installation to versions before 2.9.0. This
+        is required to maintain support for systems which do not support RSA SHA-2
+        algorithms.
+      - ansible-test - Pylint Deprecated Plugin - Use correct message symbols when
+        date or version is not a float or str (https://github.com/ansible/ansible/issues/77085)
+      - ansible-test - Relocate constants to eliminate symlink.
+      - ansible-test - Replace the directory portion of out-of-tree paths in JUnit
+        files from integration tests with the ``out-of-tree:`` prefix.
+      - ansible-test - Sanity tests run with the ``--requirements` option for Python
+        2.x now install ``virtualenv`` when it is missing or too old. Previously it
+        was only installed if missing. Version 16.7.12 is now installed instead of
+        the latest version.
+      - ansible-test - Set the ``pytest`` option ``--rootdir`` instead of letting
+        it be auto-detected.
+      - ansible-test - Show an error message instead of a traceback when running outside
+        of a supported directory.
+      - ansible-test - Target integration test requirements are now correctly installed
+        for target environments running on the controller.
+      - ansible-test - The ``import`` sanity test no longer reports errors about ``packaging``
+        being missing when testing collections.
+      - ansible-test - Update distribution test containers to version 3.1.0.
+      - ansible-test - Update help links to reference ``ansible-core`` instead of
+        ``ansible``.
+      - ansible-test - Update unit tests to use the ``--forked`` option instead of
+        the deprecated ``--boxed`` option.
+      - ansible-test - Use https://ci-files.testing.ansible.com/ for instance bootstrapping
+        instead of an S3 endpoint.
+      - ansible-test - Use relative paths in JUnit files generated during integration
+        test runs.
+      - ansible-test - Use the correct variable to reference the client's SSH key
+        when generating inventory.
+      - ansible-test - Use the legacy collection loader for ``import`` sanity tests
+        on target-only Python versions.
+      - ansible-test - Virtual environments managed by ansible-test now use consistent
+        versions of ``pip``, ``setuptools`` and ``wheel``. This avoids issues with
+        virtual environments containing outdated or dysfunctional versions of these
+        tools. The initial bootstrapping of ``pip`` is done by ansible-test from an
+        HTTPS endpoint instead of creating the virtual environment with it already
+        present.
+      - ansible-test - fix a typo in validate-modules.
+      - ansible-test - fixed support container failures (eg http-test-container) under
+        podman
+      - ansible-test compile sanity test - do not crash if a column could not be determined
+        for an error (https://github.com/ansible/ansible/pull/77465).
+      - ansible-test pslint - Fix error when encountering validation results that
+        are highly nested - https://github.com/ansible/ansible/issues/74151
+      - ansible-vault encrypt_string - fix ``--output`` option to correctly write
+        encrypted string into given file (https://github.com/ansible/ansible/issues/75101)
+      - ansible.builtin.file modification_time supports check_mode
+      - ansible_facts.devices - Fix parsing of device serial number detected via sg_inq
+        for rhel8 (https://github.com/ansible/ansible/issues/75420)
+      - apt - fails to deploy deb file to old debian systems using python-apt < 0.8.9
+        (https://github.com/ansible/ansible/issues/47277)
+      - async - Improve performance of sending async callback events by never sending
+        the full task through the queue (https://github.com/ansible/ansible/issues/76729)
+      - catch the case that cowsay is broken which would lead to missing output
+      - cleaning facts will now only warn about the variable name and not post the
+        content, which can be undesireable to disclose
+      - collection_loader - Implement 'find_spec' and 'exec_module' to override deprecated
+        importlib methods 'find_module' and 'load_module' when applicable (https://github.com/ansible/ansible/issues/74660).
+      - correctly inherit vars from parent in block (https://github.com/ansible/ansible/issues/75286).
+      - default callback - Ensure we compare FQCN also in lockstep logic, to ensure
+        using the FQCN of a strategy plugin triggers the correct behavior in the default
+        callback plugin. (https://github.com/ansible/ansible/issues/76782)
+      - distribution - add EuroLinux to fact gathering (https://github.com/ansible/ansible/pull/76624).
+      - distribution - detect tencentos and gather correct facts on the distro.
+      - dnf - ensure releasever is passed into libdnf as string (https://github.com/ansible/ansible/issues/77010)
+      - extend timeout for ansible-galaxy when communicating with the galaxy server
+        api, and apply it to all interactions with the api
+      - facts - add support for deepin distro information detection (https://github.com/ansible/ansible/issues/77286).
+      - first_found - fix to allow for spaces in file names (https://github.com/ansible/ansible/issues/77136)
+      - gather_facts - Fact gathering now continues even if it fails to read a file
+      - gather_facts action now handles the move of base connection plugin types into
+        collections to add/prevent subset argument correctly
+      - gather_facts/setup will not fail anymore if capsh is present but not executable
+      - git module fix docs and proper use of ssh wrapper script and GIT_SSH_COMMAND
+        depending on version.
+      - git module is more consistent and clearer about which ssh options are added
+        to git calls.
+      - git module no longer uses wrapper script for ssh options.
+      - hacking - fix incorrect usage of deprecated fish-shell redirection operators
+        that failed to honor ``--quiet`` flag when sourced (https://github.com/ansible/ansible/pull/77180).
+      - hostname - Do not require SystemdStrategy subclasses for every distro (https://github.com/ansible/ansible/issues/76792)
+      - hostname - Fix Debian strategy KeyError, use `SystemdStrategy` (https://github.com/ansible/ansible/issues/76124)
+      - hostname - Update the systemd strategy in the ``hostname`` module to not interfere
+        with NetworkManager (https://github.com/ansible/ansible/issues/76958)
+      - hostname - add hostname support for openEuler distro (https://github.com/ansible/ansible/pull/76619).
+      - hostname - use ``file_get_content()`` to read the file containing the host
+        name in the ``FileStrategy.get_permanent_hostname()`` method. This prevents
+        a ``TypeError`` from being raised when the strategy is used (https://github.com/ansible/ansible/issues/77025).
+      - include_vars, properly initialize variable as there is corner case in which
+        it can end up referenced and not defined
+      - inventory - parameterize ``disable_lookups`` in ``Constructable`` (https://github.com/ansible/ansible/issues/76769).
+      - inventory manager now respects --flush-cache
+      - junit callback - Fix traceback during automatic fact gathering when using
+        relative paths.
+      - junit callback - Fix unicode error when handling non-ASCII task paths.
+      - module_utils.common.yaml - The ``SafeLoader``, ``SafeDumper`` and ``Parser``
+        classes now fallback to ``object`` when ``yaml`` is not available. This fixes
+        tracebacks when inheriting from these classes without requiring a ``HAS_YAML``
+        guard around class definitions.
+      - parameters - handle blank values when argument is a list (https://github.com/ansible/ansible/issues/77108).
+      - play_context now compensates for when a conneciton sets the default to inventory_hostname
+        but skips adding it to the vars.
+      - playbook/strategy have more informative 'attribute' based errors for playbook
+        objects and handlers.
+      - python modules (new type) will now again prefer the specific python stated
+        in the module's shebang instead of hardcoding to /usr/bin/python.
+      - replace - Always return ``rc`` to ensure return values are consistent - https://github.com/ansible/ansible/pull/71963
+      - script - skip in check mode if the plugin cannot determine if a change will
+        occur (i.e. neither `creates` or `removes` are provided).
+      - service - Fixed handling of sleep arguments during service restarts on AIX.
+        (https://github.com/ansible/ansible/issues/76877)
+      - service - Fixed service restarts with arguments on AIX. (https://github.com/ansible/ansible/issues/76840)
+      - service_facts module will now give more meaningful warnings when it fails
+        to gather data.
+      - set_fact/include_vars correctly handle delegation assignments within loops
+      - setup - detect docker container with check for ./dockerenv or ./dockinit (https://github.com/ansible/ansible/pull/74349).
+      - shell/command - only return changed as True if the task has not been skipped.
+      - shell/command - only skip in check mode if the options `creates` and `removes`
+        are both None.
+      - ssh connection - properly quote controlpersist path given by user to avoid
+        issues with spaces and other characters
+      - ssh connection avoid parsing ssh cli debug lines as they can match expected
+        output at high verbosities.
+      - ssh connection now uses more correct host source as play_context can ignore
+        loop/delegation variations.
+      - sudo become plugin, fix handling of non interactive flags, previous substitution
+        was too naive
+      - systemd - check if service is alias so it gets enabled (https://github.com/ansible/ansible/issues/75538).
+      - systemd - check if service is indirect so it gets enabled (https://github.com/ansible/ansible/issues/76453).
+      - task_executor reverts the change to push facts into delegated vars on loop
+        finalization as result managing code already handles this and was duplicating
+        effort to wrong result.
+      - template lookup - restore inadvertently deleted default for ``convert_data``
+        (https://github.com/ansible/ansible/issues/77004)
+      - to_json/to_nice_json filters defaults back to unvaulting/no unsafe packing.
+      - unarchive - Fix zip archive file listing that caused issues with content postprocessing
+        (https://github.com/ansible/ansible/issues/76067).
+      - unarchive - Make extraction work when the LANGUAGE environment variable is
+        set to a non-English locale.
+      - unarchive - apply ``owner`` and ``group`` permissions to top folder (https://github.com/ansible/ansible/issues/35426)
+      - unarchive - include the original error when a handler cannot manage the archive
+        (https://github.com/ansible/ansible/issues/28977).
+      - unarchive - the ``io_buffer_size`` option added in 2.12 was not accepted by
+        the module (https://github.com/ansible/ansible/pull/77271).
+      - urls - Allow ``ca_path`` to point to a bundle containing multiple PEM certs
+        (https://github.com/ansible/ansible/issues/75015)
+      - urls/uri - Address case where ``HTTPError`` isn't fully initialized due to
+        the error, and is missing certain methods and attributes (https://github.com/ansible/ansible/issues/76386)
+      - user - allow ``password_expiry_min`` and ``password_expiry_min`` to be set
+        to ``0`` (https://github.com/ansible/ansible/issues/75017)
+      - user - allow password min and max to be set at the same time (https://github.com/ansible/ansible/issues/75017)
+      - user - update logic to check if user exists or not in MacOS.
+      - validate_argument_spec - Skip suboption validation if the top level option
+        is an invalid type (https://github.com/ansible/ansible/issues/75612).
+      - vault - Warn instead of fail for missing vault IDs if at least one valid vault
+        secret is found.
+      - winrm - Ensure ``kinit`` is run with the same ``PATH`` env var as the Ansible
+        process
+      - yum - prevent storing unnecessary cache data by running `yum makecache fast`
+        (https://github.com/ansible/ansible/issues/76336)
+      deprecated_features:
+      - ansible-core - Remove support for Python 2.6.
+      - ansible-test - Remove support for Python 2.6.
+      - ssh connection plugin option scp_if_ssh in favor of ssh_transfer_method.
+      known_issues:
+      - get_url - document ``check_mode`` correctly with unreliable changed status
+        (https://github.com/ansible/ansible/issues/65687).
+      major_changes:
+      - Jinja2 Controller Requirement - Jinja2 3.0.0 or newer is required for the
+        control node (the machine that runs Ansible) (https://github.com/ansible/ansible/pull/75881)
+      - Templating - remove ``safe_eval`` in favor of using ``NativeEnvironment``
+        but utilizing ``literal_eval`` only in cases when ``safe_eval`` was used (https://github.com/ansible/ansible/pull/75587)
+      minor_changes:
+      - Action Plugins - Add helper method for argument spec validation, and extend
+        to pause and async_wrapper
+      - Added AIX root CA certs folders - enhance the TLS support in ``uri`` task
+        on AIX
+      - Added ``module_utils.compat.typing`` to facilitate type-hinting on all supported
+        Python versions.
+      - Ansible.Basic - small changes to allow use in PowerShell modules running on
+        non-Windows platforms (https://github.com/ansible/ansible/pull/76924).
+      - AnsibleModule.run_command() now has a toggle to allow caller to decide to
+        handle exceptions from executing the command itself
+      - Attach concat function to an environment class (https://github.com/ansible/ansible/pull/76282)
+      - Clarify in a comment that unrolling an iterator in ``Templar._finalize`` is
+        actually necessary. Also switch to using the ``_unroll_iterator`` decorator
+        directly to deduplicate code in ``Templar._finalize``. (https://github.com/ansible/ansible/pull/76436)
+      - Installation - modernize our python installation, to reduce dynamic code in
+        setup.py, and migrate what is feasible to setup.cfg. This will enable shipping
+        wheels in the future.
+      - PlayIterator - introduce public methods to access ``PlayIterator._host_states``
+        (https://github.com/ansible/ansible/pull/74416)
+      - PlayIterator - use enums for Iterating and Failed states (https://github.com/ansible/ansible/pull/74511)
+      - Reduce number of iterations through PlayIterator (https://github.com/ansible/ansible/pull/74175)
+      - Remove more Python 2.x compatibility code from controller (https://github.com/ansible/ansible/pull/77320).
+      - Start of moving away from using Six, Python 2 and 3 compatibility library
+        (https://github.com/ansible/ansible/pull/75863)
+      - The collection loader now reports a Python warning if an attempt is made to
+        install the Ansible collection loader a second time. Previously this condition
+        was reported using an Ansible warning.
+      - '``ansible-galaxy collection [install|verify]`` - allow user-provided signature
+        sources in addition to those from the Galaxy server. Each collection entry
+        in a requirements file can specify a ``signatures`` key followed by a list
+        of sources. Collection name(s) provided on the CLI can specify additional
+        signature sources by using the ``--signatures`` CLI option. Signature sources
+        should be URIs that can be opened with ``urllib.request.urlopen()``, such
+        as "https://example.com/path/to/detached_signature.asc" or "file:///path/to/detached_signature.asc".
+        The ``--keyring`` option must be specified if signature sources are provided.'
+      - '``ansible-galaxy collection [install|verify]`` - use gpg to verify the authenticity
+        of the signed ``MANIFEST.json`` with ASCII armored detached signatures provided
+        by the Galaxy server. The keyring (which is not managed by ``ansible-galaxy``)
+        must be provided with the ``--keyring`` option to use signature verification.
+        If no ``--keyring`` is specified and the collection to ``install|verify``
+        has associated detached signatures on the Galaxy server, a warning is provided.'
+      - '``ansible-galaxy collection install`` - Add a global configuration to modify
+        the required number of signatures that must verify the authenticity of the
+        collection. By default, the number of required successful signatures is 1.
+        Set this option to ``all`` to require all signatures verify the collection.
+        To ensure signature verification fails if there are no valid signatures, prepend
+        the value with ''+'', such as ``+all`` or ``+1``.'
+      - '``ansible-galaxy collection install`` - Add a global ignore list for gpg
+        signature errors. This can be used to ignore certain signatures when the number
+        of required successful signatures is all. When the required number of successful
+        signatures is a positive integer, the only effect this has is to display fewer
+        errors to the user on failure (success is determined by having the minimum
+        number of successful signatures, in which case all errors are disregarded).'
+      - '``ansible-galaxy collection install`` - Add a global toggle to turn off GPG
+        signature verification.'
+      - '``ansible-galaxy collection install`` - Store Galaxy server metadata alongside
+        installed collections for provenance. Signatures obtained from the Galaxy
+        server can be used for offline verification with ``ansible-galaxy collection
+        verify --offline``.'
+      - ansible-console - Provide a  way to customize the stdout callback
+      - ansible-core modules - Remove unused Python shebangs from built-in modules.
+      - ansible-doc metadata dump - add option ``--no-fail-on-errors`` which allows
+        to not fail the ansible-doc invocation when errors happen during docs parsing
+        or processing. Instead they are reported in the JSON result in an ``error``
+        key for the affected plugins (https://github.com/ansible/ansible/pull/77035).
+      - ansible-galaxy - the option to skip certificate verification now also applies
+        when cloning via SCM (git/hg) (https://github.com/ansible/ansible/issues/41077)
+      - ansible-test - Accept new-style Python modules without a shebang.
+      - ansible-test - Add ``--version`` support to show the ansible-core version.
+      - ansible-test - Add support for ``rhel/8.5`` remote instances.
+      - ansible-test - Add support for remote testing of FreeBSD 12.3.
+      - ansible-test - Add support for running container tests with ``podman remote``
+        (https://github.com/ansible/ansible/pull/75753)
+      - ansible-test - Added the ``fedora35`` test container.
+      - ansible-test - Change the maximum number of open files in a test container
+        from the default to ``10240``.
+      - ansible-test - Declare public dependencies of ansible-core and use to limit
+        unguarded imports in plugins.
+      - ansible-test - Importing ``distutils`` now results in an error.
+      - ansible-test - Installation of ``cryptography`` is no longer version constrained
+        when ``openssl`` 1.1.0 or later is installed.
+      - ansible-test - Miscellaneous code cleanup and type hint fixes.
+      - ansible-test - PowerShell in the ``base`` and ``default`` containers has been
+        upgraded to version 7.1.4.
+      - ansible-test - Remove RHEL 8.4 remote (``rhel/8.4``) support.
+      - ansible-test - Remove ``idna`` constraint.
+      - ansible-test - Remove obsolete ``MAXFD`` display.
+      - ansible-test - Remove obsolete constraints for Python 2.6.
+      - ansible-test - Remove support for FreeBSD 12.2 remote provisioning.
+      - ansible-test - Remove support for macOS 11.1 remote provisioning.
+      - ansible-test - Remove support for provisioning remote AIX instances.
+      - ansible-test - Remove the ``centos8`` test container since CentOS 8 will reach
+        end-of-life soon.
+      - ansible-test - Remove the ``fedora33`` test container since Fedora 33 will
+        reach end-of-life soon.
+      - ansible-test - Remove unused Python 2.x compatibility code.
+      - ansible-test - Removed support for Sherlock from the Azure provisioning plugin.
+      - ansible-test - Removed used ``MarkupSafe`` constraint for Python 3.5 and earlier.
+      - ansible-test - Requirements for the plugin import test are now frozen.
+      - ansible-test - Shellcheck in the ``base`` and ``default`` containers has been
+        upgraded to version 0.7.0.
+      - ansible-test - Stop early with an error if the current working directory contains
+        an invalid collection namespace or name.
+      - ansible-test - The ``--help`` option is now available when an unsupported
+        cwd is in use.
+      - ansible-test - The ``--help`` output now shows the same instructions about
+        cwd as would be shown in error messages if the cwd is unsupported.
+      - ansible-test - The ``pip`` and ``wheel`` packages are removed from all sanity
+        test virtual environments after installation completes to reduce their size.
+        Previously they were only removed from the environments used for the ``import``
+        sanity test.
+      - ansible-test - The explanation about cwd usage has been improved to explain
+        more clearly what is required.
+      - ansible-test - The hash for all managed sanity test virtual environments has
+        changed. Containers that include ``ansible-test sanity --prime-venvs`` will
+        need to be rebuilt to continue using primed virtual environments.
+      - ansible-test - Update ``base`` container to version 2.1.0.
+      - ansible-test - Update ``base`` container to version 2.2.0.
+      - ansible-test - Update ``default`` containers to version 5.2.0.
+      - ansible-test - Update ``default`` containers to version 5.4.0.
+      - ansible-test - Update ``default`` containers to version 5.5.0.
+      - ansible-test - Update ``default`` containers to version 5.6.2.
+      - ansible-test - Update ``default`` containers to version 5.7.0.
+      - ansible-test - Update ``default`` containers to version 5.8.0.
+      - ansible-test - Update ``pip`` used to bootstrap remote FreeBSD instances from
+        version 20.3.4 to 21.3.1.
+      - ansible-test - Update sanity test requirements.
+      - ansible-test - Update the NIOS test plugin container to version 1.4.0.
+      - ansible-test - Update the ``alpine`` container to version 3.3.0. This updates
+        the base image from 3.14.2 to 3.15.0, which includes support for installing
+        binary wheels using pip.
+      - ansible-test - Update the ``base`` and ``default`` containers from Python
+        3.10.0rc2 to 3.10.0.
+      - ansible-test - Update the ``base`` and ``default`` containers from a Ubuntu
+        18.04 to Ubuntu 20.04 base image.
+      - ansible-test - Update the ``default`` containers to version 5.1.0.
+      - ansible-test - Update the ``galaxy`` test plugin to get its container from
+        a copy on quay.io.
+      - ansible-test - Update the ``openshift`` test plugin to get its container from
+        a copy on quay.io.
+      - ansible-test - Use Python 3.10 as the default Python version for the ``base``
+        and ``default`` containers.
+      - ansible-test - add macOS 12.0 as a remote target (https://github.com/ansible/ansible/pull/76328)
+      - ansible-test - handle JSON decode error gracefully in podman environment.
+      - ansible-test pslint - Added the `AvoidLongLines <https://github.com/PowerShell/PSScriptAnalyzer/blob/master/docs/Rules/AvoidLongLines.md>`_
+        rule set to a length of 160.
+      - ansible-test pslint - Added the `PlaceCloseBrace <https://github.com/PowerShell/PSScriptAnalyzer/blob/master/docs/Rules/PlaceCloseBrace.md>`_
+        rule set to enforce close braces on a newline.
+      - ansible-test pslint - Added the `PlaceOpenBrace <https://github.com/PowerShell/PSScriptAnalyzer/blob/master/docs/Rules/PlaceOpenBrace.md>`_
+        rule set to enforce open braces on the same line and a subsequent newline.
+      - ansible-test pslint - Added the `UseConsistentIndentation <https://github.com/PowerShell/PSScriptAnalyzer/blob/master/docs/Rules/UseConsistentIndentation.md>`_
+        rule to enforce indentation is done with 4 spaces.
+      - ansible-test pslint - Added the `UseConsistentWhitespace <https://github.com/PowerShell/PSScriptAnalyzer/blob/master/docs/Rules/UseConsistentWhitespace.md>`_
+        rule to enforce whitespace consistency in PowerShell.
+      - ansible-test pslint - Updated ``PowerShellScriptAnalyzer`` to 1.20.0
+      - ansible-test sanity validate-modules - the validate-modules sanity test now
+        also checks the documentation of documentable plugin types (https://github.com/ansible/ansible/pull/71734).
+      - ansible-test validate-modules sanity test - add more schema checks to improve
+        quality of plugin documentation (https://github.com/ansible/ansible/pull/77268).
+      - ansible-test validate_modules - allow ``choices`` for return values (https://github.com/ansible/ansible/pull/76009).
+      - apt - Add support for using ">=" in package version number matching.
+      - apt - Adds APT option ``--allow-change-held-packages`` as module parameter
+        ``allow_change_held_packages`` to allow APT up- or downgrading a package which
+        is on APTs hold list (https://github.com/ansible/ansible/issues/65325)
+      - auto inventory plugin will now give plugin loading information on verbose
+        output
+      - callbacks - Add result serialization format options to ``_dump_results`` allowing
+        plugins such as the ``default`` callback to emit ``YAML`` serialized task
+        results in addition to ``JSON``
+      - dnf - add more specific error message for GPG validation (https://github.com/ansible/ansible/issues/76192)
+      - env lookup, add default option
+      - facts - report prefix length for IPv4 addresses in Linux network facts.
+      - get_parsable_locale now logs result when in debug mode.
+      - git - display the destination directory path in error msg when local_mods
+        detects local modifications conflict so that users see the exact location
+      - iptables - add the ``chain_management`` parameter that controls iptables chain
+        creation and deletion
+      - jinja2_native - keep same behavior on Python 3.10.
+      - junit callback - Add support for replacing the directory portion of out-of-tree
+        relative task paths with a placeholder.
+      - k8s - scenario guides for kubernetes migrated to ``kubernetes.core`` collection.
+      - module_utils.distro - Add missing ``typing`` import from original code.
+      - package_facts - add pkg_info support for OpenBSD and NetBSD (https://github.com/ansible/ansible/pull/76580)
+      - services_facts - Add support for openrc (https://github.com/ansible/ansible/pull/76373).
+      - setting DEFAULT_FACT_PATH is being deprecated in favor of the generic module_defaults
+        keyword
+      - uri - Avoid reading the response body when not needed
+      - uri - Eliminate multiple requests to determine the final URL for file naming
+        with ``dest``
+      - validate-modules - do some basic validation on the ``M(...)``, ``U(...)``,
+        ``L(..., ...)`` and ``R(..., ...)`` documentation markups (https://github.com/ansible/ansible/pull/76262).
+      - vmware - migrated vmware scenario guides to `community.vmware` repo.
+      - yum, dnf - add sslverify option to temporarily disable certificate validation
+        for a repository
+      release_summary: '| Release Date: 2022-04-11
+
+        | `Porting Guide <https://docs.ansible.com/ansible/devel/porting_guides.html>`__
+
+        '
+      removed_features:
+      - Remove deprecated ``Templar.set_available_variables()`` method (https://github.com/ansible/ansible/issues/75828)
+      - cli - remove deprecated ability to set verbosity before the sub-command (https://github.com/ansible/ansible/issues/75823)
+      - copy - remove deprecated ``thirsty`` alias (https://github.com/ansible/ansible/issues/75824)
+      - psrp - Removed fallback on ``put_file`` with older ``pypsrp`` versions. Users
+        must have at least ``pypsrp>=0.4.0``.
+      - url_argument_spec - remove deprecated ``thirsty`` alias for ``get_url`` and
+        ``uri`` modules (https://github.com/ansible/ansible/issues/75825, https://github.com/ansible/ansible/issues/75826)
+      security_fixes:
+      - 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)
+    codename: Nobody's Fault but Mine
+    fragments:
+    - ' 75876-fix-parsing-of-device-serial-number-for-rhel-8.yaml'
+    - 47277-fails-to-deploy-deb-when-has-no-architecture-attribute.yml
+    - 50771-uri-improvements.yml
+    - 50897-include_role-any_errors_fatal.yaml
+    - 67616-galaxy-scm-cloning-ignore-certs.yml
+    - 69776-add-aix-root-ca-certs-paths.yml
+    - 71627-add_host-group_by-fix-changed_when-in-loop.yml
+    - 71734-validate-plugins.yml
+    - 72405-git-module-local_mods-show-conflict-destination-directory.yml
+    - 72592-catch-broken-cowsay.yaml
+    - 73024-unarchive-apply-permissions-top-folder.yml
+    - 73629_allow-change-held-packages.yml
+    - 73657-include-parser-error-fail.yml
+    - 74127-bad-filter-2.yml
+    - 74349-improve-docker-detection.yml
+    - 74416-PlayIterator-_host_states-setters.yml
+    - 74511-PlayIterator-states-enums.yml
+    - 75002-apt_min_version.yml
+    - 75015-ca-path-bundle.yml
+    - 75017-user-password-expiry.yml
+    - 75101-ansible-vault-encrypt_string-output-file.yml
+    - 75538-systemd-alias-check.yml
+    - 75540-warn-invalid-configured-vault-secret-files.yaml
+    - 75560-interp-discovery-family-fallback.yml
+    - 75635-fix-role-argspec-suboption-validation.yml
+    - 75642-free-strat-fix-executing-includes.yml
+    - 75671-ansible-doc-ignore-deprecations.yml
+    - 75823-cli-remove-deprecated-verbosity-before-sub-cmd.yml
+    - 75824-copy-remove-deprecated-thirsty-alias.yml
+    - 75825-75826-get_url-uri-remove-deprecated-thirsty-alias.yml
+    - 75828-remove-deprecated-set_available_variables.yml
+    - 75845-ansible-galaxy-support-collection-skeleton.yml
+    - 75863-start-move-away-six.yml
+    - 75881-jinja2-3-min.yml
+    - 76009-validate-modules-choices-return-value.yml
+    - 76011-loop-variable-in-use-warning.yml
+    - 76049-task-debugger-run_once.yml
+    - 76069-fix-unarchive-file-listing-in-zip.yaml
+    - 76108-fix-ansible-galaxy-collection-verify-help.yaml
+    - 76124-hostname-debianstrategy.yml
+    - 76192-dnf-specific-gpg-error.yml
+    - 76225-update-collection-loader-for-python3.yaml
+    - 76235-fix-ansible-doc-builtin-legacy.yml
+    - 76262-validate-modules-validate-markup.yml
+    - 76316-galaxy-install-role-inaccessible-dir-fix.yml
+    - 76336-yum-makecache-fast.yml
+    - 76343-tencentos-dnf.yml
+    - 76353-fix-check-mode-skipping.yaml
+    - 76356-yumdnf-sslverify.yml
+    - 76365-unarchive-include-stderr-in-error-message.yml
+    - 76373-add-openrc-support-to-service_facts.yaml
+    - 76375-fix-module-logging-WSL2.yml
+    - 76378-iptables-chain-management.yml
+    - 76379-set-finalize-on-new-env.yml
+    - 76386-httperror-no-fp.yml
+    - 76433-get_url-document-check_mode.yml
+    - 76453-indirect-systemd-status.yml
+    - 76530-connection-password-file-tb-fix.yml
+    - 76542-fix-unarchive-on-nenglish-locales.yml
+    - 76579-fix-ansible-galaxy-collection-version-error.yml
+    - 76580-add-pkg_info-support-to-package_facts.yml
+    - 76610-empty-template-none.yml
+    - 76672-fix-end_play-multiple_plays.yml
+    - 76681-ansible-galaxy-add-gpg-signature-verification.yaml
+    - 76690-fix-ansible-galaxy-collection-verify-modified-content.yaml
+    - 76729-async-callback-perf.yml
+    - 76735-ansible-galaxy-fix-ignore-certs.yaml
+    - 76751-facts-check-datafile-before-close.yml
+    - 76769-inventory-constructable-disable-lookups.yml
+    - 76782-fqcn-compare-lockstep-strategies.yml
+    - 76792-hostname-all-systemd.yml
+    - 76840-added-restart-to-the-argument-condition-for-AIX.yml
+    - 76877-added-sleep-to-the-service-restart-for-AIX.yml
+    - 76924-powershell-ansible.basic-support-non-windows.yml
+    - 76958-hostname-systemd-nm.yaml
+    - 77004-restore-missing-default.yml
+    - 77010-dnf-ensure-releasever-string.yml
+    - 77035-ansible-doc-metadata-dump-errors.yml
+    - 77050-add-pkg-mgr-support-for-al2022.yaml
+    - 77074-hostname-fix-typeerror-in-filestrategy.yml
+    - 77086-correct-pylint-symbols.yml
+    - 77108_params_blank.yml
+    - 77136-first_found-spaces-in-names.yml
+    - 77180-fix-fish-env-setup-script.yml
+    - 77193-linux-networking-facts-Provide-IPv4-prefix.yml
+    - 77210-fix-collection-filter-test-redirects.yml
+    - 77268-validate-plugins.yml
+    - 77271-unarchive.yml
+    - 77275-add-support-for-deepin-distro-info-detection.yaml
+    - 77320-python-2.yml
+    - 77368-rhel-os-family-compat.yaml
+    - 77465-ansible-test-compile-crash.yml
+    - 77472-ansible-test-network-disconnect-warning.yml
+    - 77493-ansible-galaxy-find-git-executable-before-using.yaml
+    - ModuleUtils.SID-long-username.yml
+    - action-plugin-arg-spec.yml
+    - ansible-console-callback.yaml
+    - ansible-core-python-2.6.yaml
+    - ansible-module-shebangs.yml
+    - ansible-test-alpine3-update.yaml
+    - ansible-test-azure-sherlock.yml
+    - ansible-test-bootstrap-pip.yml
+    - ansible-test-ci-files.yaml
+    - ansible-test-code-cleanup.yml
+    - ansible-test-collection-identifier.yml
+    - ansible-test-constraints-cleanup.yaml
+    - ansible-test-constraints.yaml
+    - ansible-test-container-images.yml
+    - ansible-test-container-removal.yml
+    - ansible-test-default-base-containers-base-update.yaml
+    - ansible-test-default-base-containers-python-3.10.yaml
+    - ansible-test-default-container-update-5.2.0.yaml
+    - ansible-test-default-container-update-5.4.0.yaml
+    - ansible-test-default-container-update-5.5.0.yaml
+    - ansible-test-default-container-update-5.6.2.yaml
+    - ansible-test-default-container-update-5.7.0.yaml
+    - ansible-test-default-container-update-5.8.0.yaml
+    - ansible-test-default-container-update.yaml
+    - ansible-test-delegation-inventory.yaml
+    - ansible-test-delegation-pythonpath.yml
+    - ansible-test-distro-containers-3.1.0.yaml
+    - ansible-test-docker-ulimit.yml
+    - ansible-test-fedora35.yml
+    - ansible-test-fix-type-hints.yml
+    - ansible-test-fix-typo-validate-modules.yaml
+    - ansible-test-freebsd-12.3.yaml
+    - ansible-test-help-cwd.yml
+    - ansible-test-import-collections.yml
+    - ansible-test-import-distutils.yaml
+    - ansible-test-inventory-path.yaml
+    - ansible-test-inventory-ssh-key.yml
+    - ansible-test-junit-relative-paths.yml
+    - ansible-test-links.yml
+    - ansible-test-managed-venv.yml
+    - ansible-test-maxfd.yaml
+    - ansible-test-nios-container.yml
+    - ansible-test-paramiko-constraint.yaml
+    - ansible-test-plugin-loading.yml
+    - ansible-test-podman-remote.yaml
+    - ansible-test-podman-support-containers.yaml
+    - ansible-test-powershell-coverage-all.yaml
+    - ansible-test-pyopenssl.yaml
+    - ansible-test-pytest-forked.yml
+    - ansible-test-pytest-rootdir.yml
+    - ansible-test-python-2.6.yaml
+    - ansible-test-relocate-constants.yaml
+    - ansible-test-remote-cleanup.yaml
+    - ansible-test-remove-aix-provisioning.yaml
+    - ansible-test-requirements-target.yaml
+    - ansible-test-rhel-8.4.yml
+    - ansible-test-rhel85.yaml
+    - ansible-test-sanity-import-loader.yml
+    - ansible-test-sanity-import-no-pip.yml
+    - ansible-test-sanity-import.yml
+    - ansible-test-sanity-requirements-update.yaml
+    - ansible-test-sanity-vendoring.yml
+    - ansible-test-target-filter.yml
+    - ansible-test-unsupported-directory-traceback.yaml
+    - ansible-test-validate-modules-collection-loader.yml
+    - ansible-test-validate-modules-no-callable.yml
+    - ansible-test-venv-real-prefix.yaml
+    - ansible-test-windows-default.yaml
+    - ansible-test-yaml-import.yaml
+    - ansible_galaxy_timeout.yml
+    - ansible_test.yml
+    - auto_squeal.yml
+    - avoid-set_options-leak.yaml
+    - clarify-unroll.yml
+    - clean_facts_values.yml
+    - compat-typing.yml
+    - config_fix_terms.yml
+    - default-callback-result-format.yml
+    - deprecate_default_fact_path_setting.yml
+    - deprecate_scp_if_ssh.yml
+    - distro-module_utils-typing.yml
+    - drop-target-2.6-support.yml
+    - environment-concat.yml
+    - evn_default.yml
+    - file_modification_times_support_check_mode.yml
+    - finalize-not-in-globals.yml
+    - fix_block_var_inh.yml
+    - fix_fax_delegation_loops.yml
+    - fix_sudo_flag_mangling.yml
+    - fqn-module-cache.yml
+    - galaxy-build-files-ignore.yml
+    - galaxy-import-level-fix.yml
+    - gather_facts_collections.yml
+    - git_fixes.yml
+    - handle_connection_cornercase.yml
+    - include_vars_failed.yml
+    - inventory_manager_flush_cache.yml
+    - jinja2_native-literal_eval-py310.yml
+    - json_filter_fix.yml
+    - junit-callback-task-path-unicode.yml
+    - log_locale_selection_results.yml
+    - macos12-ci-image.yml
+    - migrated_k8s_scenario_guides.yml
+    - modernize-install.yaml
+    - module_utils-yaml-fix.yml
+    - more_targeted_attribute_errors.yml
+    - nativejinjatext-yaml-representer.yml
+    - nativejinjaunsafetext-yaml-representer.yml
+    - openEuler_hostname.yml
+    - pslint-sanity-warning.yml
+    - psrp-put_file-dep.yaml
+    - pull_fix_limit.yml
+    - pwsh-pssa-update.yml
+    - reduce-playiterator-iterations.yml
+    - replace-rc-return-values.yml
+    - restore_python_shebang_adherence.yml
+    - runc_command_exception_toggle.yml
+    - service_facts_warnings.yml
+    - set_fact_delegation.yml
+    - ssh_debug_noparse.yml
+    - ssh_quote_cp.yml
+    - ssh_use_right_host.yml
+    - support_eurolinux.yml
+    - templar-correct-environment_class-template.yml
+    - templating-safe-eval-replaced-native_environment.yml
+    - user_mac.yaml
+    - v2.13.0-initial-commit.yaml
+    - v2.13.0b0_summary.yaml
+    - vmware_sceanrio.yml
+    - win_LinkUtil-ignore-LIB.yml
+    - winrm-kinit-path.yml
+    release_date: '2022-04-11'
+  2.13.0b1:
+    changes:
+      bugfixes:
+      - ansible - Exclude Python 2.6 from Python interpreter discovery.
+      - arg_spec - Fix incorrect ``no_log`` warning when a parameter alias is used
+        (https://github.com/ansible/ansible/pull/77576)
+      - variablemanager, more efficient read of vars files
+      minor_changes:
+      - ansible-test - Update ``default`` containers to version 5.9.0.
+      release_summary: '| Release Date: 2022-04-25
+
+        | `Porting Guide <https://docs.ansible.com/ansible/devel/porting_guides.html>`__
+
+        '
+    codename: Nobody's Fault but Mine
+    fragments:
+    - 77576-arg_spec-no_log-aliases.yml
+    - ansible-test-default-container-update-5.9.0.yaml
+    - python-2.6-discovery.yml
+    - v2.13.0b1_summary.yaml
+    - vm_more_efficient.yml
+    release_date: '2022-04-25'
+  2.13.0rc1:
+    changes:
+      bugfixes:
+      - Prevent losing unsafe on results returned from lookups (https://github.com/ansible/ansible/issues/77535)
+      release_summary: '| Release Date: 2022-05-02
+
+        | `Porting Guide <https://docs.ansible.com/ansible/devel/porting_guides.html>`__
+
+        '
+    codename: Nobody's Fault but Mine
+    fragments:
+    - 77535-prevent-losing-unsafe-lookups.yml
+    - v2.13.0rc1_summary.yaml
+    release_date: '2022-05-02'
+  2.13.1:
+    changes:
+      release_summary: '| Release Date: 2022-06-20
+
+        | `Porting Guide <https://docs.ansible.com/ansible/devel/porting_guides.html>`__
+
+        '
+    codename: Nobody's Fault but Mine
+    fragments:
+    - v2.13.1_summary.yaml
+    release_date: '2022-06-20'
+  2.13.1rc1:
+    changes:
+      bugfixes:
+      - Add PyYAML >= 5.1 as a dependency of ansible-core to be compatible with Python
+        3.8+.
+      - ansible-config dump - Only display plugin type headers when plugin options
+        are changed if --only-changed is specified.
+      - ansible-galaxy - handle unsupported versions of resolvelib gracefully.
+      - ansible-test - Fix internal validation of remote completion configuration.
+      - ansible-test - Prevent ``--target-`` prefixed options for the ``shell`` command
+        from being combined with legacy environment options.
+      - ansible-test - Sanity test output with the ``--lint`` option is no longer
+        mixed in with bootstrapping output.
+      - ansible-test - Subprocesses are now isolated from the stdin, stdout and stderr
+        of ansible-test. This avoids issues with subprocesses tampering with the file
+        descriptors, such as SSH making them non-blocking. As a result of this change,
+        subprocess output from unit and integration tests on stderr now go to stdout.
+      - ansible-test - Subprocesses no longer have access to the TTY ansible-test
+        is connected to, if any. This maintains consistent behavior between local
+        testing and CI systems, which typically do not provide a TTY. Tests which
+        require a TTY should use pexpect or another mechanism to create a PTY.
+      - apt module now correctly handles virtual packages.
+      - lookup plugin - catch KeyError when lookup returns dictionary (https://github.com/ansible/ansible/pull/77789).
+      - pip - fix cases where resolution of pip Python module fails when importlib.util
+        has not already been imported
+      - plugin loader - Sort results when fuzzy matching plugin names (https://github.com/ansible/ansible/issues/77966).
+      - plugin loader will now load config data for plugin by name instead of by file
+        to avoid issues with the same file being loaded under different names (fqcn
+        + short name).
+      - psrp connection now handles default to inventory_hostname correctly.
+      - winrm connection now handles default to inventory_hostname correctly.
+      minor_changes:
+      - "Add an 'action_plugin' field for modules in runtime.yml plugin_routing.\n\nThis
+        fixes module_defaults by supporting modules-as-redirected-actions\nwithout
+        redirecting module_defaults entries to the common action.\n\n.. code: yaml\n\n
+        \  plugin_routing:\n     action:\n       facts:\n         redirect: ns.coll.eos\n
+        \      command:\n         redirect: ns.coll.eos\n     modules:\n       facts:\n
+        \        redirect: ns.coll.eos_facts\n       command:\n         redirect:
+        ns.coll.eos_command\n\nWith the runtime.yml above for ns.coll, a task such
+        as\n\n.. code: yaml\n\n   - hosts: all\n     module_defaults:\n       ns.coll.eos_facts:
+        {'valid_for_eos_facts': 'value'}\n       ns.coll.eos_command: {'not_valid_for_eos_facts':
+        'value'}\n     tasks:\n       - ns.coll.facts:\n\nwill end up with defaults
+        for eos_facts and eos_command\nsince both modules redirect to the same action.\n\nTo
+        select an action plugin for a module without merging\nmodule_defaults, define
+        an action_plugin field for the resolved\nmodule in the runtime.yml.\n\n..
+        code: yaml\n\n   plugin_routing:\n     modules:\n       facts:\n         redirect:
+        ns.coll.eos_facts\n         action_plugin: ns.coll.eos\n       command:\n
+        \        redirect: ns.coll.eos_command\n         action_plugin: ns.coll.eos\n\nThe
+        action_plugin field can be a redirected action plugin, as\nit is resolved
+        normally.\n\nUsing the modified runtime.yml, the example task will only use\nthe
+        ns.coll.eos_facts defaults.\n"
+      - ansible-galaxy - Support resolvelib versions 0.6.x, 0.7.x, and 0.8.x. The
+        full range of supported versions is now >= 0.5.3, < 0.9.0.
+      - ansible-test - Add RHEL 9.0 remote support.
+      - ansible-test - Add support for Ubuntu VMs using the ``--remote`` option.
+      - ansible-test - Add support for exporting inventory with ``ansible-test shell
+        --export {path}``.
+      - ansible-test - Add support for multi-arch remotes.
+      - ansible-test - Add support for running non-interactive commands with ``ansible-test
+        shell``.
+      - ansible-test - Avoid using the ``mock_use_standalone_module`` setting for
+        unit tests running on Python 3.8 or later.
+      - ansible-test - Blocking mode is now enforced for stdin, stdout and stderr.
+        If any of these are non-blocking then ansible-test will exit during startup
+        with an error.
+      - ansible-test - Improve consistency of output messages by using stdout or stderr
+        for most output, but not both.
+      - ansible-test - The ``shell`` command can be used outside a collection if no
+        controller delegation is required.
+      release_summary: '| Release Date: 2022-06-13
+
+        | `Porting Guide <https://docs.ansible.com/ansible/devel/porting_guides.html>`__
+
+        '
+    codename: Nobody's Fault but Mine
+    fragments:
+    - 77265-module_defaults-with-modules-as-redirected-actions.yaml
+    - 77630-ansible-galaxy-fix-unsupported-resolvelib-version.yml
+    - 77649-support-recent-resolvelib-versions.yml
+    - 77789-catch-keyerror-lookup-dict.yml
+    - 77898-ansible-config-dump-only-changed-all-types.yml
+    - 77936-add-pyyaml-version.yml
+    - ansible-test-ansible-core-mock.yml
+    - ansible-test-multi-arch-remotes.yml
+    - ansible-test-remote-completion-validation.yml
+    - ansible-test-rhel-9.yaml
+    - ansible-test-shell-features.yml
+    - ansible-test-subprocess-isolation.yml
+    - ansible-test-target-options.yml
+    - ansible-test-ubuntu-remote.yml
+    - apt_virtual_fix.yml
+    - config_load_by_name.yml
+    - pip-lazy-import.yml
+    - plugin-loader-deterministic-fuzzy-match.yml
+    - v2.13.1rc1_summary.yaml
+    - windows_conn_option_fix.yml
+    release_date: '2022-06-13'
+  2.13.2:
+    changes:
+      release_summary: '| Release Date: 2022-07-18
+
+        | `Porting Guide <https://docs.ansible.com/ansible/devel/porting_guides.html>`__
+
+        '
+    codename: Nobody's Fault but Mine
+    fragments:
+    - v2.13.2_summary.yaml
+    release_date: '2022-07-18'
+  2.13.2rc1:
+    changes:
+      bugfixes:
+      - Move undefined check from concat to finalize (https://github.com/ansible/ansible/issues/78156)
+      - ansible-doc - no longer list module and plugin aliases that are created with
+        symlinks (https://github.com/ansible/ansible/pull/78137).
+      - ansible-doc - when listing modules in collections, proceed recursively. This
+        fixes module listing for community.general 5.x.y and community.network 4.x.y
+        (https://github.com/ansible/ansible/pull/78137).
+      - ansible-doc will not add 'website for' in ":ref:" substitutions as it made
+        them confusing.
+      - file backed cache plugins now handle concurrent access by making atomic updates
+        to the files.
+      - password lookup does not ignore k=v arguments anymore.
+      - user - Fix error "Permission denied" in user module while generating SSH keys
+        (https://github.com/ansible/ansible/issues/78017).
+      minor_changes:
+      - ansible-test - An improved error message is shown when the download of a pip
+        bootstrap script fails. The download now uses ``urllib2`` instead of ``urllib``
+        on Python 2.
+      release_summary: '| Release Date: 2022-07-11
+
+        | `Porting Guide <https://docs.ansible.com/ansible/devel/porting_guides.html>`__
+
+        '
+    codename: Nobody's Fault but Mine
+    fragments:
+    - 78137-ansible-doc-list-modules-recursively.yml
+    - 78156-undefined-check-in-finalize.yml
+    - ansible-test-pip-bootstrap.yml
+    - atomic_cache_files.yml
+    - fix_adoc_text.yml
+    - password_lookup_fix.yml
+    - permission-denied-spwd-module.yml
+    - v2.13.2rc1_summary.yaml
+    release_date: '2022-07-11'

changelogs/fragments/77265-module_defaults-with-modules-as-redirected-actions.yaml

@@ -0,0 +1,55 @@
+minor_changes:
+- |
+  Add an 'action_plugin' field for modules in runtime.yml plugin_routing.
+
+  This fixes module_defaults by supporting modules-as-redirected-actions
+  without redirecting module_defaults entries to the common action.
+
+  .. code: yaml
+
+     plugin_routing:
+       action:
+         facts:
+           redirect: ns.coll.eos
+         command:
+           redirect: ns.coll.eos
+       modules:
+         facts:
+           redirect: ns.coll.eos_facts
+         command:
+           redirect: ns.coll.eos_command
+
+  With the runtime.yml above for ns.coll, a task such as
+
+  .. code: yaml
+
+     - hosts: all
+       module_defaults:
+         ns.coll.eos_facts: {'valid_for_eos_facts': 'value'}
+         ns.coll.eos_command: {'not_valid_for_eos_facts': 'value'}
+       tasks:
+         - ns.coll.facts:
+
+  will end up with defaults for eos_facts and eos_command
+  since both modules redirect to the same action.
+
+  To select an action plugin for a module without merging
+  module_defaults, define an action_plugin field for the resolved
+  module in the runtime.yml.
+
+  .. code: yaml
+
+     plugin_routing:
+       modules:
+         facts:
+           redirect: ns.coll.eos_facts
+           action_plugin: ns.coll.eos
+         command:
+           redirect: ns.coll.eos_command
+           action_plugin: ns.coll.eos
+
+  The action_plugin field can be a redirected action plugin, as
+  it is resolved normally.
+
+  Using the modified runtime.yml, the example task will only use
+  the ns.coll.eos_facts defaults.

changelogs/fragments/77465-ansible-test-compile-crash.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - "ansible-test compile sanity test - do not crash if a column could not be determined for an error (https://github.com/ansible/ansible/pull/77465)."

changelogs/fragments/77472-ansible-test-network-disconnect-warning.yml

@@ -0,0 +1,3 @@
+bugfixes:
+- ansible-test - Don't fail if network cannot be disconnected
+  (https://github.com/ansible/ansible/pull/77472)

changelogs/fragments/77493-ansible-galaxy-find-git-executable-before-using.yaml

@@ -0,0 +1,2 @@
+bugfixes:
+  - Fix traceback when installing a collection from a git repository and git is not installed (https://github.com/ansible/ansible/issues/77479).

changelogs/fragments/77535-prevent-losing-unsafe-lookups.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - Prevent losing unsafe on results returned from lookups (https://github.com/ansible/ansible/issues/77535)

changelogs/fragments/77576-arg_spec-no_log-aliases.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - arg_spec - Fix incorrect ``no_log`` warning when a parameter alias is used (https://github.com/ansible/ansible/pull/77576)

changelogs/fragments/77630-ansible-galaxy-fix-unsupported-resolvelib-version.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - ansible-galaxy - handle unsupported versions of resolvelib gracefully.

changelogs/fragments/77649-support-recent-resolvelib-versions.yml

@@ -0,0 +1,3 @@
+minor_changes:
+  - ansible-galaxy - Support resolvelib versions 0.6.x, 0.7.x, and 0.8.x.
+    The full range of supported versions is now >= 0.5.3, < 0.9.0.

changelogs/fragments/77789-catch-keyerror-lookup-dict.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - lookup plugin - catch KeyError when lookup returns dictionary (https://github.com/ansible/ansible/pull/77789).

changelogs/fragments/77898-ansible-config-dump-only-changed-all-types.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - ansible-config dump - Only display plugin type headers when plugin options are changed if --only-changed is specified.

changelogs/fragments/77936-add-pyyaml-version.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - Add PyYAML >= 5.1 as a dependency of ansible-core to be compatible with Python 3.8+.

changelogs/fragments/78137-ansible-doc-list-modules-recursively.yml

@@ -0,0 +1,3 @@
+bugfixes:
+  - "ansible-doc - when listing modules in collections, proceed recursively. This fixes module listing for community.general 5.x.y and community.network 4.x.y (https://github.com/ansible/ansible/pull/78137)."
+  - "ansible-doc - no longer list module and plugin aliases that are created with symlinks (https://github.com/ansible/ansible/pull/78137)."

changelogs/fragments/78156-undefined-check-in-finalize.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - Move undefined check from concat to finalize (https://github.com/ansible/ansible/issues/78156)

changelogs/fragments/ansible-test-ansible-core-mock.yml

@@ -0,0 +1,2 @@
+minor_changes:
+  - ansible-test - Avoid using the ``mock_use_standalone_module`` setting for unit tests running on Python 3.8 or later.

changelogs/fragments/ansible-test-default-container-update-5.9.0.yaml

@@ -0,0 +1,2 @@
+minor_changes:
+  - ansible-test - Update ``default`` containers to version 5.9.0.

changelogs/fragments/ansible-test-multi-arch-remotes.yml

@@ -0,0 +1,2 @@
+minor_changes:
+  - ansible-test - Add support for multi-arch remotes.

changelogs/fragments/ansible-test-pip-bootstrap.yml

@@ -0,0 +1,3 @@
+minor_changes:
+  - ansible-test - An improved error message is shown when the download of a pip bootstrap script fails.
+                   The download now uses ``urllib2`` instead of ``urllib`` on Python 2.

changelogs/fragments/ansible-test-remote-completion-validation.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - ansible-test - Fix internal validation of remote completion configuration.

changelogs/fragments/ansible-test-rhel-9.yaml

@@ -0,0 +1,2 @@
+minor_changes:
+  - ansible-test - Add RHEL 9.0 remote support.

changelogs/fragments/ansible-test-shell-features.yml

@@ -0,0 +1,7 @@
+minor_changes:
+  - ansible-test - Add support for running non-interactive commands with ``ansible-test shell``.
+  - ansible-test - Add support for exporting inventory with ``ansible-test shell --export {path}``.
+  - ansible-test - The ``shell`` command can be used outside a collection if no controller delegation is required.
+  - ansible-test - Improve consistency of output messages by using stdout or stderr for most output, but not both.
+bugfixes:
+  - ansible-test - Sanity test output with the ``--lint`` option is no longer mixed in with bootstrapping output.

changelogs/fragments/ansible-test-subprocess-isolation.yml

@@ -0,0 +1,10 @@
+bugfixes:
+  - ansible-test - Subprocesses are now isolated from the stdin, stdout and stderr of ansible-test.
+                   This avoids issues with subprocesses tampering with the file descriptors, such as SSH making them non-blocking.
+                   As a result of this change, subprocess output from unit and integration tests on stderr now go to stdout.
+  - ansible-test - Subprocesses no longer have access to the TTY ansible-test is connected to, if any.
+                   This maintains consistent behavior between local testing and CI systems, which typically do not provide a TTY.
+                   Tests which require a TTY should use pexpect or another mechanism to create a PTY.
+minor_changes:
+  - ansible-test - Blocking mode is now enforced for stdin, stdout and stderr.
+                   If any of these are non-blocking then ansible-test will exit during startup with an error.

changelogs/fragments/ansible-test-target-filter.yml

@@ -0,0 +1,5 @@
+bugfixes:
+  - ansible-test - Correctly detect when running as the ``root`` user (UID 0) on the origin host.
+                   The result of the detection was incorrectly being inverted.
+  - ansible-test - Fix skipping of tests marked ``needs/root`` on the origin host.
+  - ansible-test - Fix skipping of tests marked ``needs/python`` on the origin host.

changelogs/fragments/ansible-test-target-options.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - ansible-test - Prevent ``--target-`` prefixed options for the ``shell`` command from being combined with legacy environment options.

changelogs/fragments/ansible-test-ubuntu-remote.yml

@@ -0,0 +1,2 @@
+minor_changes:
+  - ansible-test - Add support for Ubuntu VMs using the ``--remote`` option.

changelogs/fragments/apt_virtual_fix.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - apt module now correctly handles virtual packages.

changelogs/fragments/atomic_cache_files.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - file backed cache plugins now handle concurrent access by making atomic updates to the files.

changelogs/fragments/config_load_by_name.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - plugin loader will now load config data for plugin by name instead of by file to avoid issues with the same file being loaded under different names (fqcn + short name).

changelogs/fragments/fix_adoc_text.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - ansible-doc will not add 'website for' in ":ref:" substitutions as it made them confusing.

changelogs/fragments/git_fixes.yml

@@ -1,3 +1,4 @@
 bugfixes:
   - git module no longer uses wrapper script for ssh options.
   - git module is more consistent and clearer about which ssh options are added to git calls.
+  - git module fix docs and proper use of ssh wrapper script and GIT_SSH_COMMAND depending on version.

changelogs/fragments/password_lookup_fix.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - password lookup does not ignore k=v arguments anymore.

changelogs/fragments/permission-denied-spwd-module.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - user - Fix error "Permission denied" in user module while generating SSH keys (https://github.com/ansible/ansible/issues/78017).

changelogs/fragments/pip-lazy-import.yml

@@ -0,0 +1,2 @@
+bugfixes:
+- pip - fix cases where resolution of pip Python module fails when importlib.util has not already been imported

changelogs/fragments/plugin-loader-deterministic-fuzzy-match.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - plugin loader - Sort results when fuzzy matching plugin names (https://github.com/ansible/ansible/issues/77966).

changelogs/fragments/python-2.6-discovery.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - ansible - Exclude Python 2.6 from Python interpreter discovery.

changelogs/fragments/templar-correct-environment_class-template.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - Ensure the correct ``environment_class`` is set on ``AnsibleJ2Template``

changelogs/fragments/v2.13.0_summary.yaml

@@ -0,0 +1,3 @@
+release_summary: |
+   | Release Date: 2022-05-16
+   | `Porting Guide <https://docs.ansible.com/ansible/devel/porting_guides.html>`__

changelogs/fragments/v2.13.0b0_summary.yaml

@@ -0,0 +1,3 @@
+release_summary: |
+   | Release Date: 2022-04-11
+   | `Porting Guide <https://docs.ansible.com/ansible/devel/porting_guides.html>`__

changelogs/fragments/v2.13.0b1_summary.yaml

@@ -0,0 +1,3 @@
+release_summary: |
+   | Release Date: 2022-04-25
+   | `Porting Guide <https://docs.ansible.com/ansible/devel/porting_guides.html>`__

changelogs/fragments/v2.13.0rc1_summary.yaml

@@ -0,0 +1,3 @@
+release_summary: |
+   | Release Date: 2022-05-02
+   | `Porting Guide <https://docs.ansible.com/ansible/devel/porting_guides.html>`__

changelogs/fragments/v2.13.1_summary.yaml

@@ -0,0 +1,3 @@
+release_summary: |
+   | Release Date: 2022-06-20
+   | `Porting Guide <https://docs.ansible.com/ansible/devel/porting_guides.html>`__

changelogs/fragments/v2.13.1rc1_summary.yaml

@@ -0,0 +1,3 @@
+release_summary: |
+   | Release Date: 2022-06-13
+   | `Porting Guide <https://docs.ansible.com/ansible/devel/porting_guides.html>`__

changelogs/fragments/v2.13.2_summary.yaml

@@ -0,0 +1,3 @@
+release_summary: |
+   | Release Date: 2022-07-18
+   | `Porting Guide <https://docs.ansible.com/ansible/devel/porting_guides.html>`__

changelogs/fragments/v2.13.2rc1_summary.yaml

@@ -0,0 +1,3 @@
+release_summary: |
+   | Release Date: 2022-07-11
+   | `Porting Guide <https://docs.ansible.com/ansible/devel/porting_guides.html>`__

changelogs/fragments/vm_more_efficient.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - variablemanager, more efficient read of vars files

changelogs/fragments/windows_conn_option_fix.yml

@@ -0,0 +1,3 @@
+bugfixes:
+  - winrm connection now handles default to inventory_hostname correctly.
+  - psrp connection now handles default to inventory_hostname correctly.

changelogs/fragments/winrm-kinit-path.yml

@@ -0,0 +1,2 @@
+bugfixes:
+- winrm - Ensure ``kinit`` is run with the same ``PATH`` env var as the Ansible process

docs/docsite/.templates/banner.html

@@ -46,7 +46,7 @@
         /* temp extra banner to advertise AnsibeFest2021 */
         banner += extra_banner;
 
-        msg += 'You are reading the latest community version of the Ansible documentation. Red Hat subscribers, select <b>2.9</b> in the version selection to the left for the most recent Red Hat release.';
+        msg += 'You are reading the <b>latest</b> (stable) community version of the Ansible documentation. Red Hat subscribers, select <b>2.9</b> in the version selection to the left for the most recent Red Hat release.';
       } else if (startsWith(current_url_path, "/ansible/2.9/")) {
         msg += 'You are reading the latest Red Hat released version of the Ansible documentation. Community users can use this version, or select <b>latest</b> from the version selector to the left for the most recent community version.';
       } else if (startsWith(current_url_path, "/ansible/devel/")) {
@@ -58,9 +58,9 @@
         msg += 'Please take our <a href="https://www.surveymonkey.co.uk/r/B9V3CDY">Docs survey</a> before December 31 to help us improve Ansible documentation.';
         */
 
-        msg += 'You are reading the <b>devel</b> version of the Ansible documentation - this version is not guaranteed stable. Use the version selection to the left if you want the latest stable released version.';
+        msg += 'You are reading the <b>devel</b> version of the Ansible documentation - this version is not guaranteed stable. Use the version selection to the left if you want the <b>latest</b> (stable) released version.';
       } else {
-        msg += 'You are reading an older version of the Ansible documentation. Use the version selection to the left if you want the latest stable released version.';
+        msg += 'You are reading an older version of the Ansible documentation. Use the version selection to the left if you want the <b>latest</b> (stable) released version.';
       }
       msg += '</p>';
 

docs/docsite/Makefile

@@ -83,6 +83,7 @@ ansible_structure:
 	if python -c "import sys, packaging.version as p; sys.exit(not p.Version('$(MAJOR_VERSION)') >  p.Version('2.10'))" ; then \
 		echo "Creating symlinks in ansible_structure"; \
 		ln -sf ../rst/ansible_index.rst rst/index.rst; \
+		ln -sf ../dev_guide/ansible_index.rst rst/dev_guide/index.rst; \
 		ln -sf ../sphinx_conf/ansible_conf.py rst/conf.py; \
 	else \
 		echo 'Creating symlinks for older ansible in ansible_structure'; \
@@ -94,12 +95,14 @@ ansible_structure:
 core_structure:
 	@echo "Creating symlinks in core_structure"
 	-ln -sf ../rst/core_index.rst rst/index.rst
+	-ln -sf ../dev_guide/core_index.rst rst/dev_guide/index.rst
 	-ln -sf ../sphinx_conf/core_conf.py rst/conf.py
 
 # Symlink the relevant index into place for building core docs
 gettext_structure:
 	@echo "Creating symlinks in gettext_structure"
 	-ln -sf ../rst/core_index.rst rst/index.rst
+	-ln -sf ../rst/dev_guide/core_index.rst rst/dev_guide/index.rst
 	-ln -sf ../sphinx_conf/all_conf.py rst/conf.py
 
 gettext: gettext_structure gettext_generate_rst

docs/docsite/known_good_reqs.txt

@@ -1,19 +0,0 @@
-# pip packages required to build docsite
-# tested Nov 11 2021
-# NOTE - this file must align with CI test for docs-build at
-#    test/sanity/code-smell/docs-build.requirements.txt
-#    test/sanity/code-smell/rstcheck.requirements.txt
-
-antsibull == 0.42.0
-# sphinx 4.2.0 requires docutils < 0.18
-docutils == 0.17.1
-jinja2 == 3.0.3
-pygments == 2.10.0
-pyyaml == 6.0
-resolvelib == 0.5.4
-rstcheck == 3.3.1
-sphinx == 4.2.0
-sphinx-notfound-page == 0.8 # must be >= 0.6
-sphinx-intl == 2.0.1
-sphinx-ansible-theme === 0.9.1
-straight.plugin == 1.5.0 # Needed for hacking/build-ansible.py which is the backend build script

docs/docsite/requirements.txt

@@ -3,7 +3,7 @@
 # if you want known good versions of these dependencies
 # use known_good_reqs.txt instead
 
-antsibull >= 0.42.0
+antsibull-docs >= 1.0.0, < 2.0.0
 docutils
 jinja2
 pygments >= 2.10.0

docs/docsite/rst/ansible_index.rst

@@ -24,6 +24,12 @@ This documentation covers the version of Ansible noted in the upper left corner
 
 Ansible releases a new major release approximately twice a year. The core application evolves somewhat conservatively, valuing simplicity in language design and setup. Contributors develop and change modules and plugins hosted in collections since version 2.10 much more quickly.
 
+.. toctree::
+   :maxdepth: 2
+   :caption: Ansible getting started
+
+   getting_started/index
+
 .. toctree::
    :maxdepth: 2
    :caption: Installation, Upgrade & Configuration

docs/docsite/rst/community/collection_contributors/collection_integration_about.rst

@@ -107,18 +107,18 @@ 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?)
+- 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).
+- 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).
+- 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).
+- 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:
 
@@ -128,7 +128,7 @@ To check a task:
   #. 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: yes`` (if check-mode is supported by the module). Check with other modules that the actual system state has not been changed.
+3. Run the same task with ``check_mode: yes`` 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: yes`` option and check the returned message with the ``assert`` module.
 
 Example:

docs/docsite/rst/community/collection_contributors/collection_integration_add.rst

@@ -108,8 +108,8 @@ Examine the output to see at which step the failure occurred. Investigate the re
 
 8. If the test succeeds, write more tests. Refer to the :ref:`Recommendations on coverage<collection_integration_recommendations>` section for details.
 
-``community.postregesql`` example
-----------------------------------
+``community.postgresql`` example
+--------------------------------
 
 Here is a real example of writing integration tests from scratch for the ``community.postgresql.postgresql_info`` module.
 
@@ -229,7 +229,7 @@ That is enough for our very basic example.
 
 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 (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.
+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:
 

docs/docsite/rst/community/collection_contributors/collection_release_with_branches.rst

@@ -0,0 +1,319 @@
+.. _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. If you are going to release the ``community.general`` and ``community.network`` collections, create new ``backport-X`` and ``needs_backport_to_stable_X`` labels in the corresponding repositories. Copy the styles and descriptions from the corresponding existing labels.
+
+2. 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
+
+
+3. 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, ensure that ``galaxy.yml`` contains the correct version number ``X.0.0``. If not, update it.
+
+7. 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.
+
+
+8. In the ``stable-X`` branch, generate the changelogs:
+
+  .. code-block:: bash
+
+    antsibull-changelog release --cummulative-release
+
+
+9. In the ``stable-X`` branch, verify that the ``CHANGELOG.rst`` looks as expected.
+
+10. 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).
+
+11. 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. 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``.
+
+
+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/Libera.Chat IRC channel <https://docs.ansible.com/ansible/devel/community/communication.html#real-time-chat>`_.
+
+6. 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 ``verison_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`` snce 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>`_.

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>`.

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

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 <module_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 <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 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.
+

docs/docsite/rst/community/collection_development_process.rst

@@ -66,6 +66,8 @@ More precisely:
 
 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
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -151,7 +153,8 @@ A single changelog fragment may contain multiple sections but most will only con
 
 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``.
+Most changelog entries are ``bugfixes`` or ``minor_changes``. You can also use ``trivial``  for any collection that requires a changelog fragment for each pull request. ``trivial`` changelog fragments are excluded from the changelog output.
+
 
 Changelog fragment entry format
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

docs/docsite/rst/community/communication.rst

@@ -86,10 +86,10 @@ 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.im>`_ - ``Matrix: #social:ansible.im | IRC: #ansible-social``
-- `General usage and support questions <https://matrix.to:/#/#users:ansible.im>`_ - ``Matrix: #users:ansible.im | IRC: #ansible``
-- `Discussions on developer topics and code related to features or bugs <https://matrix.to/#/#devel:ansible.im>`_ - ``Matrix: #devel:ansible.im | IRC: #ansible-devel``
-- `Discussions on community and collections related topics <https://matrix.to:/#/#community:ansible.im>`_ - ``Matrix: #community:ansible.im | IRC: #ansible-community``
+- `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/master/meetings/README.md>`_
 
@@ -100,28 +100,29 @@ 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.
 
-- `Amazon (AWS) Working Group <https://github.com/ansible/community/wiki/AWS>`_ - Matrix: `#aws:ansible.im <https://matrix.to:/#/#aws:ansible.im>`_ | IRC: ``#ansible-aws``
-- `Ansible Lockdown Working Group <https://github.com/ansible/community/wiki/Lockdown>`_ (`Security playbooks/roles <https://github.com/ansible/ansible-lockdown>`_) - Matrix: `#lockdown:ansible.im <https://matrix.to:/#/#lockdown:ansible.im>`_ | IRC: ``#ansible-lockdown``
-- `AWX Working Group <https://github.com/ansible/awx>`_ - Matrix: `#awx:ansible.im <https://matrix.to:/#/#awx:ansible.im>`_ | IRC: ``#ansible-awx``
-- `Azure Working Group <https://github.com/ansible/community/wiki/Azure>`_ - Matrix: `#azure:ansible.im <https://matrix.to:/#/#azure:ansible.im>`_ | IRC: ``#ansible-azure``
-- `Community Working Group <https://github.com/ansible/community/wiki/Community>`_ (including Meetups) - Matrix: `#community:ansible.im <https://matrix.to:/#/#community:ansible.im>`_ | IRC: ``#ansible-community``
-- `Container Working Group <https://github.com/ansible/community/wiki/Container>`_ - Matrix: `#container:ansible.im <https://matrix.to:/#/#container:ansible.im>`_ | IRC: ``#ansible-container``
-- `Contributor Experience Working Group <https://github.com/ansible/community/wiki/Contributor-Experience>`_ - Matrix: `#community:ansible.im <https://matrix.to:/#/#community:ansible.im>`_ | IRC: ``#ansible-community``
+- `Amazon (AWS) Working Group <https://github.com/ansible/community/wiki/AWS>`_ - Matrix: `#aws:ansible.com <https://matrix.to:/#/#aws:ansible.com>`_ | IRC: ``#ansible-aws``
+- `Ansible Lockdown Working Group <https://github.com/ansible/community/wiki/Lockdown>`_ (`Security playbooks/roles <https://github.com/ansible/ansible-lockdown>`_) - Matrix: `#lockdown:ansible.com <https://matrix.to:/#/#lockdown:ansible.com>`_ | IRC: ``#ansible-lockdown``
+- `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.im <https://matrix.to:/#/#diversity:ansible.im>`_ | IRC: ``#ansible-diversity``
-- `Docker Working Group <https://github.com/ansible/community/wiki/Docker>`_ - Matrix: `#devel:ansible.im <https://matrix.to:/#/#devel:ansible.im>`_ | IRC: ``#ansible-devel``
-- `Documentation Working Group <https://github.com/ansible/community/wiki/Docs>`_ - Matrix: `#docs:ansible.im <https://matrix.to:/#/#docs:ansible.im>`_ | IRC: ``#ansible-docs``
-- `Galaxy Working Group <https://github.com/ansible/community/wiki/Galaxy>`_ - Matrix: `#galaxy:ansible.im <https://matrix.to:/#/#galaxy:ansible.im>`_ | IRC: ``#ansible-galaxy``
-- `JBoss Working Group <https://github.com/ansible/community/wiki/JBoss>`_ - Matrix: `#jboss:ansible.im <https://matrix.to:/#/#jboss:ansible.im>`_ | IRC: ``#ansible-jboss``
-- `Kubernetes Working Group <https://github.com/ansible/community/wiki/Kubernetes>`_ - Matrix: `#kubernetes:ansible.im <https://matrix.to:/#/#kubernetes:ansible.im>`_ | IRC: ``#ansible-kubernetes``
-- `Linode Working Group <https://github.com/ansible/community/wiki/Linode>`_ - Matrix: `#linode:ansible.im <https://matrix.to:/#/#linode:ansible.im>`_ | IRC: ``#ansible-linode``
+- `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``
-- `Network Working Group <https://github.com/ansible/community/wiki/Network>`_ - Matrix: `#network:ansible.im <https://matrix.to:/#/#network:ansible.im>`_ | IRC: ``#ansible-network``
-- `Remote Management Working Group <https://github.com/ansible/community/issues/409>`_ - Matrix: `#devel:ansible.im <https://matrix.to:/#/#devel:ansible.im>`_ | IRC: ``#ansible-devel``
-- `Testing Working Group <https://github.com/ansible/community/wiki/Testing>`_  - Matrix: `#devel:ansible.im <https://matrix.to:/#/#devel:ansible.im>`_ | IRC: ``#ansible-devel``
-- `VMware Working Group <https://github.com/ansible/community/wiki/VMware>`_ - Matrix: `#vmware:ansible.im <https://matrix.to:/#/#vmware:ansible.im>`_ | IRC: ``#ansible-vmware``
-- `Windows Working Group <https://github.com/ansible/community/wiki/Windows>`_ - Matrix: `#windows:ansible.im <https://matrix.to:/#/#windows:ansible.im>`_ | IRC: ``#ansible-windows``
-- `Ansible developer tools Group <https://github.com/ansible/community/wiki/Ansible-developer-tools>`_ - Matrix: `devtools:ansible.im <https://matrix.to/#/#devtools:ansible.im>`_ | IRC: ``#ansible-devtools``
+- `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``
+- `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/master/WORKING-GROUPS.md>`_?
 
@@ -141,14 +142,14 @@ The Ansible community holds regular meetings on various topics on Matrix/IRC, an
 Ansible Community Topics
 ========================
 
-The `Ansible Community Steering Committee <https://github.com/ansible/community-docs/blob/main/ansible_community_steering_committee.rst>`_ 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.
+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://github.com/ansible/community-docs/blob/main/ansible_community_steering_committee.rst>`_
+* `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

docs/docsite/rst/community/contributions_collections.rst

@@ -11,10 +11,11 @@ Ansible Collections Contributor Guide
    reporting_collections
    create_pr_quick_start
    collection_contributors/test_index
-   documentation_contributions
+   collection_contributors/collection_reviewing
    maintainers
    contributing_maintained_collections
    steering/steering_index
+   documentation_contributions
    other_tools_and_programs
 
 
@@ -30,3 +31,4 @@ Working with the Ansible collection repositories
 * 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.

docs/docsite/rst/community/contributor_path.rst

@@ -0,0 +1,104 @@
+****************
+Contributor path
+****************
+
+This section describes the contributor journey from the beginning to becoming a leader who helps shape the future of Ansible. You can use this path as a roadmap for your long-term participation.
+
+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 *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. Familarize 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` and the `collection repository <https://github.com/ansible-collections/>`_  ``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.
+
+You can also look for GitHub issues labeled with the ``easyfix``, ``good_first_issue``, and ``docs`` labels.  Add a comment on the GitHub issue to say you are looking at it and to ask for help 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 `improving documentation <ommunity_documentation_contributions>`, answering question from other contributors and users  on `Matrix/Libera.Chat IRC <communicate>`, giving advice in issues and pull requests, and discussing the `Community Topics <https://github.com/ansible-community/community-topics/issues>`_.
+
+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.
+
+* `module_maintainers` - The stage prior to becoming a collection maintainer. The file is usually a module or plugin. File maintainers have indirect commit rights.
+* supershipit permissions - Similar to being a file maintainer but the scope where a maintainer has the indirect commit is the whole repository.
+* ``triage``  - Access to the repository that allows contributors manage issues and pull requests.
+* ``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 `Steering Committee <community_steering_committee>`_ member status reflects the highest level of trust which allows contributors to lead the project through making very important `decisions <https://github.com/ansible-community/community-topics/issues>`_ for the Ansible project. The Committee members are the community leaders who shape the project's future and the future of automation in the IT world in general.
+
+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.

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 <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.12 release project <https://github.com/ansible/ansible/projects/43>`_
    * the `core documentation project <https://github.com/ansible/ansible/projects/27>`_
 
+
 .. _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 <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
+* 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 <backport_process>`_ to one or more ``stable-X.Y`` branches (optional, bugfixes only)
 
 Automated PR review: ansibullbot
 --------------------------------
@@ -249,7 +252,9 @@ A single changelog fragment may contain multiple sections but most will only con
 
 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``.
+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:
 
@@ -355,7 +360,7 @@ We do **not** backport features.
 
    These instructions assume that:
 
-    * ``stable-2.12`` is the targeted release branch for the backport
+    * ``stable-2.13`` 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.
 
@@ -364,7 +369,7 @@ We do **not** backport features.
 .. code-block:: shell
 
        git fetch upstream
-       git checkout -b backport/2.12/[PR_NUMBER_FROM_DEVEL] upstream/stable-2.12
+       git checkout -b backport/2.12/[PR_NUMBER_FROM_DEVEL] upstream/stable-2.13
 
 #. Cherry pick the relevant commit SHA from the devel branch into your feature branch, handling merge conflicts as necessary:
 
@@ -378,15 +383,15 @@ We do **not** backport features.
 
 .. code-block:: shell
 
-       git push origin backport/2.12/[PR_NUMBER_FROM_DEVEL]
+       git push origin backport/2.13/[PR_NUMBER_FROM_DEVEL]
 
-#. Submit the pull request for ``backport/2.12/[PR_NUMBER_FROM_DEVEL]`` against the ``stable-2.12`` branch
+#. Submit the pull request for ``backport/2.13/[PR_NUMBER_FROM_DEVEL]`` against the ``stable-2.13`` 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.12/[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.
+    The branch name ``backport/2.13/[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::
 

docs/docsite/rst/community/documentation_contributions.rst

@@ -74,7 +74,7 @@ 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.5 or greater and install the `Ansible dependencies`_ and `documentation dependencies`_, which are listed in two :file:`requirements.txt` files to make installation easier:
+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
@@ -84,12 +84,14 @@ To work with documentation on your local machine, you need to have python-3.5 or
     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:`docs/docsite/known_good_reqs.txt` instead:
+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 docs/docsite/known_good_reqs.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). 
 

docs/docsite/rst/community/how_can_I_help.rst

@@ -48,7 +48,10 @@ If there is no meetup near you, we are happy to help you `start one <https://www
 File and verify issues
 ======================
 
-All software has bugs, and Ansible is no exception. When you find a bug, you can help tremendously by :ref:`telling us about it <reporting_bugs_and_features>`.
+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.
@@ -56,16 +59,16 @@ If the bug you found already exists in an issue, you can help by verifying the b
 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:`Ansible development process <community_development_process>` and and :ref:`how to contribute to collections <contributing_maintained_collections>` to learn how to get your code accepted into Ansible.
+As you become more familiar with how Ansible works, you may be able to fix issues or develop new features yourself. If you think you have a fix for a bug in Ansible, or if you have a new feature that you would like to share with millions of Ansible users, read all about the :ref:`development process <community_development_process>` to learn how to get your code accepted into Ansible.
 
-Another good way to help is to review pull requests that other Ansible users have submitted. The Ansible community 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.
+Another good way to help is to review pull requests that other Ansible users have submitted. Ansible core keeps a full list of `open pull requests by file <https://ansible.sivel.net/pr/byfile.html>`_, so if a particular module or plugin interests you, you can easily keep track of all the relevant new pull requests and provide testing or feedback. Alternately, you can review the pull requests for any collections that interest you. Click :guilabel:`Issue tracker` on the collection documentation page to find the issues and PRs for that collection.
 
 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.
 
-To learn more about the responsibilities of being an Ansible module maintainer, please read our :ref:`collection maintainer guidelines <maintainers>`.
+ See :ref:`collection maintainer guidelines <maintainers>` to learn more about the responsibilities of being an Ansible collection maintainer.
 
 .. _community_working_groups:
 

docs/docsite/rst/community/index.rst

@@ -21,3 +21,4 @@ The purpose of this guide is to teach you everything you need to know about bein
    :maxdepth: 2
 
    getting_started
+   contributor_path

docs/docsite/rst/community/maintainers.rst

@@ -11,6 +11,7 @@ Thank you for being a community collection maintainer. This guide offers an over
 
    maintainers_guidelines
    maintainers_workflow
+   collection_contributors/collection_releasing
 
 In addition to the information here, module maintainers should be familiar with:
 

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<collection_maintainers>` 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<maintainer_requirements>` may either self-nominate or be nominated by another maintainer.
+A person interested in becoming a maintainer and satisfies the :ref:`requirements<maintainer_requirements>` may either self-nominate or be nominated by another maintainer.
 
-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 <https://github.com/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 <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.
+ 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:
@@ -51,7 +55,7 @@ See :ref:`communication` for more details on these communication channels.
 Community Topics
 ----------------
 
-The Community and the `Steering Committee <https://github.com/ansible/community-docs/blob/main/ansible_community_steering_committee.rst>`_ 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.
+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.
 
@@ -61,12 +65,12 @@ 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 <https://github.com/ansible/community/wiki/News#the-bullhorn>`_ for information when the next contributor summit, invite contributors you know, and take part in the event together.
+The quarterly Ansible Contributor Summit is a global event that provides our contributors a great opportunity to meet each other, communicate, share ideas, and see that there are other real people behind the messages on Matrix or Libera Chat IRC or GitHub. This gives a sense of community. Watch the `Bullhorn newsletter <https://github.com/ansible/community/wiki/News#the-bullhorn>`_ for information when the next contributor summit, invite contributors you know, and take part in the event together.
 
 Weekly community Matrix/IRC meetings
 ------------------------------------
 
-The Community and the Steering Committee come together at weekly meetings in the ``#ansible-community`` :ref:`Matrix/Libera.Chat <https://docs.ansible.com/ansible/devel/community/communication.html#real-time-chat>` channel to discuss important project-scale questions. See the `schedule <https://github.com/ansible/community/blob/main/meetings/README.md#schedule>`_ and join.
+The Community and the Steering Committee come together at weekly meetings in the ``#ansible-community`` :ref:`Matrix/Libera.Chat <communication_irc>` channel to discuss important project-scale questions. See the `schedule <https://github.com/ansible/community/blob/main/meetings/README.md#schedule>`_ and join.
 
 Expanding the collection community
 ===================================
@@ -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.
 
@@ -108,7 +112,18 @@ Promote active contributors satisfying :ref:`requirements<maintainer_requirement
 
 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 preferences, please say it explicitly.
+* When asking for adding tests or for complex code refactoring, say that the author is welcome to ask for clarifications and help if they need.
+* If 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:
 
@@ -117,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 <module_documenting>`.
+* 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.
 

docs/docsite/rst/community/maintainers_workflow.rst

@@ -1,20 +1,5 @@
 .. _maintainers_workflow:
 
-.. _Releasing:
-
-Releasing collections
-======================
-
-Collection maintainers release all supported stable versions of the collections regularly,
-provided that there have been enough changes merged to release.
-
-Generally, releasing in the collections consists of:
-
-1. Planning and announcement.
-2. Generating a changelog.
-3. Creating a release git tag and pushing it.
-4. Automatic publishing the release tarball on `Ansible Galaxy <https://galaxy.ansible.com/>`_ by `Zuul <https://dashboard.zuul.ansible.com/t/ansible/builds?pipeline=release>`_.
-5. Final announcement.
 
 Backporting and Ansible inclusion
 ==================================
@@ -23,8 +8,8 @@ Each collection community can set its own rules and workflow for managing pull r
 
 * :ref:`code_of_conduct`
 * :ref:`maintainer_requirements`
-* :ref:`Committer guidelines <committer_general_rules>`.
-* `PR review checklist <https://github.com/ansible/community-docs/blob/main/review_checklist.rst>`_
+* :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`.
 
@@ -59,6 +44,20 @@ 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 in the collections consists of:
+
+#. Planning and announcement.
+#. Generating a changelog.
+#. Creating a release git tag and pushing it.
+#. Automaticly 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
@@ -72,10 +71,12 @@ The manual backport process is similar to the :ref:`ansible-core backporting gui
 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>`_.
 
 
-Inclusion in Ansible
-----------------------
+.. _including_collection_ansible:
 
-If a collection is not included in Ansible (not shipped with Ansible package), maintainers can submit the collection for inclusion by creating a discussion under `ansible-collections/ansible-inclusion repository <https://github.com/ansible-collections/ansible-inclusion>`_. For more information, see the `repository's README <https://github.com/ansible-collections/ansible-inclusion/blob/main/README.md>`_.
+Including a collection in Ansible
+-----------------------------------
+
+If a collection is not included in Ansible (not shipped with Ansible package), maintainers can submit the collection for inclusion by creating a discussion under `ansible-collections/ansible-inclusion repository <https://github.com/ansible-collections/ansible-inclusion>`_. For more information, see the `repository's README <https://github.com/ansible-collections/ansible-inclusion/blob/main/README.md>`_, and the `Ansible community package collections requirements <https://github.com/ansible-collections/overview/blob/main/collection_requirements.rst>`.
 
 Stepping down as a collection maintainer
 ===========================================

docs/docsite/rst/community/reporting_bugs_and_features.rst

@@ -16,7 +16,7 @@ Reporting a bug
 Security bugs
 -------------
 
-Ansible practices responsible disclosure - for security-related bugs, email `security@ansible.com <mailto:security@ansible.com>`_ to receive a prompt response. Do not submit a  ticket or post to any public groups.
+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
 --------------------
@@ -38,17 +38,16 @@ If you find a bug, open an issue using the `issue template <https://github.com/a
 
 Fill out the issue template as completely and as accurately as possible. Include:
 
-  * your Ansible version
-  * the expected behavior
-  * the current behavior and why you think it is a bug
-  * what you've tried including the exact commands you were using or tasks you are running
-  * any relevant configurations and the components you used
-  * any relevant output plus ``ansible -vvvv`` (debugging) output
-  * the steps to reproduce the bug  
-    * Use a minimal reproducible example and comments describing examples
-    * Preserve formatting using `code blocks  <https://help.github.com/articles/creating-and-highlighting-code-blocks/>`_ when sharing YAML in playbooks.
+* 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``. 
 
-For multiple-file content, use gist.github.com, which is more durable than pastebin content.
+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:
 

docs/docsite/rst/community/steering/community_steering_committee.rst

@@ -1,12 +1,10 @@
 
-.. _steering_responsibilties:
+.. _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. The Committee helps decide the technical direction of the Ansible project and is responsible for approval of 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 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
@@ -35,6 +33,8 @@ The following table lists the current Steering Committee members. See :ref:`stee
   +------------------+---------------+-------------+
   | Name             | GitHub        | Start year  |
   +==================+===============+=============+
+  | Alexei Znamensky | russoz        | 2022        |
+  +------------------+---------------+-------------+
   | Alicia Cozine    | acozine       | 2021        |
   +------------------+---------------+-------------+
   | Andrew Klychkov  | Andersson007  | 2021        |
@@ -49,16 +49,17 @@ 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        |
+  +------------------+---------------+-------------+
   | Markus Bergholz  | markuman      | 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.
 
@@ -114,7 +115,11 @@ When reviewing community collection `inclusion requests <https://github.com/ansi
 
 #. 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 Committee members.
+#. 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.
 

docs/docsite/rst/community/steering/steering_committee_membership.rst

@@ -3,7 +3,7 @@
 Steering Committee membership guidelines
 ==========================================
 
-This document describes the expectations and policies related to membership in the `Ansible Community Steering Committee <https://github.com/ansible/community-docs/blob/main/ansible_community_steering_committee.rst>`_ (hereinafter the Committee).
+This document describes the expectations and policies related to membership in the :ref:`Ansible Community Steering Committee <steering_responsibilities>` (hereinafter the Committee).
 
 .. contents:: Topics:
 
@@ -119,6 +119,8 @@ In case of the `Ansible Community Code of Conduct <https://docs.ansible.com/ansi
 
 In case of starting the removal process, the topic's description in the reason's part changes correspondingly.
 
+.. _chairperson:
+
 Chairperson
 ------------
 

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.

docs/docsite/rst/core_index.rst

@@ -31,7 +31,11 @@ This documentation covers the version of ``ansible-core`` noted in the upper lef
 
 ``ansible-core`` releases a new major release approximately twice a year. The core application evolves somewhat conservatively, valuing simplicity in language design and setup. Contributors develop and change modules and plugins, hosted in collections since version 2.10, much more quickly.
 
+.. toctree::
+   :maxdepth: 2
+   :caption: Ansible getting started
 
+   getting_started/index
 
 .. toctree::
    :maxdepth: 2

docs/docsite/rst/dev_guide/ansible_index.rst

@@ -35,10 +35,10 @@ Find the task that best describes what you want to do:
    * I want to write a specific kind of module:
       * a :ref:`network module <developing_modules_network>`
       * a :ref:`Windows module <developing_modules_general_windows>`.
-      * an :ref:`Amazon module <AWS_module_development>`.
+      * an :ref:`Amazon module <ansible_collections.amazon.aws.docsite.dev_guide_intro>`.
       * an :ref:`OpenStack module <OpenStack_module_development>`.
       * an :ref:`oVirt/RHV module <oVirt_module_development>`.
-      * a :ref:`VMware module <VMware_module_development>`.
+      * a :ref:`VMware module <ansible_collections.community.vmware.docsite.vmware_ansible_devguide>`.
    * I want to :ref:`write a series of related modules <developing_modules_in_groups>` that integrate Ansible with a new product (for example, a database, cloud provider, network platform, and so on).
 
 * I want to refine my code:

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.

docs/docsite/rst/dev_guide/core_index.rst

@@ -0,0 +1,89 @@
+.. _developer_guide:
+
+***************
+Developer 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 Developer Guide!
+
+**Who should use this guide?**
+
+If you want to extend Ansible by using a custom module or plugin locally, creating a module or plugin, adding functionality to an existing module, or expanding test coverage, this guide is for you. We've included detailed information for developers on how to test and document modules, as well as the prerequisites for getting your module or plugin accepted into the main Ansible repository.
+
+Find the task that best describes what you want to do:
+
+* I'm looking for a way to address a use case:
+
+   * I want to :ref:`add a custom plugin or module locally <developing_locally>`.
+   * I want to figure out if :ref:`developing a module is the right approach <module_dev_should_you>` for my use case.
+   * I want to :ref:`develop a collection <developing_collections>`.
+   * I want to :ref:`contribute to an Ansible-maintained collection <contributing_maintained_collections>`.
+   * I want to :ref:`contribute to a community-maintained collection <hacking_collections>`.
+   * I want to :ref:`migrate a role to a collection <migrating_roles>`.
+
+* I've read the info above, and I'm sure I want to develop a module:
+
+   * What do I need to know before I start coding?
+   * I want to :ref:`set up my Python development environment <environment_setup>`.
+   * I want to :ref:`get started writing a module <developing_modules_general>`.
+   * I want to write a specific kind of module:
+      * a :ref:`network module <developing_modules_network>`
+      * a :ref:`Windows module <developing_modules_general_windows>`.
+   * I want to :ref:`write a series of related modules <developing_modules_in_groups>` that integrate Ansible with a new product (for example, a database, cloud provider, network platform, and so on).
+
+* I want to refine my code:
+
+   * I want to :ref:`debug my module code <debugging_modules>`.
+   * I want to :ref:`add tests <developing_testing>`.
+   * I want to :ref:`document my module <module_documenting>`.
+   * I want to :ref:`document my set of modules for a network platform <documenting_modules_network>`.
+   * I want to follow :ref:`conventions and tips for clean, usable module code <developing_modules_best_practices>`.
+   * I want to :ref:`make sure my code runs on Python 2 and Python 3 <developing_python_3>`.
+
+* I want to work on other development projects:
+
+   * I want to :ref:`write a plugin <developing_plugins>`.
+   * I want to :ref:`connect Ansible to a new source of inventory <developing_inventory>`.
+   * I want to :ref:`deprecate an outdated module <deprecating_modules>`.
+
+* I want to contribute back to the Ansible project:
+
+  * I want to :ref:`understand how to contribute to Ansible <ansible_community_guide>`.
+  * I want to :ref:`contribute my module or plugin <developing_modules_checklist>`.
+  * I want to :ref:`understand the license agreement <contributor_license_agreement>` for contributions to Ansible.
+
+If you prefer to read the entire guide, here's a list of the pages in order.
+
+.. toctree::
+   :maxdepth: 2
+
+   developing_locally
+   developing_modules
+   developing_modules_general
+   developing_modules_checklist
+   developing_modules_best_practices
+   developing_python_3
+   debugging
+   developing_modules_documenting
+   developing_modules_general_windows
+   developing_modules_general_aci
+   developing_modules_in_groups
+   testing
+   module_lifecycle
+   developing_plugins
+   developing_inventory
+   developing_core
+   developing_program_flow_modules
+   developing_api
+   developing_rebasing
+   developing_module_utilities
+   developing_collections
+   migrating_roles
+   collections_galaxy_meta
+   overview_architecture

docs/docsite/rst/dev_guide/developing_collections_shared.rst

@@ -70,7 +70,7 @@ The optional import behavior also applies to module_utils imported from collecti
 Listing collection dependencies
 ===============================
 
-We recommend that collections work as standalone, independent units, depending only on ansible-core. However, if your collection must depend on features and functionality from another collection, list the other collection or collections under ``dependencies`` in your collection's :file:`galaxy.yml` file. For more information on the :file:`galaxy.yml` file, see :ref:`collections_galaxy_meta`.
+We recommend that collections work as standalone, independent units, depending only on ansible-core. However, if your collection must depend on features and functionality from another collection, list the other collection or collections under ``dependencies`` in your collection's :file:`galaxy.yml` file. Use the :file:`meta/runtime.yml` file to set the ansible-core version that your collection depends on. For more information on the :file:`galaxy.yml` file, see :ref:`collections_galaxy_meta`.
 
 You can use git repositories for collection dependencies during local development and testing. For example:
 

docs/docsite/rst/dev_guide/developing_collections_structure.rst

@@ -70,7 +70,9 @@ For community collections included in the Ansible PyPI package, docs.ansible.com
      toctree:
        - scenario_guide
 
-The index page of the documentation for your collection displays the title you define in ``docs/docsite/extra-docs.yml`` with a link to your extra documentation. For an example, see the `community.docker collection repo <https://github.com/ansible-collections/community.docker/tree/main/docs/docsite>`_ and the `community.docker collection documentation <https://docs.ansible.com/ansible/latest/collections/community/docker/index.html>`_. 
+The index page of the documentation for your collection displays the title you define in ``docs/docsite/extra-docs.yml`` with a link to your extra documentation. For an example, see the `community.docker collection repo <https://github.com/ansible-collections/community.docker/tree/main/docs/docsite>`_ and the `community.docker collection documentation <https://docs.ansible.com/ansible/latest/collections/community/docker/index.html>`_.
+
+You can add extra links to your collection index page and plugin pages with the ``docs/docsite/links.yml`` file. This populates the links under `Description and Communications <https://docs.ansible.com/ansible/devel/collections/community/dns/index.html#plugins-in-community-dns>`_ headings as well as links at the end of the individual plugin pages. See the `collection_template links.yml file <https://github.com/ansible-collections/collection_template/blob/main/docs/docsite/links.yml>`_ for a complete description of the structure and use of this file to create links.
 
 Plugin and module documentation
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -183,6 +185,13 @@ This will keep the playbook in 'collection context', as if you had added ``colle
 
 You can have most of the subdirectories you would expect, such ``files/``, ``vars/`` or  ``templates/`` but no ``roles/`` since those are handled already in the collection.
 
+Also, playbooks within a collection follow the same guidelines as any playbooks except for these few adjustments:
+
+ - Directory: It must be in ``/playbooks directory``.
+ - Hosts: The host should be defined as a variable so the users of a playbook do not mistakenly run the plays against their entire inventory (if the host is set to all). For example - ``hosts: '{{target|default("all")}}'``.
+
+To run the plays, users can now use such commands as ``ansible-playbook --e 'targets=webservers'`` or ``ansible-playbook --limit webservers``. Either way, the collection owner should document their playbooks and how to use them in the ``/docs`` folder or ``README`` file.
+
 .. _developing_collections_tests_directory:
 
 tests directory
@@ -196,8 +205,8 @@ When reading the :ref:`developing_testing` documentation, there will be content
 
 .. _meta_runtime_yml:
 
-meta directory
---------------
+meta directory and runtime.yml
+------------------------------
 
 A collection can store some additional metadata in a ``runtime.yml`` file in the collection's ``meta`` directory. The ``runtime.yml`` file supports the top level keys:
 

docs/docsite/rst/dev_guide/developing_core.rst

@@ -7,6 +7,7 @@ Although ``ansible-core`` (the code hosted in the `ansible/ansible repository <h
 .. toctree::
    :maxdepth: 1
 
+   core_branches_and_tags
    developing_program_flow_modules
 
 .. seealso::

docs/docsite/rst/dev_guide/developing_modules_best_practices.rst

@@ -160,7 +160,6 @@ Ansible conventions offer a predictable user interface across all modules, playb
 * Implement declarative operations (not CRUD) so the user can ignore existing state and focus on final state. For example, use ``started/stopped``, ``present/absent``.
 * Strive for a consistent final state (aka idempotency). If running your module twice in a row against the same system would result in two different states, see if you can redesign or rewrite to achieve consistent final state. If you can't, document the behavior and the reasons for it.
 * Provide consistent return values within the standard Ansible return structure, even if NA/None are used for keys normally returned under other options.
-* Follow additional guidelines that apply to families of modules if applicable. For example, AWS modules should follow the  :ref:`Amazon development checklist <AWS_module_development>`.
 
 
 Module Security

docs/docsite/rst/dev_guide/developing_modules_checklist.rst

@@ -42,5 +42,4 @@ Other checklists
 ================
 
 * :ref:`Tips for module development <developing_modules_best_practices>`.
-* :ref:`Amazon development checklist <AWS_module_development>`.
 * :ref:`Windows development checklist <developing_modules_general_windows>`.

docs/docsite/rst/dev_guide/developing_modules_documenting.rst

@@ -33,28 +33,24 @@ Begin your Ansible module with ``#!/usr/bin/python`` - this "shebang" allows ``a
 Copyright and license
 =====================
 
-After the shebang and UTF-8 coding, add a `copyright line <https://www.gnu.org/licenses/gpl-howto.en.html>`_ with the original copyright holder and a license declaration. The license declaration should be ONLY one line, not the full GPL prefix.:
+After the shebang and UTF-8 coding, add a `copyright line <https://www.linuxfoundation.org/blog/copyright-notices-in-open-source-software-projects/>`_ with the original copyright holder and a license declaration. The license declaration should be ONLY one line, not the full GPL prefix.:
 
 .. code-block:: python
 
     #!/usr/bin/python
     # -*- coding: utf-8 -*-
 
-    # Copyright: (c) 2018, Terry Jones <terry.jones@example.org>
+    # Copyright: Contributors to the Ansible project
     # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-Major additions to the module (for instance, rewrites) may add additional copyright lines. Any legal review will include the source control history, so an exhaustive copyright header is not necessary.
-Please do not edit the existing copyright year. This simplifies project administration and is unlikely to cause any interesting legal issues.
-When adding a second copyright line for a significant feature or rewrite, add the newer line above the older one:
+Additions to the module (for instance, rewrites) are not permitted to add additional copyright lines other than the default copyright statement if missing:
 
 .. code-block:: python
 
-    #!/usr/bin/python
-    # -*- coding: utf-8 -*-
-
-    # Copyright: (c) 2017, [New Contributor(s)]
-    # Copyright: (c) 2015, [Original Contributor(s)]
-    # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+    # Copyright: Contributors to the Ansible project
+    
+Any legal review will include the source control history, so an exhaustive copyright header is not necessary.
+Please do not include a copyright year. If the existing copyright statement includes a year, do not edit the existing copyright year. Any existing copyright header should not be modified without permission from the copyright author.
 
 .. _ansible_metadata_block:
 
@@ -236,6 +232,7 @@ All fields in the ``DOCUMENTATION`` block are lower-case. All fields are require
   * Details of any important information that doesn't fit in one of the above sections.
   * For example, whether ``check_mode`` is or is not supported.
 
+.. _module_documents_linking:
 
 Linking and other format macros within module documentation
 -----------------------------------------------------------
@@ -253,8 +250,8 @@ content in a uniform way:
 * ``I()`` for option names. For example: ``Required if I(state=present).``  This is italicized in
   the documentation.
 * ``C()`` for files, option values, and inline code. For example: ``If not set the environment variable C(ACME_PASSWORD) will be used.`` or ``Use C(var | foo.bar.my_filter) to transform C(var) into the required format.``  This displays with a mono-space font 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 ``<hr>`` 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 ``<hr>`` html tag) in the documentation.
 
 .. note::
 

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 <developing_collections>`,  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)
------------------------------------------
+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.
 
-Due to dependencies (for example ansible -> paramiko -> pynacl -> libffi):
+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.
 
-.. code:: bash
+Creating a module
+=================
 
-    sudo apt update
-    sudo apt install build-essential libssl-dev libffi-dev python-dev
+It is highly recommended that you use a ``venv`` or ``virtualenv`` for Python development.
 
-Installing prerequisites via yum (CentOS)
------------------------------------------
+To create a module:
 
-Due to dependencies (for example ansible -> paramiko -> pynacl -> libffi):
-
-.. code:: bash
-
-    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 development environment (platform-independent steps)
----------------------------------------------------------------
-
-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``
-
-.. 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 <developing_modules_documenting>`, a simple :ref:`argument spec for declaring the module options <argument_spec>`, 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 <developing_modules_best_practices>` and :ref:`Python 3 compatibility <developing_python_3>` 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<return_block>` and :ref:`examples<examples_block>`.
 
-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 <developing_modules_documenting>`, a simple :ref:`argument spec for declaring the module options <argument_spec>`, 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 <developing_modules_best_practices>` and :ref:`Python 3 compatibility <developing_python_3>` 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 <developing_collections>`, ``$ 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 <developing_modules_documenting>`, a simple :ref:`argument spec for declaring the module options <argument_spec>`, 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 <developing_modules_best_practices>` and :ref:`Python 3 compatibility <developing_python_3>` 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 <debugging_modules>` 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:
 
-This should return output like this:
+.. code:: console
+
+   ``$ 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 <testing_module_documentation>`, adding :ref:`integration tests <testing_integration>`, 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 <https://docs.ansible.com/ansible/latest/dev_guide/testing/sanity/integration-aliases.html>`_.
 
 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
 ============================

docs/docsite/rst/dev_guide/developing_plugins.rst

@@ -225,7 +225,7 @@ but with an extra option so you can see how configuration works in Ansible versi
 
     # not only visible to ansible-doc, it also 'declares' the options the plugin requires and how to configure them.
     DOCUMENTATION = '''
-    callback: timer
+    name: timer
     callback_type: aggregate
     requirements:
         - enable in configuration
@@ -357,8 +357,8 @@ Here's a simple lookup plugin implementation --- this lookup returns the content
     __metaclass__ = type
 
     DOCUMENTATION = """
-      lookup: file
-      author: Daniel Hokka Zakrisson <daniel@hozac.com>
+      name: file
+      author: Daniel Hokka Zakrisson (@dhozac) <daniel@hozac.com>
       version_added: "0.9"  # for collections, use the collection version, not the Ansible version
       short_description: read file contents
       description:

docs/docsite/rst/dev_guide/developing_python_3.rst

@@ -4,47 +4,31 @@
 Ansible and Python 3
 ********************
 
-The ``ansible-core`` code runs on both Python 2 and Python 3 because we want Ansible to be able to manage a wide
-variety of machines. Contributors to ansible-core and to Ansible Collections should be aware of the tips in this document so that they can write code that will run on the same versions of Python as the rest of Ansible.
+The ``ansible-core`` code runs Python 3 (for specific versions check `Control Node Requirements <:ref:control-node-requirements>`_.
+Contributors to ``ansible-core`` and to Ansible Collections should be aware of the tips in this document so that they can write code
+that will run on the same versions of Python as the rest of Ansible.
 
 .. contents::
    :local:
 
-To ensure that your code runs on Python 3 as well as on Python 2, learn the tips and tricks and idioms
-described here. Most of these considerations apply to all three types of Ansible code:
+We do have some considerations depending on the types of Ansible code:
 
-1. controller-side code - code that runs on the machine where you invoke :command:`/usr/bin/ansible`
-2. modules - the code which Ansible transmits to and invokes on the managed machine.
-3. shared ``module_utils`` code - the common code that's used by modules to perform tasks and sometimes used by controller-side code as well
+1. controller-side code - code that runs on the machine where you invoke :command:`/usr/bin/ansible`, only needs to support the controller's Python versions.
+2. modules - the code which Ansible transmits to and invokes on the managed machine. Modules need to support the 'managed node' Python versions, with some exceptions.
+3. shared ``module_utils`` code - the common code that is  used by modules to perform tasks and sometimes used by controller-side code as well. Shared ``module_utils`` code needs to support the same range of Python as the modules.
 
 However, the three types of code do not use the same string strategy. If you're developing a module or some ``module_utils`` code, be sure to read the section on string strategy carefully.
 
+.. note:
+    - While modules can be written in any language, the above applies to code contributed to the core project, which only supports specific Python versions and Powershell for Windows.
+
 Minimum version of Python 3.x and Python 2.x
 ============================================
 
-On the controller we support Python 3.5 or greater and Python 2.7 or greater.  Module-side, we
-support Python 3.5 or greater and Python 2.6 or greater.
+See `Control Node Requirements <:ref:control-node-requirements>`_ and `Managed Node Requirements <:ref:managed-node-requirements>`_ for the
+specific versions supported.
 
-Python 3.5 was chosen as a minimum because it is the earliest Python 3 version adopted as the
-default Python by a Long Term Support (LTS) Linux distribution (in this case, Ubuntu-16.04).
-Previous LTS Linux distributions shipped with a Python 2 version which users can rely upon instead
-of the Python 3 version.
-
-For Python 2, the default is for modules to run on at least Python 2.6.  This allows
-users with older distributions that are stuck on Python 2.6 to manage their
-machines.  Modules are allowed to drop support for Python 2.6 when one of
-their dependent libraries requires a higher version of Python. This is not an
-invitation to add unnecessary dependent libraries in order to force your
-module to be usable only with a newer version of Python; instead it is an
-acknowledgment that some libraries (for instance, boto3 and docker-py) will
-only function with a newer version of Python.
-
-.. note:: Python 2.4 Module-side Support:
-
-    Support for Python 2.4 and Python 2.5 was dropped in Ansible-2.4.  RHEL-5
-    (and its rebuilds like CentOS-5) were supported until April of 2017.
-    Ansible-2.3 was released in April of 2017 and was the last Ansible release
-    to support Python 2.4 on the module-side.
+Your custom modules can support any version of Python (or other languages) you want, but the above are the requirements for the code contributed to the Ansible project.
 
 Developing Ansible code that supports Python 2 and Python 3
 ===========================================================
@@ -90,7 +74,7 @@ Ansible uses different strategies for working with strings in controller-side co
 Controller string strategy: the Unicode Sandwich
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-In controller-side code we use a strategy known as the Unicode Sandwich (named
+Until recently ``ansible-core`` supported Python 2.x and followed this strategy, known as the Unicode Sandwich (named
 after Python 2's :func:`unicode  <python:unicode>` text type).  For Unicode Sandwich we know that
 at the border of our code and the outside world (for example, file and network IO,
 environment variables, and some library calls) we are going to receive bytes.
@@ -100,6 +84,13 @@ the outside world we first convert the text back into bytes.
 To visualize this, imagine a 'sandwich' consisting of a top and bottom layer
 of bytes, a layer of conversion between, and all text type in the center.
 
+For compatibility reasons you will see a bunch of custom functions we developed (``to_text``/``to_bytes``/``to_native``)
+and while Python 2 is not a concern anymore we will continue to use them as they apply for other cases that make
+dealing with unicode problematic.
+
+While we will not be using it most of it anymore, the documentation below is still useful for those developing modules
+that still need to support both Python 2 and 3 simultaneouslly.
+
 Unicode Sandwich common borders: places to convert bytes to text in controller code
 -----------------------------------------------------------------------------------
 
@@ -400,8 +391,3 @@ does have support for the older, percent-formatting.
     Python documentation on `percent formatting <https://docs.python.org/3/library/stdtypes.html#string-formatting>`_
 
 .. _testing_modules_python_3:
-
-Testing modules on Python 3
-===================================
-
-Ansible modules are slightly harder to code to support Python 3 than normal code from other projects. A lot of mocking has to go into unit testing an Ansible module, so it's harder to test that your changes have fixed everything or to to make sure that later commits haven't regressed the Python 3 support. Review our :ref:`testing <developing_testing>` pages for more information.

docs/docsite/rst/dev_guide/platforms/aws_guidelines.rst

@@ -4,782 +4,4 @@
 Guidelines for Ansible Amazon AWS module development
 ****************************************************
 
-The Ansible AWS collection (on `Galaxy <https://galaxy.ansible.com/community/aws>`_, source code `repository <https://github.com/ansible-collections/community.aws>`_) is maintained by the Ansible AWS Working Group.  For further information see the `AWS working group community page <https://github.com/ansible/community/wiki/aws>`_. If you are planning to contribute AWS modules to Ansible then getting in touch with the working group is a good way to start, especially because a similar module may already be under development.
-
-.. contents::
-   :local:
-
-Requirements
-============
-
-Python Compatibility
---------------------
-
-AWS content in Ansible 2.9 and 1.x collection releases supported Python 2.7 and newer.
-
-Starting with the 2.0 releases of both collections, Python 2.7 support will be ended in accordance with AWS' `end of Python 2.7 support <https://aws.amazon.com/blogs/developer/announcing-end-of-support-for-python-2-7-in-aws-sdk-for-python-and-aws-cli-v1/>`_.  Contributions to both collections that target the 2.0 or later collection releases can be written to support Python 3.6+ syntax.
-
-SDK Version Support
--------------------
-
-Starting with the 2.0 releases of both collections, it is generally the policy to support the versions of botocore and boto3 that were released 12 months prior to the most recent major collection release, following semantic versioning (for example, 2.0.0, 3.0.0).
-
-Features and functionality that require newer versions of the SDK can be contributed provided they are noted in the module documentation:
-
-.. code-block:: yaml
-
-  DOCUMENTATION = '''
-  ---
-  module: ec2_vol
-  options:
-    throughput:
-      description:
-        - Volume throughput in MB/s.
-        - This parameter is only valid for gp3 volumes.
-        - Valid range is from 125 to 1000.
-        - Requires at least botocore version 1.19.27.
-      type: int
-      version_added: 1.4.0
-
-And handled using the ``botocore_at_least`` helper method:
-
-.. code-block:: python
-
-    if module.params.get('throughput'):
-        if not module.botocore_at_least("1.19.27"):
-            module.fail_json(msg="botocore >= 1.19.27 is required to set the throughput for a volume")
-
-
-Maintaining existing modules
-============================
-
-Fixing bugs
------------
-
-Bug fixes to code that relies on boto will still be accepted. When possible,
-the code should be ported to use boto3.
-
-Adding new features
--------------------
-
-Try to keep backward compatibility with relatively recent versions of boto3. That means that if you
-want to implement some functionality that uses a new feature of boto3, it should only fail if that
-feature actually needs to be run, with a message stating the missing feature and minimum required
-version of boto3.
-
-Use feature testing (for example, ``hasattr('boto3.module', 'shiny_new_method')``) to check whether boto3
-supports a feature rather than version checking. For example, from the ``ec2`` module:
-
-.. code-block:: python
-
-   if boto_supports_profile_name_arg(ec2):
-       params['instance_profile_name'] = instance_profile_name
-   else:
-       if instance_profile_name is not None:
-           module.fail_json(msg="instance_profile_name parameter requires boto version 2.5.0 or higher")
-
-Migrating to boto3
-------------------
-
-Prior to Ansible 2.0, modules were written in either boto3 or boto. We are
-still porting some modules to boto3. Modules that still require boto should be ported to use boto3 rather than using both libraries (boto and boto3). We would like to remove the boto dependency from all modules.
-
-Porting code to AnsibleAWSModule
----------------------------------
-
-Some old AWS modules use the generic ``AnsibleModule`` as a base rather than the more efficient ``AnsibleAWSModule``. To port an old module to ``AnsibleAWSModule``, change:
-
-.. code-block:: python
-
-   from ansible.module_utils.basic import AnsibleModule
-   ...
-   module = AnsibleModule(...)
-
-to:
-
-.. code-block:: python
-
-   from ansible_collections.amazon.aws.plugins.module_utils.core import AnsibleAWSModule
-   ...
-   module = AnsibleAWSModule(...)
-
-Few other changes are required. AnsibleAWSModule
-does not inherit methods from AnsibleModule by default, but most useful methods
-are included. If you do find an issue, please raise a bug report.
-
-When porting, keep in mind that AnsibleAWSModule also will add the default ec2
-argument spec by default. In pre-port modules, you should see common arguments
-specified with:
-
-.. code-block:: python
-
-   def main():
-       argument_spec = ec2_argument_spec()
-       argument_spec.update(dict(
-           state=dict(default='present', choices=['present', 'absent', 'enabled', 'disabled']),
-           name=dict(default='default'),
-           # ... and so on ...
-       ))
-       module = AnsibleModule(argument_spec=argument_spec, supports_check_mode=True,)
-
-These can be replaced with:
-
-.. code-block:: python
-
-   def main():
-       argument_spec = dict(
-           state=dict(default='present', choices=['present', 'absent', 'enabled', 'disabled']),
-           name=dict(default='default'),
-           # ... and so on ...
-       )
-       module = AnsibleAWSModule(argument_spec=argument_spec, supports_check_mode=True,)
-
-Creating new AWS modules
-========================
-
-Use boto3 and AnsibleAWSModule
--------------------------------
-
-All new AWS modules must use boto3 and ``AnsibleAWSModule``.
-
-``AnsibleAWSModule`` greatly simplifies exception handling and library
-management, reducing the amount of boilerplate code. If you cannot
-use ``AnsibleAWSModule`` as a base, you must document the reason and request an exception to this rule.
-
-Naming your module
-------------------
-
-Base the name of the module on the part of AWS that you actually use. (A good rule of thumb is to
-take whatever module you use with boto as a starting point).  Don't further abbreviate names - if
-something is a well known abbreviation of a major component of AWS (for example, VPC or ELB), that's fine, but
-don't create new ones independently.
-
-Unless the name of your service is quite unique, please consider using ``aws_`` as a prefix. For example ``aws_lambda``.
-
-Importing botocore and boto3
-----------------------------
-
-The ``ansible_collections.amazon.aws.plugins.module_utils.ec2`` module and
-``ansible_collections.amazon.aws.plugins.module_utils.core`` modules both
-automatically import boto3 and botocore.  If boto3 is missing from the system then the variable
-``HAS_BOTO3`` will be set to false.  Normally, this means that modules don't need to import
-boto3 directly. There is no need to check ``HAS_BOTO3`` when using AnsibleAWSModule
-as the module does that check:
-
-.. code-block:: python
-
-   from ansible_collections.amazon.aws.plugins.module_utils.core import AnsibleAWSModule
-   try:
-       import botocore
-   except ImportError:
-       pass  # handled by AnsibleAWSModule
-
-or:
-
-.. code-block:: python
-
-   from ansible.module_utils.basic import AnsibleModule
-   from ansible_collections.amazon.aws.plugins.module_utils.ec2 import HAS_BOTO3
-   try:
-       import botocore
-   except ImportError:
-       pass  # handled by imported HAS_BOTO3
-
-   def main():
-
-       if not HAS_BOTO3:
-           module.fail_json(msg='boto3 and botocore are required for this module')
-
-Supporting Module Defaults
---------------------------
-
-The existing AWS modules support using :ref:`module_defaults <module_defaults>` for common
-authentication parameters.  To do the same for your new module, add an entry for it in
-``meta/runtime.yml``.  These entries take the form of:
-
-.. code-block:: yaml
-
-  aws_module_name:
-  - aws
-
-Connecting to AWS
-=================
-
-AnsibleAWSModule provides the ``resource`` and ``client`` helper methods for obtaining boto3 connections.
-These handle some of the more esoteric connection options, such as security tokens and boto profiles.
-
-If using the basic AnsibleModule then you should use ``get_aws_connection_info`` and then ``boto3_conn``
-to connect to AWS as these handle the same range of connection options.
-
-These helpers also for missing profiles or a region not set when it needs to be, so you don't have to.
-
-An example of connecting to ec2 is shown below. Note that unlike boto there is no ``NoAuthHandlerFound``
-exception handling like in boto. Instead, an ``AuthFailure`` exception will be thrown when you use the
-connection. To ensure that authorization, parameter validation and permissions errors are all caught,
-you should catch ``ClientError`` and ``BotoCoreError`` exceptions with every boto3 connection call.
-See exception handling:
-
-.. code-block:: python
-
-   module.client('ec2')
-
-or for the higher level ec2 resource:
-
-.. code-block:: python
-
-   module.resource('ec2')
-
-
-An example of the older style connection used for modules based on AnsibleModule rather than AnsibleAWSModule:
-
-.. code-block:: python
-
-   region, ec2_url, aws_connect_params = get_aws_connection_info(module, boto3=True)
-   connection = boto3_conn(module, conn_type='client', resource='ec2', region=region, endpoint=ec2_url, **aws_connect_params)
-
-.. code-block:: python
-
-   region, ec2_url, aws_connect_params = get_aws_connection_info(module, boto3=True)
-   connection = boto3_conn(module, conn_type='client', resource='ec2', region=region, endpoint=ec2_url, **aws_connect_params)
-
-
-Common Documentation Fragments for Connection Parameters
---------------------------------------------------------
-
-There are two :ref:`common documentation fragments <module_docs_fragments>`
-that should be included into almost all AWS modules:
-
-* ``aws`` - contains the common boto connection parameters
-* ``ec2`` - contains the common region parameter required for many AWS modules
-
-These fragments should be used rather than re-documenting these properties to ensure consistency
-and that the more esoteric connection options are documented. For example:
-
-.. code-block:: python
-
-   DOCUMENTATION = '''
-   module: my_module
-   # some lines omitted here
-   requirements: [ 'botocore', 'boto3' ]
-   extends_documentation_fragment:
-       - amazon.aws.aws
-       - amazon.aws.ec2
-   '''
-
-Handling exceptions
-===================
-
-You should wrap any boto3 or botocore call in a try block. If an exception is thrown, then there
-are a number of possibilities for handling it.
-
-* Catch the general ``ClientError`` or look for a specific error code with
-    ``is_boto3_error_code``.
-* Use ``aws_module.fail_json_aws()`` to report the module failure in a standard way
-* Retry using AWSRetry
-* Use ``fail_json()`` to report the failure without using ``ansible_collections.amazon.aws.plugins.module_utils.core``
-* Do something custom in the case where you know how to handle the exception
-
-For more information on botocore exception handling see the `botocore error documentation <https://botocore.readthedocs.io/en/latest/client_upgrades.html#error-handling>`_.
-
-Using is_boto3_error_code
--------------------------
-
-To use ``ansible_collections.amazon.aws.plugins.module_utils.core.is_boto3_error_code`` to catch a single
-AWS error code, call it in place of ``ClientError`` in your except clauses. In
-this case, *only* the ``InvalidGroup.NotFound`` error code will be caught here,
-and any other error will be raised for handling elsewhere in the program.
-
-.. code-block:: python
-
-   try:
-       info = connection.describe_security_groups(**kwargs)
-   except is_boto3_error_code('InvalidGroup.NotFound'):
-       pass
-   do_something(info)  # do something with the info that was successfully returned
-
-Using fail_json_aws()
----------------------
-
-In the AnsibleAWSModule there is a special method, ``module.fail_json_aws()`` for nice reporting of
-exceptions.  Call this on your exception and it will report the error together with a traceback for
-use in Ansible verbose mode.
-
-You should use the AnsibleAWSModule for all new modules, unless not possible. If adding significant
-amounts of exception handling to existing modules, we recommend migrating the module to use AnsibleAWSModule
-(there are very few changes required to do this)
-
-.. code-block:: python
-
-   from ansible_collections.amazon.aws.plugins.module_utils.core import AnsibleAWSModule
-
-   # Set up module parameters
-   # module params code here
-
-   # Connect to AWS
-   # connection code here
-
-   # Make a call to AWS
-   name = module.params.get['name']
-   try:
-       result = connection.describe_frooble(FroobleName=name)
-   except (botocore.exceptions.BotoCoreError, botocore.exceptions.ClientError) as e:
-       module.fail_json_aws(e, msg="Couldn't obtain frooble %s" % name)
-
-Note that it should normally be acceptable to catch all normal exceptions here, however if you
-expect anything other than botocore exceptions you should test everything works as expected.
-
-If you need to perform an action based on the error boto3 returned, use the error code and the
-``is_boto3_error_code()`` helper.
-
-.. code-block:: python
-
-   # Make a call to AWS
-   name = module.params.get['name']
-   try:
-       result = connection.describe_frooble(FroobleName=name)
-   except is_boto3_error_code('FroobleNotFound'):
-       workaround_failure()  # This is an error that we can work around
-   except (botocore.exceptions.BotoCoreError, botocore.exceptions.ClientError) as e:  # pylint: disable=duplicate-except
-       module.fail_json_aws(e, msg="Couldn't obtain frooble %s" % name)
-
-using fail_json() and avoiding ansible_collections.amazon.aws.plugins.module_utils.core
----------------------------------------------------------------------------------------
-
-Boto3 provides lots of useful information when an exception is thrown so pass this to the user
-along with the message.
-
-.. code-block:: python
-
-   from ansible.module_utils.ec2 import HAS_BOTO3
-   try:
-       import botocore
-   except ImportError:
-       pass  # caught by imported HAS_BOTO3
-
-   # Connect to AWS
-   # connection code here
-
-   # Make a call to AWS
-   name = module.params.get['name']
-   try:
-       result = connection.describe_frooble(FroobleName=name)
-   except botocore.exceptions.ClientError as e:
-       module.fail_json(msg="Couldn't obtain frooble %s: %s" % (name, str(e)),
-                        exception=traceback.format_exc(),
-                        **camel_dict_to_snake_dict(e.response))
-
-Note: we use `str(e)` rather than `e.message` as the latter doesn't
-work with python3
-
-If you need to perform an action based on the error boto3 returned, use the error code.
-
-.. code-block:: python
-
-   # Make a call to AWS
-   name = module.params.get['name']
-   try:
-       result = connection.describe_frooble(FroobleName=name)
-   except botocore.exceptions.ClientError as e:
-       if e.response['Error']['Code'] == 'FroobleNotFound':
-           workaround_failure()  # This is an error that we can work around
-       else:
-           module.fail_json(msg="Couldn't obtain frooble %s: %s" % (name, str(e)),
-                            exception=traceback.format_exc(),
-                            **camel_dict_to_snake_dict(e.response))
-   except botocore.exceptions.BotoCoreError as e:
-       module.fail_json_aws(e, msg="Couldn't obtain frooble %s" % name)
-
-
-API throttling (rate limiting) and pagination
-=============================================
-
-For methods that return a lot of results, boto3 often provides
-`paginators <https://boto3.readthedocs.io/en/latest/guide/paginators.html>`_. If the method
-you're calling has ``NextToken`` or ``Marker`` parameters, you should probably
-check whether a paginator exists (the top of each boto3 service reference page has a link
-to Paginators, if the service has any). To use paginators, obtain a paginator object,
-call ``paginator.paginate`` with the appropriate arguments and then call ``build_full_result``.
-
-Any time that you are calling the AWS API a lot, you may experience API throttling,
-and there is an ``AWSRetry`` decorator that can be used to ensure backoff. Because
-exception handling could interfere with the retry working properly (as AWSRetry needs to
-catch throttling exceptions to work correctly), you'd need to provide a backoff function
-and then put exception handling around the backoff function.
-
-You can use ``exponential_backoff`` or ``jittered_backoff`` strategies - see
-the cloud ``module_utils`` ()/lib/ansible/module_utils/cloud.py)
-and `AWS Architecture blog <https://www.awsarchitectureblog.com/2015/03/backoff.html>`_ for more details.
-
-The combination of these two approaches is then:
-
-.. code-block:: python
-
-   @AWSRetry.exponential_backoff(retries=5, delay=5)
-   def describe_some_resource_with_backoff(client, **kwargs):
-        paginator = client.get_paginator('describe_some_resource')
-        return paginator.paginate(**kwargs).build_full_result()['SomeResource']
-
-   def describe_some_resource(client, module):
-       filters = ansible_dict_to_boto3_filter_list(module.params['filters'])
-       try:
-           return describe_some_resource_with_backoff(client, Filters=filters)
-       except botocore.exceptions.ClientError as e:
-           module.fail_json_aws(e, msg="Could not describe some resource")
-
-
-Prior to Ansible 2.10 if the underlying ``describe_some_resources`` API call threw
-a ``ResourceNotFound`` exception, ``AWSRetry`` would take this as a cue to retry until
-it is not thrown (this is so that when creating a resource, we can just retry until it
-exists).  This default was changed and it is now necessary to explicitly request
-this behaviour.  This can be done by using the ``catch_extra_error_codes``
-argument on the decorator.
-
-.. code-block:: python
-
-   @AWSRetry.exponential_backoff(retries=5, delay=5, catch_extra_error_codes=['ResourceNotFound'])
-   def describe_some_resource_retry_missing(client, **kwargs):
-        return client.describe_some_resource(ResourceName=kwargs['name'])['Resources']
-
-   def describe_some_resource(client, module):
-       name = module.params.get['name']
-       try:
-           return describe_some_resource_with_backoff(client, name=name)
-       except (botocore.exceptions.BotoCoreError, botocore.exceptions.ClientError) as e:
-           module.fail_json_aws(e, msg="Could not describe resource %s" % name)
-
-
-To make use of AWSRetry easier, it can now be wrapped around a client returned
-by ``AnsibleAWSModule``. any call from a client. To add retries to a client,
-create a client:
-
-.. code-block:: python
-
-   module.client('ec2', retry_decorator=AWSRetry.jittered_backoff(retries=10))
-
-Any calls from that client can be made to use the decorator passed at call-time
-using the `aws_retry` argument. By default, no retries are used.
-
-.. code-block:: python
-
-   ec2 = module.client('ec2', retry_decorator=AWSRetry.jittered_backoff(retries=10))
-   ec2.describe_instances(InstanceIds=['i-123456789'], aws_retry=True)
-
-   # equivalent with normal AWSRetry
-   @AWSRetry.jittered_backoff(retries=10)
-   def describe_instances(client, **kwargs):
-       return ec2.describe_instances(**kwargs)
-
-   describe_instances(module.client('ec2'), InstanceIds=['i-123456789'])
-
-The call will be retried the specified number of times, so the calling functions
-don't need to be wrapped in the backoff decorator.
-
-You can also use customization for ``retries``, ``delay`` and ``max_delay`` parameters used by
-``AWSRetry.jittered_backoff`` API using module params. You can take a look at
-the `cloudformation <cloudformation_module>` module for example.
-
-To make all Amazon modules uniform, prefix the module param with ``backoff_``, so ``retries`` becomes ``backoff_retries``
- and likewise with ``backoff_delay`` and ``backoff_max_delay``.
-
-Returning Values
-================
-
-When you make a call using boto3, you will probably get back some useful information that you
-should return in the module.  As well as information related to the call itself, you will also have
-some response metadata.  It is OK to return this to the user as well as they may find it useful.
-
-Boto3 returns all values CamelCased.  Ansible follows Python standards for variable names and uses
-snake_case. There is a helper function in module_utils/ec2.py called `camel_dict_to_snake_dict`
-that allows you to easily convert the boto3 response to snake_case.
-
-You should use this helper function and avoid changing the names of values returned by Boto3.
-E.g. if boto3 returns a value called 'SecretAccessKey' do not change it to 'AccessKey'.
-
-.. code-block:: python
-
-   # Make a call to AWS
-   result = connection.aws_call()
-
-   # Return the result to the user
-   module.exit_json(changed=True, **camel_dict_to_snake_dict(result))
-
-Dealing with IAM JSON policy
-============================
-
-If your module accepts IAM JSON policies then set the type to 'json' in the module spec. For
-example:
-
-.. code-block:: python
-
-   argument_spec.update(
-       dict(
-           policy=dict(required=False, default=None, type='json'),
-       )
-   )
-
-Note that AWS is unlikely to return the policy in the same order that is was submitted. Therefore,
-use the `compare_policies` helper function which handles this variance.
-
-`compare_policies` takes two dictionaries, recursively sorts and makes them hashable for comparison
-and returns True if they are different.
-
-.. code-block:: python
-
-   from ansible_collections.amazon.aws.plugins.module_utils.ec2 import compare_policies
-
-   import json
-
-   # some lines skipped here
-
-   # Get the policy from AWS
-   current_policy = json.loads(aws_object.get_policy())
-   user_policy = json.loads(module.params.get('policy'))
-
-   # Compare the user submitted policy to the current policy ignoring order
-   if compare_policies(user_policy, current_policy):
-       # Update the policy
-       aws_object.set_policy(user_policy)
-   else:
-       # Nothing to do
-       pass
-
-Dealing with tags
-=================
-
-AWS has a concept of resource tags. Usually the boto3 API has separate calls for tagging and
-untagging a resource.  For example, the ec2 API has a create_tags and delete_tags call.
-
-It is common practice in Ansible AWS modules to have a `purge_tags` parameter that defaults to
-true.
-
-The `purge_tags` parameter means that existing tags will be deleted if they are not specified by
-the Ansible task.
-
-There is a helper function `compare_aws_tags` to ease dealing with tags. It can compare two dicts
-and return the tags to set and the tags to delete.  See the Helper function section below for more
-detail.
-
-Helper functions
-================
-
-Along with the connection functions in Ansible ec2.py module_utils, there are some other useful
-functions detailed below.
-
-camel_dict_to_snake_dict
-------------------------
-
-boto3 returns results in a dict.  The keys of the dict are in CamelCase format. In keeping with
-Ansible format, this function will convert the keys to snake_case.
-
-``camel_dict_to_snake_dict`` takes an optional parameter called ``ignore_list`` which is a list of
-keys not to convert (this is usually useful for the ``tags`` dict, whose child keys should remain with
-case preserved)
-
-Another optional parameter is ``reversible``. By default, ``HTTPEndpoint`` is converted to ``http_endpoint``,
-which would then be converted by ``snake_dict_to_camel_dict`` to ``HttpEndpoint``.
-Passing ``reversible=True`` converts HTTPEndpoint to ``h_t_t_p_endpoint`` which converts back to ``HTTPEndpoint``.
-
-snake_dict_to_camel_dict
-------------------------
-
-`snake_dict_to_camel_dict` converts snake cased keys to camel case. By default, because it was
-first introduced for ECS purposes, this converts to dromedaryCase. An optional
-parameter called `capitalize_first`, which defaults to `False`, can be used to convert to CamelCase.
-
-ansible_dict_to_boto3_filter_list
----------------------------------
-
-Converts a an Ansible list of filters to a boto3 friendly list of dicts.  This is useful for any
-boto3 `_facts` modules.
-
-boto_exception
---------------
-
-Pass an exception returned from boto or boto3, and this function will consistently get the message from the exception.
-
-Deprecated: use `AnsibleAWSModule`'s `fail_json_aws` instead.
-
-
-boto3_tag_list_to_ansible_dict
-------------------------------
-
-Converts a boto3 tag list to an Ansible dict. Boto3 returns tags as a list of dicts containing keys
-called 'Key' and 'Value' by default.  This key names can be overridden when calling the function.
-For example, if you have already camel_cased your list of tags you may want to pass lowercase key
-names instead, in other words, 'key' and 'value'.
-
-This function converts the list in to a single dict where the dict key is the tag key and the dict
-value is the tag value.
-
-ansible_dict_to_boto3_tag_list
-------------------------------
-
-Opposite of above. Converts an Ansible dict to a boto3 tag list of dicts. You can again override
-the key names used if 'Key' and 'Value' is not suitable.
-
-get_ec2_security_group_ids_from_names
--------------------------------------
-
-Pass this function a list of security group names or combination of security group names and IDs
-and this function will return a list of IDs.  You should also pass the VPC ID if known because
-security group names are not necessarily unique across VPCs.
-
-compare_policies
-----------------
-
-Pass two dicts of policies to check if there are any meaningful differences and returns true
-if there are. This recursively sorts the dicts and makes them hashable before comparison.
-
-This method should be used any time policies are being compared so that a change in order
-doesn't result in unnecessary changes.
-
-compare_aws_tags
-----------------
-
-Pass two dicts of tags and an optional purge parameter and this function will return a dict
-containing key pairs you need to modify and a list of tag key names that you need to remove.  Purge
-is True by default.  If purge is False then any existing tags will not be modified.
-
-This function is useful when using boto3 'add_tags' and 'remove_tags' functions. Be sure to use the
-other helper function `boto3_tag_list_to_ansible_dict` to get an appropriate tag dict before
-calling this function. Since the AWS APIs are not uniform (for example, EC2 is different from Lambda) this will work
-without modification for some (Lambda) and others may need modification before using these values
-(such as EC2, with requires the tags to unset to be in the form `[{'Key': key1}, {'Key': key2}]`).
-
-Integration Tests for AWS Modules
-=================================
-
-All new AWS modules should include integration tests to ensure that any changes in AWS APIs that
-affect the module are detected. At a minimum this should cover the key API calls and check the
-documented return values are present in the module result.
-
-For general information on running the integration tests see the :ref:`Integration Tests page of the
-Module Development Guide <testing_integration>`, especially the section on configuration for cloud tests.
-
-The integration tests for your module should be added in `test/integration/targets/MODULE_NAME`.
-
-You must also have a aliases file in `test/integration/targets/MODULE_NAME/aliases`. This file serves
-two purposes. First indicates it's in an AWS test causing the test framework to make AWS credentials
-available during the test run. Second putting the test in a test group causing it to be run in the
-continuous integration build.
-
-Tests for new modules should be added to the same group as existing AWS tests. In general just copy
-an existing aliases file such as the `aws_s3 tests aliases file <https://github.com/ansible-collections/amazon.aws/blob/master/tests/integration/targets/aws_s3/aliases>`_.
-
-AWS Credentials for Integration Tests
--------------------------------------
-
-The testing framework handles running the test with appropriate AWS credentials, these are made available
-to your test in the following variables:
-
-* `aws_region`
-* `aws_access_key`
-* `aws_secret_key`
-* `security_token`
-
-So all invocations of AWS modules in the test should set these parameters. To avoid duplicating these
-for every call, it's preferable to use :ref:`module_defaults <module_defaults>`. For example:
-
-.. code-block:: yaml
-
-   - name: set connection information for aws modules and run tasks
-     module_defaults:
-       group/aws:
-         aws_access_key: "{{ aws_access_key }}"
-         aws_secret_key: "{{ aws_secret_key }}"
-         security_token: "{{ security_token | default(omit) }}"
-         region: "{{ aws_region }}"
-
-     block:
-
-     - name: Do Something
-       ec2_instance:
-         ... params ...
-
-     - name: Do Something Else
-       ec2_instance:
-         ... params ...
-
-AWS Permissions for Integration Tests
--------------------------------------
-
-As explained in the :ref:`Integration Test guide <testing_integration>`
-there are defined IAM policies in `mattclay/aws-terminator <https://github.com/mattclay/aws-terminator>`_ that contain the necessary permissions
-to run the AWS integration test.
-
-If your module interacts with a new service or otherwise requires new permissions, tests will fail when you submit a pull request and the
-`Ansibullbot <https://github.com/ansible/ansibullbot/blob/master/ISSUE_HELP.md>`_ will tag your PR as needing revision.
-We do not automatically grant additional permissions to the roles used by the continuous integration builds.
-You will need to raise a Pull Request against `mattclay/aws-terminator <https://github.com/mattclay/aws-terminator>`_ to add them.
-
-If your PR has test failures, check carefully to be certain the failure is only due to the missing permissions. If you've ruled out other sources of failure, add a comment with the `ready_for_review`
-tag and explain that it's due to missing permissions.
-
-Your pull request cannot be merged until the tests are passing. If your pull request is failing due to missing permissions,
-you must collect the minimum IAM permissions required to
-run the tests.
-
-There are two ways to figure out which IAM permissions you need for your PR to pass:
-
-* Start with the most permissive IAM policy, run the tests to collect information about which resources your tests actually use, then construct a policy based on that output. This approach only works on modules that use `AnsibleAWSModule`.
-* Start with the least permissive IAM policy, run the tests to discover a failure, add permissions for the resource that addresses that failure, then repeat. If your module uses `AnsibleModule` instead of `AnsibleAWSModule`, you must use this approach.
-
-To start with the most permissive IAM policy:
-
-1) `Create an IAM policy <https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html#access_policies_create-start>`_ that allows all actions (set ``Action`` and ``Resource`` to ``*```).
-2) Run your tests locally with this policy. On AnsibleAWSModule-based modules, the ``debug_botocore_endpoint_logs`` option is automatically set to ``yes``, so you should see a list of AWS ACTIONS after the PLAY RECAP showing all the permissions used. If your tests use a boto/AnsibleModule module, you must start with the least permissive policy (see below).
-3) Modify your policy to allow only the actions your tests use. Restrict account, region, and prefix where possible. Wait a few minutes for your policy to update.
-4) Run the tests again with a user or role that allows only the new policy.
-5) If the tests fail, troubleshoot (see tips below), modify the policy, run the tests again, and repeat the process until the tests pass with a restrictive policy.
-6) Open a pull request proposing the minimum required policy to the `CI policies <https://github.com/mattclay/aws-terminator/tree/master/aws/policy>`_.
-
-To start from the least permissive IAM policy:
-
-1) Run the integration tests locally with no IAM permissions.
-2) Examine the error when the tests reach a failure.
-    a) If the error message indicates the action used in the request, add the action to your policy.
-    b) If the error message does not indicate the action used in the request:
-        - Usually the action is a CamelCase version of the method name - for example, for an ec2 client the method `describe_security_groups` correlates to the action `ec2:DescribeSecurityGroups`.
-        - Refer to the documentation to identify the action.
-    c) If the error message indicates the resource ARN used in the request, limit the action to that resource.
-    d) If the error message does not indicate the resource ARN used:
-        - Determine if the action can be restricted to a resource by examining the documentation.
-        - If the action can be restricted, use the documentation to construct the ARN and add it to the policy.
-3) Add the action or resource that caused the failure to `an IAM policy <https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html#access_policies_create-start>`_. Wait a few minutes for your policy to update.
-4) Run the tests again with this policy attached to your user or role.
-5) If the tests still fail at the same place with the same error you will need to troubleshoot (see tips below). If the first test passes, repeat steps 2 and 3 for the next error. Repeat the process until the tests pass with a restrictive policy.
-6) Open a pull request proposing the minimum required policy to the `CI policies <https://github.com/mattclay/aws-terminator/tree/master/aws/policy>`_.
-
-Troubleshooting IAM policies
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-- When you make changes to a policy, wait a few minutes for the policy to update before re-running the tests.
-- Use the `policy simulator <https://policysim.aws.amazon.com/>`_ to verify that each action (limited by resource when applicable) in your policy is allowed.
-- If you're restricting actions to certain resources, replace resources temporarily with `*`. If the tests pass with wildcard resources, there is a problem with the resource definition in your policy.
-- If the initial troubleshooting above doesn't provide any more insight, AWS may be using additional undisclosed resources and actions.
-- Examine the AWS FullAccess policy for the service for clues.
-- Re-read the AWS documentation, especially the list of `Actions, Resources and Condition Keys <https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_actions-resources-contextkeys.html>`_ for the various AWS services.
-- Look at the `cloudonaut <https://iam.cloudonaut.io>`_ documentation as a troubleshooting cross-reference.
-- Use a search engine.
-- Ask in the #ansible-aws chat channel (using Matrix at ansible.im or using IRC at `irc.libera.chat <https://libera.chat/>`_).
-
-Unsupported Integration tests
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-There are a limited number of reasons why it may not be practical to run integration
-tests for a module within CI.  Where these apply you should add the keyword
-`unsupported` to the aliases file in `test/integration/targets/MODULE_NAME/aliases`.
-
-Some cases where tests should be marked as unsupported:
-1) The tests take longer than 10 or 15 minutes to complete
-2) The tests create expensive resources
-3) The tests create inline policies
-4) The tests require the existence of external resources
-5) The tests manage Account level security policies such as the password policy or AWS Organizations.
-
-Where one of these reasons apply you should open a pull request proposing the minimum required policy to the
-`unsupported test policies <https://github.com/mattclay/aws-terminator/tree/master/hacking/aws_config/test_policies>`_.
-
-Unsupported integration tests will not be automatically run by CI.  However, the
-necessary policies should be available so that the tests can be manually run by
-someone performing a PR review or writing a patch.
+This guide has moved to :ref:`ansible_collections.amazon.aws.docsite.dev_guide_intro`.

docs/docsite/rst/dev_guide/platforms/ovirt_dev_guide.rst

@@ -3,218 +3,5 @@
 oVirt Ansible Modules
 =====================
 
-The set of modules for interacting with oVirt/RHV are currently part of the community.general collection (on `Galaxy <https://galaxy.ansible.com/community/general>`_, source code `repository <https://github.com/ansible-collections/community.general/tree/main/plugins/modules/cloud/ovirt>`_). This document serves as developer coding guidelines for creating oVirt/RHV modules.
 
-.. contents::
-   :local:
-
-Naming
-------
-
--  All modules should start with an ``ovirt_`` prefix.
--  All modules should be named after the resource it manages in singular
-   form.
--  All modules that gather information should have a ``_info``
-   suffix.
-
-Interface
----------
-
--  Every module should return the ID of the resource it manages.
--  Every module should return the dictionary of the resource it manages.
--  Never change the name of the parameter, as we guarantee backward
-   compatibility. Use aliases instead.
--  If a parameter can't achieve idempotency for any reason, please
-   document it.
-
-Interoperability
-----------------
-
--  All modules should work against all minor versions of
-   version 4 of the API. Version 3 of the API is not supported.
-
-Libraries
----------
-
--  All modules should use ``ovirt_full_argument_spec`` or
-   ``ovirt_info_full_argument_spec`` to pick up the standard input (such
-   as auth and ``fetch_nested``).
--  All modules should use ``extends_documentation_fragment``: ovirt to go
-   along with ``ovirt_full_argument_spec``.
--  All info modules should use ``extends_documentation_fragment``:
-   ``ovirt_info`` to go along with ``ovirt_info_full_argument_spec``.
--  Functions that are common to all modules should be implemented in the
-   ``module_utils/ovirt.py`` file, so they can be reused.
--  Python SDK version 4 must be used.
-
-New module development
-----------------------
-
-Please read :ref:`developing_modules`,
-first to know what common properties, functions and features every module must
-have.
-
-In order to achieve idempotency of oVirt entity attributes, a helper class
-was created. The first thing you need to do is to extend this class and override a few
-methods:
-
-.. code:: python
-
-    try:
-        import ovirtsdk4.types as otypes
-    except ImportError:
-        pass
-
-    from ansible.module_utils.ovirt import (
-        BaseModule,
-        equal
-    )
-
-    class ClustersModule(BaseModule):
-
-        # The build method builds the entity we want to create.
-        # Always be sure to build only the parameters the user specified
-        # in their yaml file, so we don't change the values which we shouldn't
-        # change. If you set the parameter to None, nothing will be changed.
-        def build_entity(self):
-            return otypes.Cluster(
-                name=self.param('name'),
-                comment=self.param('comment'),
-                description=self.param('description'),
-            )
-
-        # The update_check method checks if the update is needed to be done on
-        # the entity. The equal method doesn't check the values which are None,
-        # which means it doesn't check the values which user didn't set in yaml.
-        # All other values are checked and if there is found some mismatch,
-        # the update method is run on the entity, the entity is build by
-        # 'build_entity' method. You don't have to care about calling the update,
-        # it's called behind the scene by the 'BaseModule' class.
-        def update_check(self, entity):
-            return (
-                equal(self.param('comment'), entity.comment)
-                and equal(self.param('description'), entity.description)
-            )
-
-The code above handle the check if the entity should be updated, so we
-don't update the entity if not needed and also it construct the needed
-entity of the SDK.
-
-.. code:: python
-
-    from ansible.module_utils.basic import AnsibleModule
-    from ansible.module_utils.ovirt import (
-        check_sdk,
-        create_connection,
-        ovirt_full_argument_spec,
-    )
-
-    # This module will support two states of the cluster,
-    # either it will be present or absent. The user can
-    # specify three parameters: name, comment and description,
-    # The 'ovirt_full_argument_spec' function, will merge the
-    # parameters created here with some common one like 'auth':
-    argument_spec = ovirt_full_argument_spec(
-        state=dict(
-            choices=['present', 'absent'],
-            default='present',
-        ),
-        name=dict(default=None, required=True),
-        description=dict(default=None),
-        comment=dict(default=None),
-    )
-
-    # Create the Ansible module, please always implement the
-    # feature called 'check_mode', for 'create', 'update' and
-    # 'delete' operations it's implemented by default in BaseModule:
-    module = AnsibleModule(
-        argument_spec=argument_spec,
-        supports_check_mode=True,
-    )
-
-    # Check if the user has Python SDK installed:
-    check_sdk(module)
-
-    try:
-        auth = module.params.pop('auth')
-
-        # Create the connection to the oVirt engine:
-        connection = create_connection(auth)
-
-        # Create the service which manages the entity:
-        clusters_service = connection.system_service().clusters_service()
-
-        # Create the module which will handle create, update and delete flow:
-        clusters_module = ClustersModule(
-            connection=connection,
-            module=module,
-            service=clusters_service,
-        )
-
-        # Check the state and call the appropriate method:
-        state = module.params['state']
-        if state == 'present':
-            ret = clusters_module.create()
-        elif state == 'absent':
-            ret = clusters_module.remove()
-
-        # The return value of the 'create' and 'remove' method is dictionary
-        # with the 'id' of the entity we manage and the type of the entity
-        # with filled in attributes of the entity. The 'change' status is
-        # also returned by those methods:
-        module.exit_json(**ret)
-    except Exception as e:
-        # Modules can't raises exception, it always must exit with
-        # 'module.fail_json' in case of exception. Always use
-        # 'exception=traceback.format_exc' for debugging purposes:
-        module.fail_json(msg=str(e), exception=traceback.format_exc())
-    finally:
-        # Logout only in case the user passed the 'token' in 'auth'
-        # parameter:
-        connection.close(logout=auth.get('token') is None)
-
-If your module must support action handling (for example,
-virtual machine start) you must ensure that you handle the states of the
-virtual machine correctly, and document the behavior of the
-module:
-
-.. code:: python
-
-        if state == 'running':
-            ret = vms_module.action(
-                action='start',
-                post_action=vms_module._post_start_action,
-                action_condition=lambda vm: (
-                    vm.status not in [
-                        otypes.VmStatus.MIGRATING,
-                        otypes.VmStatus.POWERING_UP,
-                        otypes.VmStatus.REBOOT_IN_PROGRESS,
-                        otypes.VmStatus.WAIT_FOR_LAUNCH,
-                        otypes.VmStatus.UP,
-                        otypes.VmStatus.RESTORING_STATE,
-                    ]
-                ),
-                wait_condition=lambda vm: vm.status == otypes.VmStatus.UP,
-                # Start action kwargs:
-                use_cloud_init=use_cloud_init,
-                use_sysprep=use_sysprep,
-                # ...
-            )
-
-As you can see from the preceding example, the ``action`` method accepts the ``action_condition`` and
-``wait_condition``, which are methods which accept the virtual machine
-object as a parameter, so you can check whether the virtual
-machine is in a proper state before the action. The rest of the
-parameters are for the ``start`` action. You may also handle pre-
-or post- action tasks by defining ``pre_action`` and ``post_action``
-parameters.
-
-Testing
--------
-
--  Integration testing is currently done in oVirt's CI system
-   `on Jenkins <https://jenkins.ovirt.org/view/All/job/ovirt-system-tests_ansible-suite-master/>`__
-   and
-   `on GitHub <https://github.com/oVirt/ovirt-system-tests/tree/master/ansible-suite-master/>`__.
--  Please consider using these integration tests if you create a new module or add a new feature to an existing
-   module.
+See the `ovirt.ovirt collection documentation <https://github.com/oVirt/ovirt-ansible-collection/blob/master/README-developers.md>`_ for details on how to contribute to this collection.

docs/docsite/rst/dev_guide/platforms/vmware_guidelines.rst

@@ -1,262 +1,7 @@
 .. _VMware_module_development:
 
-****************************************
+******************************************************
 Guidelines for VMware module development
-****************************************
+******************************************************
 
-The Ansible VMware collection (on `Galaxy <https://galaxy.ansible.com/community/vmware>`_, source code `repository <https://github.com/ansible-collections/community.vmware>`_) is maintained by the VMware Working Group. For more information see the `team community page <https://github.com/ansible/community/wiki/VMware>`_.
-
-.. contents::
-   :local:
-
-Testing with govcsim
-====================
-
-Most of the existing modules are covered by functional tests. The tests are located `here <https://github.com/ansible-collections/community.vmware/tree/main/tests/integration/targets>`_.
-
-By default, the tests run against a vCenter API simulator called `govcsim <https://github.com/vmware/govmomi/tree/master/vcsim>`_. ``ansible-test`` will automatically pull a `govcsim container <https://quay.io/repository/ansible/vcenter-test-container>`_ and use it to set-up the test environment.
-
-You can trigger the test of a module manually with the ``ansible-test`` command. For example, to trigger ``vcenter_folder`` tests:
-
-.. code-block:: shell
-
-    source hacking/env-setup
-    ansible-test integration --python 3.7 vcenter_folder
-
-``govcsim`` is handy because it is much faster than a regular test environment. However, ``govcsim`` does not
-support all the ESXi or vCenter features.
-
-.. note::
-
-   Do not confuse ``govcsim`` with ``vcsim``. ``vcsim`` is an older and outdated version of vCenter simulator, whereas ``govcsim`` is new and written in Go language.
-
-Testing with your own infrastructure
-====================================
-
-You can also target a regular VMware environment. This paragraph explains step by step how you can run the test-suite yourself.
-
-Requirements
-------------
-
-- 2 ESXi hosts (6.5 or 6.7)
-   - with 2 NIC, the second ones should be available for the test
-- a VCSA host
-- a NFS server
-- Python dependencies:
-    - `pyvmomi <https://github.com/vmware/pyvmomi/tree/master/pyVmomi>`_
-    - `requests <https://2.python-requests.org/en/master/>`_
-
-If you want to deploy your test environment in a hypervisor, both `VMware or Libvirt <https://github.com/goneri/vmware-on-libvirt>`_ work well.
-
-NFS server configuration
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-Your NFS server must expose the following directory structure:
-
-.. code-block:: shell
-
-    $ tree /srv/share/
-    /srv/share/
-    ├── isos
-    │   ├── base.iso
-    │   ├── centos.iso
-    │   └── fedora.iso
-    └── vms
-    2 directories, 3 files
-
-On a Linux system, you can expose the directory over NFS with the following export file:
-
-.. code-block:: shell
-
-    $ cat /etc/exports
-    /srv/share  192.168.122.0/255.255.255.0(rw,anonuid=1000,anongid=1000)
-
-.. note::
-
-    With this configuration all the new files will be owned by the user with the UID and GID 1000/1000.
-    Adjust the configuration to match your user's UID/GID.
-
-The service can be enabled with:
-
-.. code-block:: shell
-
-   $ sudo systemctl enable --now nfs-server
-
-
-Configure your installation
----------------------------
-
-Prepare a configuration file that describes your set-up. The file
-should be called :file:`test/integration/cloud-config-vcenter.ini` and based on
-:file:`test/lib/ansible_test/config/cloud-config-vcenter.ini.template`. For instance, if you have deployed your lab with
-`vmware-on-libvirt <https://github.com/goneri/vmware-on-libvirt>`_:
-
-.. code-block:: ini
-
-    [DEFAULT]
-    vcenter_username: administrator@vsphere.local
-    vcenter_password: !234AaAa56
-    vcenter_hostname: vcenter.test
-    vmware_validate_certs: false
-    esxi1_hostname: esxi1.test
-    esxi1_username: root
-    esxi1_password: root
-    esxi2_hostname: test2.test
-    esxi2_username: root
-    esxi2_password: root
-
-Using an HTTP proxy
--------------------
-Hosting test infrastructure behind an HTTP proxy is supported. You can specify the location of the proxy server with the two extra keys:
-
-.. code-block:: ini
-
-    vmware_proxy_host: esxi1-gw.ws.testing.ansible.com
-    vmware_proxy_port: 11153
-
-In addition, you may need to adjust the variables of the following `var files <https://github.com/ansible-collections/community.vmware/tree/main/tests/integration/targets/prepare_vmware_tests/vars>`_ to match the configuration of your lab. If you use vmware-on-libvirt to prepare your lab, you do not have anything to change.
-
-Run the test-suite
-------------------
-
-Once your configuration is ready, you can trigger a run with the following command:
-
-.. code-block:: shell
-
-    source hacking/env-setup
-    VMWARE_TEST_PLATFORM=static ansible-test integration --python 3.7 vmware_host_firewall_manager
-
-``vmware_host_firewall_manager`` is the name of the module to test.
-
-``vmware_guest`` is much larger than any other test role and is rather slow. You can enable or disable some of its test playbooks in `main.yml <https://github.com/ansible-collections/community.vmware/tree/main/tests/integration/targets/vmware_guest/defaults/main.yml>`_.
-
-
-Unit-test
-=========
-
-The VMware modules have limited unit-test coverage. You can run the test suite with the
-following commands:
-
-.. code-block:: shell
-
-    source hacking/env-setup
-    ansible-test units --venv --python 3.7 '.*vmware.*'
-
-Code style and best practice
-============================
-
-datacenter argument with ESXi
------------------------------
-
-The ``datacenter`` parameter should not use ``ha-datacenter`` by default. This is because the user may
-not realize that Ansible silently targets the wrong data center.
-
-esxi_hostname should not be mandatory
--------------------------------------
-
-Depending upon the functionality provided by ESXi or vCenter, some modules can seamlessly work with both. In this case,
-``esxi_hostname`` parameter should be optional.
-
-.. code-block:: python
-
-    if self.is_vcenter():
-        esxi_hostname = module.params.get('esxi_hostname')
-        if not esxi_hostname:
-            self.module.fail_json("esxi_hostname parameter is mandatory")
-        self.host = self.get_all_host_objs(cluster_name=cluster_name, esxi_host_name=esxi_hostname)[0]
-    else:
-        self.host = find_obj(self.content, [vim.HostSystem], None)
-    if self.host is None:
-        self.module.fail_json(msg="Failed to find host system.")
-
-Example should use the fully qualified collection name (FQCN)
--------------------------------------------------------------
-
-Use FQCN for examples within module documentation. For instance, you should use ``community.vmware.vmware_guest`` instead of just
-``vmware_guest``.
-
-This way, the examples do not depend on the ``collections`` directive of the
-playbook.
-
-Functional tests
-----------------
-
-Writing new tests
-^^^^^^^^^^^^^^^^^
-
-If you are writing a new collection of integration tests, there are a few VMware-specific things to note beyond
-the standard Ansible :ref:`integration testing<testing_integration>` process.
-
-The test-suite uses a set of common, pre-defined vars located `in prepare_vmware_tests <https://github.com/ansible-collections/community.vmware/tree/main/tests/integration/targets/test/integration/targets/prepare_vmware_tests/>`_ role.
-The resources defined there are automatically created by importing that role at the start of your test:
-
-.. code-block:: yaml
-
-  - import_role:
-      name: prepare_vmware_tests
-    vars:
-      setup_datacenter: true
-
-This will give you a ready to use cluster, datacenter, datastores, folder, switch, dvswitch, ESXi hosts, and VMs.
-
-No need to create too much resources
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Most of the time, it's not necessary to use ``with_items`` to create multiple resources. By avoiding it,
-you speed up the test execution and you simplify the clean up afterwards.
-
-VM names should be predictable
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-If you need to create a new VM during your test, you can use ``test_vm1``, ``test_vm2`` or ``test_vm3``. This
-way it will be automatically clean up for you.
-
-Avoid the common boiler plate code in your test playbook
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-From Ansible 2.10, the test suite uses `modules_defaults`. This module
-allow us to preinitialize the following default keys of the VMware modules:
-
-- hostname
-- username
-- password
-- validate_certs
-
-For example, the following block:
-
-.. code-block:: yaml
-
-    - name: Add a VMware vSwitch
-      community.vmware.vmware_vswitch:
-        hostname: '{{ vcenter_hostname }}'
-        username: '{{ vcenter_username }}'
-        password: '{{ vcenter_password }}'
-        validate_certs: 'no'
-        esxi_hostname: 'esxi1'
-        switch_name: "boby"
-        state: present
-
-should be simplified to just:
-
-.. code-block:: yaml
-
-    - name: Add a VMware vSwitch
-      community.vmware.vmware_vswitch:
-        esxi_hostname: 'esxi1'
-        switch_name: "boby"
-        state: present
-
-
-Typographic convention
-======================
-
-Nomenclature
-------------
-
-We try to enforce the following rules in our documentation:
-
-- VMware, not VMWare or vmware
-- ESXi, not esxi or ESXI
-- vCenter, not vcenter or VCenter
-
-We also refer to vcsim's Go implementation with ``govcsim``. This to avoid any confusion with the outdated implementation.
+This guide has moved to :ref:`ansible_collections.community.vmware.docsite.vmware_ansible_devguide`.

docs/docsite/rst/dev_guide/platforms/vmware_rest_guidelines.rst

@@ -4,108 +4,4 @@
 Guidelines for VMware REST module development
 *********************************************
 
-The Ansible VMware REST collection (on `Galaxy <https://galaxy.ansible.com/vmware/vmware_rest>`_, source code `repository <https://github.com/ansible-collections/vmware.vmware_rest>`_) is maintained by Red Hat and the community.
-
-.. contents::
-   :local:
-
-Contribution process
-====================
-
-The modules of the vmware_rest collection are autogenerated by another tool called `vmware_rest_code_generator <https://github.com/ansible-collections/vmware_rest_code_generator>`.
-
-If you would like to contribute a change, we would appreciate if you:
-
-- submit a Github Pull Request (PR) against the vmware_rest_code_generator project
-- but also ensure the generated modules are compliant with our quality criteria.
-
-Requirements
-============
-
-You will need:
-
-- Python 3.6 or greater
-- the `tox <https://tox.readthedocs.io/en/latest/install.html>` command
-
-
-vmware_rest_code_generator
-==========================
-
-Your contribution should follow the coding style of `Black <https://github.com/psf/black>`.
-To run the code formatter, just run:
-
-.. code-block:: shell
-
-    tox -e black
-
-To regenerate the vmware_rest collection, you can use the following commands:
-
-.. code-block:: shell
-
-    tox -e refresh_modules -- --target-dir ~/.ansible/collections/ansible_collections/vmware/vmware_rest
-
-If you also want to update the EXAMPLE section of the modules, run:
-
-.. code-block:: shell
-
-    tox -e refresh_examples -- --target-dir ~/.ansible/collections/ansible_collections/vmware/vmware_rest
-
-Testing with ansible-test
-=========================
-
-All the modules are covered by a functional test. The tests are located in the :file:`tests/integration/targets/`.
-
-To run the tests, you will need a vcenter instance and an ESXi.
-
-black code formatter
-^^^^^^^^^^^^^^^^^^^^
-
-We follow the coding style of `Black <https://github.com/psf/black>`.
-You can run the code formatter with the following command.
-
-
-.. code-block:: shell
-
-    tox -e black
-
-sanity tests
-^^^^^^^^^^^^
-
-Here we use Python 3.8, the minimal version is 3.6.
-
-.. code-block:: shell
-
-    tox -e black
-    ansible-test sanity --debug --requirements --local --skip-test future-import-boilerplate --skip-test metaclass-boilerplate --python 3.8 -vvv
-
-
-integration tests
-^^^^^^^^^^^^^^^^^
-
-These tests should be run against your test environment.
-
-..warning:: The test suite will delete all the existing DC from your test environment. 
-
-First, prepare a configuration file, we call it :file:`/tmp/inventory-vmware_rest` in
-this example:
-
-.. code-block:: ini
-
-    [vmware_rest]
-    localhost ansible_connection=local ansible_python_interpreter=python
-    
-    [vmware_rest:vars]
-    vcenter_hostname=vcenter.test
-    vcenter_username=administrator@vsphere.local
-    vcenter_password=kLRy|FXwZSHXW0w?Q:sO
-    esxi1_hostname=esxi1.test
-    esxi1_username=zuul
-    esxi1_password=f6QYNi65k05kv8m56
-
-
-To run the tests, use the following command. You may want to adjust the Python version.
-
-.. code-block:: shell
-
-    ansible-test network-integration --diff --no-temp-workdir --python 3.8 --inventory /tmp/inventory-vmware_rest zuul/
-
+This guide has moved to :ref:`ansible_collections.vmware.vmware_rest.docsite.vmware_rest_devguide`.

docs/docsite/rst/dev_guide/shared_snippets/licensing.txt

@@ -7,3 +7,6 @@
       * All other ``module_utils`` must be licensed under BSD, so GPL-licensed third-party and Galaxy modules can use them.
       * If there's doubt about the appropriate license for a file in ``module_utils``, the Ansible Core Team will decide during an Ansible Core Community Meeting.
    * All other files shipped with Ansible, including all modules, must be licensed under the GPL license (GPLv3 or later).
+   * Existing license requirements still apply to content in ansible/ansible (ansible-core).
+   * Content that was previously in ansible/ansible or a collection and has moved to a new collection must retain the license it had in its prior repository.
+   * Copyright entries by previous committers must also be kept in any moved files.