Update Ansible release version to v2.11.2.post0.

(cherry picked from commit 58d8397771)

.azure-pipelines/azure-pipelines.yml

@@ -36,7 +36,7 @@ variables:
 resources:
   containers:
     - container: default
-      image: quay.io/ansible/azure-pipelines-test-container:1.8.0
+      image: quay.io/ansible/azure-pipelines-test-container:1.9.0
 
 pool: Standard
 

.azure-pipelines/scripts/publish-codecov.sh

@@ -7,7 +7,7 @@ set -o pipefail -eu
 
 output_path="$1"
 
-curl --silent --show-error https://codecov.io/bash > codecov.sh
+curl --silent --show-error https://ansible-ci-files.s3.us-east-1.amazonaws.com/codecov/codecov.sh > codecov.sh
 
 for file in "${output_path}"/reports/coverage*.xml; do
     name="${file}"

.gitattributes

@@ -1,2 +1 @@
 .github/ export-ignore
-hacking/ export-ignore

Makefile

@@ -11,7 +11,7 @@
 #   make deb ------------------ produce a DEB
 #   make docs ----------------- rebuild the manpages (results are checked in)
 #   make gettext -------------- produce POT files for docs
-#   make generate-po ---------- generate language specfic po file
+#   make generate-po ---------- generate language specific po file
 #   make needs-translation ---- generate list of file with unstranlated or fuzzy string for a specific language
 #   make tests ---------------- run the tests (see https://docs.ansible.com/ansible/devel/dev_guide/testing_units.html for requirements)
 
@@ -34,7 +34,7 @@ else
 ASCII2MAN = @echo "ERROR: rst2man from docutils command is not installed but is required to build $(MANPAGES)" && exit 1
 endif
 
-PYTHON=python
+PYTHON ?= python
 GENERATE_CLI = hacking/build-ansible.py generate-man
 
 # fetch version from project release.py as single source-of-truth

changelogs/CHANGELOG-v2.11.rst

@@ -5,105 +5,97 @@ ansible-core 2.11 "Hey Hey, What Can I Do" Release Notes
 .. contents:: Topics
 
 
-v2.11.0b4
-=========
+v2.11.2
+=======
 
 Release Summary
 ---------------
 
-| Release Date: 2021-03-29
+| Release Date: 2021-06-22
+| `Porting Guide <https://docs.ansible.com/ansible/devel/porting_guides.html>`__
+
+
+Security Fixes
+--------------
+
+- templating engine fix for not preserving usnafe status when trying to preserve newlines. CVE-2021-3583
+
+Bugfixes
+--------
+
+- AnsibleModule.set_mode_if_different - don't check file existence when check_mode is activated (https://github.com/ansible/ansible/issues/61185).
+- Apply ``display_failed_stderr`` callback option on loop item results. (https://github.com/ansible/ansible/issues/74864)
+- Avoid task executor from ending early as vars can come from delegated to host.
+- ansible-pull - update documentation for ``--directory`` option to clarify path must be absolute.
+- config, ensure 'quoted' lists from ini or env do not take the quotes literally as part of the list item.
+- gather_facts, package, service - fix using module_defaults for the modules in addition to the action plugins. (https://github.com/ansible/ansible/issues/72918)
+- psrp - Always cleanup the last run pipeline if a second pipeline is invoked to avoid violating any resource limits.
+- psrp - Fix error when resetting a connection that was initialised but not connected - (https://github.com/ansible/ansible/issues/74092).
+- psrp - Try to clean up any server-side resources when resetting a connection.
+- roles - make sure argspec validation task is tagged with ``always`` (https://github.com/ansible/ansible/pull/74994).
+- slurp - Fix error messages for unreadable files and directories (https://github.com/ansible/ansible/issues/67340).
+- slurp - handle error when ``path`` is a directory and not a file (https://github.com/ansible/ansible/pull/74930).
+- ssh connection - fix interaction between transfer settings options.
+- subversion - fix stack trace when getting information about the repository (https://github.com/ansible/ansible/issues/36498)
+- version test - improve error message when an empty version is provided
+
+v2.11.1
+=======
+
+Release Summary
+---------------
+
+| Release Date: 2021-05-24
 | `Porting Guide <https://docs.ansible.com/ansible/devel/porting_guides.html>`__
 
 
 Minor Changes
 -------------
 
-- ansible-galaxy CLI - ``collection verify`` command now exits with a non-zero exit code on verification failure
-- ansible-galaxy CLI - ``collection verify`` command now supports a ``--offline`` option for local-only verification
+- ansible adhoc, clarified the help to some options, also added some comments to code.
+- command - update the user warning message to point out command name (https://github.com/ansible/ansible/pull/74475).
 
 Bugfixes
 --------
 
-- Correctly set template_path and template_fullpath for usage in template lookup and action plugins.
-- Try to avoid kernel 'blocking' state on reading files while fact gathering.
-- apt - fix policy_rc_d parameter throwing an exception when restoring original file (https://github.com/ansible/ansible/issues/66211)
-- argument spec validation - fix behavior of ``apply_defaults=True`` when an empty dictionary is specified for such an option (https://github.com/ansible/ansible/pull/74029).
-- pause - do not accept enter to continue when a timeout is set (https://github.com/ansible/ansible/issues/73948)
-- setup module, fix error handling on bad subset given
-- wait_for module, move missing socket into function to get proper comparrison in time.
+- Add RockyLinux to fact gathering (https://github.com/ansible/ansible/pull/74530).
+- Improve resilience of ``ansible-galaxy collection`` by increasing the page size to make fewer requests overall and retrying queries with a jittered exponential backoff when rate limiting HTTP codes (520 and 429) occur. (https://github.com/ansible/ansible/issues/74191)
+- Prevent ``ansible_failed_task`` from further templating (https://github.com/ansible/ansible/issues/74036)
+- Remove 'default' from ssh plugin as we want to rely on default from ssh itself or ssh/config.
+- The error message about the failure to import a ``gpg`` key by the ``apt_key`` module was incorrect (https://github.com/ansible/ansible/issues/74423).
+- ansible-test - Avoid publishing the port used by the ``pypi-test-container`` since it is only accessed by other containers. This avoids issues when trying to run tests in parallel on a single host.
+- ansible-test - Fix docker container IP address detection. The ``bridge`` network is no longer assumed to be the default.
+- ansible-test - Use documented API to retrieve build information from Azure Pipelines.
+- ansible.builtin.cron - Keep non-empty crontabs, when removing cron jobs (https://github.com/ansible/ansible/pull/74497).
+- ansible.utils.encrypt now handles missing or unusable 'crypt' library.
+- ansible_test - add constraint for ``MarkupSafe`` (https://github.com/ansible/ansible/pull/74666)
+- apt_key - Binary GnuPG keys downloaded via URLs were corrupted so GnuPG could not import them (https://github.com/ansible/ansible/issues/74424).
+- become - fix a regression on Solaris where chmod can return 5 which we interpret as auth failure and stop trying become tmpdir permission fallbacks
+- become - work around setfacl not existing on modern Solaris (and possibly failing on some filesystems even when it does exist)
+- callback default, now uses task delegate_to instead of delegate vars to display delegate to host
+- callbacks, restores missing delegate_vars
+- correct doc links for become on warnings over world readable settings.
+- correctly use world readable setting since old constant is not 'settable' anymore.
+- facts - detect homebrew installed at /opt/homebrew/bin/brew
+- filter plugins - patch new versions of Jinja2 to prevent warnings/errors on renamed filter decorators (https://github.com/ansible/ansible/issues/74667)
+- get_url - Fixed checksum validation for binary files (leading asterisk) in checksum files (https://github.com/ansible/ansible/pull/74502).
+- hostname - Add Rocky Linux support
+- ini lookup - handle errors for duplicate keys and missing sections (https://github.com/ansible/ansible/issues/74601)
+- interpreter discovery - Debian 8 and lower will avoid unsupported Python3 version in interpreter discovery
+- pause - ensure control characters are always set to an appropriate value (https://github.com/ansible/ansible/issues/73264)
+- playbook loaded from collection subdir now does not ignore subdirs.
+- plugin config now allows list type options to have multiple valid choices (#74225).
+- replace - better handling of file operation exceptions (https://github.com/ansible/ansible/pull/74686).
+- roles - allow for role arg specs in new meta file (https://github.com/ansible/ansible/issues/74525).
+- service - compare version without LooseVersion API (https://github.com/ansible/ansible/issues/74488).
 
-v2.11.0b3
-=========
+v2.11.0
+=======
 
 Release Summary
 ---------------
 
-| Release Date: 2021-03-19
-| `Porting Guide <https://docs.ansible.com/ansible/devel/porting_guides.html>`__
-
-
-Major Changes
--------------
-
-- AnsibleModule - use ``ArgumentSpecValidator`` class for validating argument spec and remove private methods related to argument spec validation. Any modules using private methods should now use the ``ArgumentSpecValidator`` class or the appropriate validation function.
-
-Minor Changes
--------------
-
-- Callbacks - Migrate more places in the ``TaskExecutor`` to sending callbacks directly over the queue, instead of sending them as ``TaskResult`` and short circuiting in the Strategy to send the callback. This enables closer to real time callbacks of retries and loop results (https://github.com/ansible/ansible/issues/73899)
-- setup - fix distribution facts for Older Amazon Linux with ``/etc/os-release`` (https://github.com/ansible/ansible/issues/73946).
-
-Bugfixes
---------
-
-- Fix adding unrelated candidate names to the plugin loader redirect list.
-- Strategy - When building the task in the Strategy from the Worker, ensure it is properly marked as finalized and squashed. Addresses an issue with ``ansible_failed_task``. (https://github.com/ansible/ansible/issues/57399)
-- ansible-pull - Run all playbooks that when multiple are supplied via the command line (https://github.com/ansible/ansible/issues/72708)
-- find module, fix default pattern when use_regex is true.
-
-v2.11.0b2
-=========
-
-Release Summary
----------------
-
-| Release Date: 2021-03-15
-| `Porting Guide <https://docs.ansible.com/ansible/devel/porting_guides.html>`__
-
-
-Minor Changes
--------------
-
-- ansible-test - The generated ``resource_prefix`` variable now meets the host name syntax requirements specified in RFC 1123 and RFC 952. The value used for local tests now places the random number before the hostname component, rather than after. If the resulting value is too long, it will be truncated.
-- ansible-test validate-modules - option names that seem to indicate they contain secret information that should be marked ``no_log=True`` are now flagged in the validate-modules sanity test. False positives can be marked by explicitly setting ``no_log=False`` for these options in the argument spec. Please note that many false positives are expected; the assumption is that it is by far better to have false positives than false negatives (https://github.com/ansible/ansible/pull/73508).
-- distribution - add facts about Amazon Linux Distribution facts (https://github.com/ansible/ansible/issues/73742).
-- module payload builder - module_utils imports in any nested block (eg, ``try``, ``if``) are treated as optional during module payload builds; this allows modules to implement runtime fallback behavior for module_utils that do not exist in older versions of Ansible.
-
-Bugfixes
---------
-
-- A handler defined within a role will now search handlers subdir for included tasks (issue https://github.com/ansible/ansible/issues/71222).
-- ALLOW_WORLD_READABLE_TMP, switched to 'moved' message as 'deprecation' is misleading since config settings still work w/o needing change.
-- Automatically remove async cache files for polled async tasks that have completed (issue https://github.com/ansible/ansible/issues/73206).
-- Deal with failures when sorting JSON and you have incompatible key types.
-- Setup virtualization_facts - add RHV and oVirt type. This change will fully work for VMs in clusters at cluster level 4.4 or newer (https://github.com/ansible/ansible/pull/72876).
-- [set_fact] Corrected and expanded documentation as well as now raise errors that were previously ignored.
-- ansible-test - ensure unit test paths for connection and inventory plugins are correctly identified for collections (https://github.com/ansible/ansible/issues/73876).
-- connection/ssh, ensure parameters come from correct source get_option, so functionality matches docs.
-- connection/ssh, fix reset to use same parameters to check if socket exists as actually used, was hardcoded to default string construction previouslly.
-- j2 plugin loader clarified comments, made note with better fqcn detection.
-- notify keyword is not ignored anymore on import_tasks, also able to apply to blocks now.
-- restrict module valid JSON parsed output to objects as lists are not valid responses.
-- setup, don't give up on all local facts gathering if one script file fails.
-- su become plugin, ensure correct type for localization option.
-
-v2.11.0b1
-=========
-
-Release Summary
----------------
-
-| Release Date: 2021-03-02
+| Release Date: 2021-04-26
 | `Porting Guide <https://docs.ansible.com/ansible/devel/porting_guides.html>`__
 
 
@@ -111,6 +103,7 @@ Major Changes
 -------------
 
 - A collection can be reinstalled with new version requirements without using the ``--force`` flag. The collection's dependencies will also be updated if necessary with the new requirements. Use ``--upgrade`` to force transitive dependency updates.
+- AnsibleModule - use ``ArgumentSpecValidator`` class for validating argument spec and remove private methods related to argument spec validation. Any modules using private methods should now use the ``ArgumentSpecValidator`` class or the appropriate validation function.
 - Declared ``resolvelib >= 0.5.3, < 0.6.0`` a direct dependency of
   ansible-core. Refs:
   - https://github.com/sarugaku/resolvelib
@@ -120,6 +113,7 @@ Major Changes
 - It became possible to upgrade Ansible collections from Galaxy servers using the ``--upgrade`` option with ``ansible-galaxy collection install``.
 - Support for role argument specification validation at role execution time. When a role contains an argument spec, an implicit validation task is inserted at the start of role execution.
 - add ``ArgumentSpecValidator`` class for validating parameters against an argument spec outside of ``AnsibleModule`` (https://github.com/ansible/ansible/pull/73335)
+- ansible-test - Tests run with the ``centos6`` and ``default`` test containers now use a PyPI proxy container to access PyPI when Python 2.6 is used. This allows tests running under Python 2.6 to continue functioning even though PyPI is discontinuing support for non-SNI capable clients.
 
 Minor Changes
 -------------
@@ -147,6 +141,7 @@ Minor Changes
 - CLI - Specify jinja version in ``--version`` output
 - CLI - Specify whether PyYAML includes libyaml support in version output
 - CLI version displays clarified as core version
+- Callbacks - Migrate more places in the ``TaskExecutor`` to sending callbacks directly over the queue, instead of sending them as ``TaskResult`` and short circuiting in the Strategy to send the callback. This enables closer to real time callbacks of retries and loop results (https://github.com/ansible/ansible/issues/73899)
 - Collection routing: Cisco NSO content from community.network migrated to cisco.nso (https://github.com/ansible/ansible/pull/73046).
 - Collection routing: DellEMC content from community.general migrated to dellemc.openmanage (https://github.com/ansible/ansible/pull/73046).
 - Collection routing: FortiOS content from community.network migrated to community.fortios (https://github.com/ansible/ansible/pull/73046).
@@ -200,9 +195,12 @@ Minor Changes
 - ansible-galaxy - Change the output verbosity level of the download message from 3 to 0 (https://github.com/ansible/ansible/issues/70010)
 - ansible-galaxy - Ensure ``get_collection_versions`` returns an empty list when a collection does not exist for consistency across API versions.
 - ansible-galaxy - find any collection dependencies in the globally configured Galaxy servers and not just the server the parent collection is from.
+- ansible-galaxy CLI - ``collection verify`` command now exits with a non-zero exit code on verification failure
+- ansible-galaxy CLI - ``collection verify`` command now supports a ``--offline`` option for local-only verification
 - ansible-test - A warning is no longer emitted when a ``pip*`` or ``python*`` binary is found without a matching couterpart.
 - ansible-test - Add ``macos/10.15`` as a supported value for the ``--remote`` option.
 - ansible-test - Add a ``--docker-network`` option to choose the network for running containers when using the ``--docker`` option.
+- ansible-test - Add constraint for ``decorator`` for Python versions prior to 3.5.
 - ansible-test - Add support for running tests on Fedora 33 (https://github.com/ansible/ansible/pull/72861).
 - ansible-test - Added Ubuntu 20.04 LTS image to the default completion list
 - ansible-test - Added a ``--export`` option to the ``ansible-test coverage combine`` command to facilitate multi-stage aggregation of coverage in CI pipelines.
@@ -258,9 +256,12 @@ Minor Changes
 - ansible-test - The ``pylint`` sanity test is now skipped with a warning on Python 3.9 due to unresolved upstream regressions.
 - ansible-test - The ``pylint`` sanity test is now supported on Python 3.8.
 - ansible-test - The ``rstcheck`` sanity test is no longer used for collections, but continues to be used for ansible-core.
+- ansible-test - The generated ``resource_prefix`` variable now meets the host name syntax requirements specified in RFC 1123 and RFC 952. The value used for local tests now places the random number before the hostname component, rather than after. If the resulting value is too long, it will be truncated.
 - ansible-test - Ubuntu containers as well as ``default-test-container`` and ``ansible-base-test-container`` are now slightly smaller due to apt cleanup (https://github.com/ansible/distro-test-containers/pull/46).
 - ansible-test - Update ``pylint`` and its dependencies to the latest available versions to support Python 3.9.
 - ansible-test - Update built-in service endpoints for the ``--remote`` option.
+- ansible-test - Update distribution test containers from version 2.0.1 to 2.0.2.
+- ansible-test - Update the Ansible Core and Ansible Collection default test containers to 3.2.0 and 3.2.2 respectively.
 - ansible-test - Updated the default test containers to version 3.1.0.
 - ansible-test - Upgrade ansible-runner version used in compatibility tests, remove some tasks that were only needed with older versions, and skip in python2 because ansible-runner is soon dropping it.
 - ansible-test - Use new endpoint for Parallels based instances with the ``--remote`` option.
@@ -286,6 +287,7 @@ Minor Changes
 - ansible-test runtime-metadata - validate removal version numbers, and check removal dates more strictly (https://github.com/ansible/ansible/pull/71679).
 - ansible-test validate-modules - ensure that removal collection version numbers and version_added collection version numbers conform to the semantic versioning specification at https://semver.org/ (https://github.com/ansible/ansible/pull/71679).
 - ansible-test validate-modules - no longer assume that ``default`` for ``type=bool`` options is ``false``, as the default is ``none`` and for some modules, ``none`` and ``false`` mean different things (https://github.com/ansible/ansible/issues/69561).
+- ansible-test validate-modules - option names that seem to indicate they contain secret information that should be marked ``no_log=True`` are now flagged in the validate-modules sanity test. False positives can be marked by explicitly setting ``no_log=False`` for these options in the argument spec. Please note that many false positives are expected; the assumption is that it is by far better to have false positives than false negatives (https://github.com/ansible/ansible/pull/73508).
 - ansible-test validate-modules - validate removal version numbers (https://github.com/ansible/ansible/pull/71679).
 - ansible.utils.encrypt now returns `AnsibleError` instead of crypt.crypt's `OSError` on Python 3.9
 - apt - module now works under any supported Python interpreter
@@ -303,6 +305,7 @@ Minor Changes
 - default callback - task name is now shown for ``include_tasks`` when using the ``free`` strategy (https://github.com/ansible/ansible/issues/71277).
 - default callback - task name is now shown for ``include_tasks`` when using the ``linear`` strategy with ``ANSIBLE_DISPLAY_SKIPPED_HOSTS=0``.
 - default_callback - moving 'check_mode_markers' documentation in default_callback doc_fragment (https://github.com/ansible-collections/community.general/issues/565).
+- distribution - add facts about Amazon Linux Distribution facts (https://github.com/ansible/ansible/issues/73742).
 - distribution - add support for DragonFly distribution (https://github.com/ansible/ansible/issues/43739).
 - distribution - added distribution fact and hostname support for Parrot OS (https://github.com/ansible/ansible/pull/69158).
 - distribution - handle NetBSD OS Family (https://github.com/ansible/ansible/issues/43739).
@@ -328,6 +331,7 @@ Minor Changes
 - lineinfile - add search_string parameter for non-regexp searching (https://github.com/ansible/ansible/issues/70470)
 - linux facts - Add additional check to ensure 'container' virtual fact gets added to guest_tech when appropriate (https://github.com/ansible/ansible/pull/71385)
 - meta - now include a ``skip_reason`` when skipped (https://github.com/ansible/ansible/pull/71355).
+- module payload builder - module_utils imports in any nested block (eg, ``try``, ``if``) are treated as optional during module payload builds; this allows modules to implement runtime fallback behavior for module_utils that do not exist in older versions of Ansible.
 - module_utils - ``get_file_attributes()`` now takes an optional ``include_version`` boolean parameter. When ``True`` (default), the file's version/generation number is included in the result (but requires ``lsattr -v`` to work on the target platform).
 - now !unsafe works on all types of data, not just strings, even recursively for mappings and sequences.
 - package_facts - module support for apt and rpm now works under any supported Python interpreter
@@ -338,7 +342,9 @@ Minor Changes
 - remove ``excommunicate`` debug command from AnsiballZ
 - selinux - return selinux_getpolicytype facts correctly.
 - service_facts - return service state information on AIX.
+- service_facts - return service state information on OpenBSD.
 - setup - allow list of filters (https://github.com/ansible/ansible/pull/68551).
+- setup - fix distribution facts for Older Amazon Linux with ``/etc/os-release`` (https://github.com/ansible/ansible/issues/73946).
 - setup.py - Declare that Python 3.9 is now supported (https://github.com/ansible/ansible/pull/72861).
 - setup.py - Skip doing conflict checks for ``sdist`` and ``egg_info`` commands (https://github.com/ansible/ansible/pull/71310)
 - subelements - clarify the lookup plugin documentation for parameter handling (https://github.com/ansible/ansible/issues/38182).
@@ -396,6 +402,8 @@ Security Fixes
 Bugfixes
 --------
 
+- A handler defined within a role will now search handlers subdir for included tasks (issue https://github.com/ansible/ansible/issues/71222).
+- ALLOW_WORLD_READABLE_TMP, switched to 'moved' message as 'deprecation' is misleading since config settings still work w/o needing change.
 - ANSIBLE_COLLECTIONS_PATHS - remove deprecation so that users of Ansible 2.9 and 2.10+ can use the same var when specifying a collection path without a warning.
 - Added unsafe_writes test.
 - Address compat with rpmfluff-0.6 for integration tests
@@ -407,6 +415,7 @@ Bugfixes
 - Ansible output now uses stdout to determine column width instead of stdin
 - AnsibleModule - added arg ``ignore_invalid_cwd`` to ``AnsibleModule.run_command()``, to control its behaviour when ``cwd`` is invalid. (https://github.com/ansible/ansible/pull/72390)
 - Apply ``_wrap_native_text`` only for builtin filters specified in STRING_TYPE_FILTERS.
+- Automatically remove async cache files for polled async tasks that have completed (issue https://github.com/ansible/ansible/issues/73206).
 - Be smarter about collection paths ending with ansible_collections, emulating a-galaxy behaviour. Issue 72628
 - CLI - Restore git information in version output when running from source
 - Collection callbacks were ignoring options and rules for stdout and adhoc cases.
@@ -415,6 +424,8 @@ Bugfixes
 - ConfigManager - Normalize ConfigParser between Python2 and Python3 to for handling comments (https://github.com/ansible/ansible/issues/73709)
 - Continue execution when  'flatten' filter when it hits a None/null value as part of the list.
 - Correct the inventory source error parse handling, specifically make the config INVENTORY_ANY_UNPARSED_IS_FAILED work as expected.
+- Correctly set template_path and template_fullpath for usage in template lookup and action plugins.
+- Deal with failures when sorting JSON and you have incompatible key types.
 - Display - Use wcswidth to calculate printable width of a text string (https://github.com/ansible/ansible/issues/63105)
 - Enabled unsafe_writes for get_url which was ignoring the paramter.
 - Ensure Ansible's unique filter preserves order (https://github.com/ansible/ansible/issues/63417)
@@ -425,6 +436,7 @@ Bugfixes
 - Fix --list-tasks format `role_name : task_name` when task name contains the role name. (https://github.com/ansible/ansible/issues/72505)
 - Fix ``RecursionError`` when templating large vars structures (https://github.com/ansible/ansible/issues/71920)
 - Fix ``delegate_facts: true`` when ``ansible_python_interpreter`` is not set. (https://github.com/ansible/ansible/issues/70168)
+- Fix adding unrelated candidate names to the plugin loader redirect list.
 - Fix an exit code for a non-failing playbook (https://github.com/ansible/ansible/issues/71306)
 - Fix ansible-galaxy collection list to show collections in site-packages (https://github.com/ansible/ansible/issues/70147)
 - Fix bytestring vs string comparison in module_utils.basic.is_special_selinux_path() so that special-cased filesystems which don't support SELinux context attributes still allow files to be manipulated on them. (https://github.com/ansible/ansible/issues/70244)
@@ -451,6 +463,7 @@ Bugfixes
 - InventoryManager - Fix unhandled exception when inventory directory was empty or contained empty subdirectories (https://github.com/ansible/ansible/issues/73658).
 - JSON Encoder - Ensure we treat single vault encrypted values as strings (https://github.com/ansible/ansible/issues/70784)
 - Lookup user by UID in password database if login name is not found (https://github.com/ansible/ansible/issues/17029)
+- OpenBSD module_utils - update sysctl variable name
 - Pass expression in angle-bracket notation as filename argument to a ``compile()`` built-in function, so that Python debuggers do not try to parse it as filename.
 - Pass the connection's timeout to connection plugins instead of the task's timeout.
 - Provide more information in AnsibleUndefinedVariable (https://github.com/ansible/ansible/issues/55152)
@@ -461,9 +474,11 @@ Bugfixes
 - Restored unsafe_writes functionality which was being skipped.
 - Restructured pipelining settings to be at the connection plugins leaving base config as global and for backwards compatiblity.
 - SSH plugin - Improve error message when ssh client is not found on the host
+- Setup virtualization_facts - add RHV and oVirt type. This change will fully work for VMs in clusters at cluster level 4.4 or newer (https://github.com/ansible/ansible/pull/72876).
 - Skip invalid collection names when listing in ansible-doc instead of throwing exception. Issue#72257
 - Skip literal_eval for string filters results in native jinja. (https://github.com/ansible/ansible/issues/70831)
 - Stop adding the connection variables to the output results
+- Strategy - When building the task in the Strategy from the Worker, ensure it is properly marked as finalized and squashed. Addresses an issue with ``ansible_failed_task``. (https://github.com/ansible/ansible/issues/57399)
 - Suppress warning when user directory used in --playbook-dir option with ansible-inventory command (https://github.com/ansible/ansible/issues/65262).
 - TOML inventory - Ensure we register dump functions for ``AnsibleUnsafe`` to support dumping unsafe values. Note that the TOML format has no functionality to mark that the data is unsafe for re-consumption. (https://github.com/ansible/ansible/issues/71307)
 - Terminal plugins - add "\e[m" to the list of ANSI sequences stripped from device output
@@ -471,9 +486,13 @@ Bugfixes
 - The ``flush()`` method of ``CachePluginAdjudicator`` now calls the plugin's ``flush()`` method instead of iterating over the keys that the adjudicator knows about and deleting those from the cache. (https://github.com/ansible/ansible/issues/68770)
 - The `ansible_become` value was not being treated as a boolean value when set in an INI format inventory file (fixes bug https://github.com/ansible/ansible/issues/70476).
 - The machine-readable changelog ``changelogs/changelog.yaml`` is now contained in the release.
+- Try to avoid kernel 'blocking' state on reading files while fact gathering.
 - Updated docs and added warning on max_fail_percentage and free strategy usage. fixes issue 16666.
 - VariableManager - Add the 'vars' key before getting delegated variables (https://github.com/ansible/ansible/issues/71092).
 - Vault - Allow single vault encrypted values to be used directly as module parameters. (https://github.com/ansible/ansible/issues/68275)
+- WorkerProcess - Implement workaround for stdout deadlock in multiprocessing shutdown to avoid process hangs.
+- WorkerProcess - Python 3.5 fix for workaround for stdout deadlock in multiprocessing shutdown to avoid process hangs. (https://github.com/ansible/ansible/issues/74149)
+- [set_fact] Corrected and expanded documentation as well as now raise errors that were previously ignored.
 - account for bug in Python 2.6 that occurs during interpreter shutdown to avoid stack trace
 - action plugins - change all action/module delegations to use FQ names while allowing overrides (https://github.com/ansible/ansible/issues/69788)
 - add AlmaLinux to fact gathering (https://github.com/ansible/ansible/pull/73458)
@@ -502,7 +521,9 @@ Bugfixes
 - ansible-galaxy collection download - fix downloading tar.gz files and collections in git repositories (https://github.com/ansible/ansible/issues/70429)
 - ansible-galaxy collection install - fix fallback mechanism if the AH server did not have the collection requested - https://github.com/ansible/ansible/issues/70940
 - ansible-galaxy download - fix bug when downloading a collection in a SCM subdirectory
+- ansible-pull - Run all playbooks that when multiple are supplied via the command line (https://github.com/ansible/ansible/issues/72708)
 - ansible-test - Add ``pytest < 6.0.0`` constraint for managed installations on Python 3.x to avoid issues with relative imports.
+- ansible-test - Add a ``six < 1.14.0`` constraint for Python 2.6.
 - ansible-test - Always connect additional Docker containers to the network used by the current container (if any).
 - ansible-test - Always map ``/var/run/docker.sock`` into test containers created by the ``--docker`` option if the docker host is not ``localhost``.
 - ansible-test - Attempt to detect the Docker hostname instead of assuming ``localhost``.
@@ -518,10 +539,12 @@ Bugfixes
 - ansible-test - Skip installing requirements if they are already installed.
 - ansible-test - Symbolic links are no longer used to inject ``python`` into the environment, since they do not work reliably in all cases. Instead, the existing Python based exec wrapper is always used.
 - ansible-test - Temporarily limit ``cryptography`` to versions before 3.4 to enable tests to function.
+- ansible-test - The ``--export`` option for ``ansible-test coverage`` is now limited to the ``combine`` command. It was previously available for reporting commands on which it had no effect.
 - ansible-test - The ``--raw`` option for ``ansible-test shell --remote`` now uses ``sh`` for the shell instead of ``bash``, which may not be present.
 - ansible-test - The ``--remote`` option has been updated for Python 2.7 to work around breaking changes in the newly released ``get-pip.py`` bootstrapper.
 - ansible-test - The ``--remote`` option has been updated to use a versioned ``get-pip.py`` bootstrapper to avoid issues with future releases.
 - ansible-test - The ``ansible-doc`` sanity test now works for ``netconf`` plugins.
+- ansible-test - The ``ansible-test coverage combine`` option ``--export`` now exports relative paths. This avoids loss of coverage data when aggregating across systems with different absolute paths. Paths will be converted back to absolute when generating reports.
 - ansible-test - The ``changelog`` sanity test has been updated to ensure ``rstcheck`` does not load the ``sphinx`` module.
 - ansible-test - The ``cs`` and ``openshift`` test plugins now search for containers on the current network instead of assuming the ``bridge`` network.
 - ansible-test - The ``resource_prefix`` variable provided to tests running on Azure Pipelines is now converted to lowercase to match other CI providers.
@@ -530,6 +553,8 @@ Bugfixes
 - ansible-test - ``cryptography`` is now limited to versions prior to 3.2 only when an incompatible OpenSSL version (earlier than 1.1.0) is detected
 - ansible-test - add constraint for ``cffi`` to prevent failure on systems with older versions of ``gcc`` (https://foss.heptapod.net/pypy/cffi/-/issues/480)
 - ansible-test - convert target paths to unicode on Python 2 to avoid ``UnicodeDecodeError`` (https://github.com/ansible/ansible/issues/68398, https://github.com/ansible/ansible/pull/72623).
+- ansible-test - ensure the correct unit test target is given when the ``__init__.py`` file is modified inside the connection plugins directory
+- ansible-test - ensure unit test paths for connection and inventory plugins are correctly identified for collections (https://github.com/ansible/ansible/issues/73876).
 - ansible-test - improve classification of changes to ``.gitignore``, ``COPYING``, ``LICENSE``, ``Makefile``, and all files ending with one of ``.in`, ``.md`, ``.rst``, ``.toml``, ``.txt`` in the collection root directory (https://github.com/ansible/ansible/pull/72353).
 - ansible-test - integration and unit test change detection now works for filter, lookup and test plugins
 - ansible-test now always uses the ``--python`` option for ``virtualenv`` to select the correct interpreter when creating environments with the ``--venv`` option
@@ -541,9 +566,11 @@ Bugfixes
 - ansible_pkg_mgr fact - now correctly returns ``atomic_container`` when run on "RHEL for Edge" images and Fedora/RHEL/CentOS Atomic Host (https://github.com/ansible/ansible/issues/73084).
 - api - time.clock is removed in Python 3.8, add backward compatible code (https://github.com/ansible/ansible/issues/70649).
 - apt - add ``fail_on_autoremove`` param to apt module to avoid unintended package removals (https://github.com/ansible/ansible/issues/63231)
+- apt - fix policy_rc_d parameter throwing an exception when restoring original file (https://github.com/ansible/ansible/issues/66211)
 - apt - include exception message from apt python library in error output
 - apt_key - Specifying ``file`` as mutually exclusive with ``data``, ``keyserver``, ``url`` (https://github.com/ansible/ansible/pull/70492).
 - apt_repository - fixes ``mode`` doc to remove ineffective default (https://github.com/ansible/ansible/pull/70319).
+- argument spec validation - fix behavior of ``apply_defaults=True`` when an empty dictionary is specified for such an option (https://github.com/ansible/ansible/pull/74029).
 - assemble - fix decrypt argument in the module (https://github.com/ansible/ansible/issues/65450).
 - async - Fix Python 3 interpreter parsing from module by comparing with bytes (https://github.com/ansible/ansible/issues/70690)
 - async_wrapper - Fix race condition when ``~/.ansible_async`` folder tries to be created by multiple async tasks at the same time - https://github.com/ansible/ansible/issues/59306
@@ -556,8 +583,11 @@ Bugfixes
 - clarified changed status to reflect existing rule that had never been written down.
 - collection loader - fix bogus code coverage entries for synthetic packages
 - collection metadata - ensure collection loader uses libyaml/CSafeLoader to parse collection metadata if available
+- connection/ssh, ensure parameters come from correct source get_option, so functionality matches docs.
+- connection/ssh, fix reset to use same parameters to check if socket exists as actually used, was hardcoded to default string construction previouslly.
 - cron - cron file should not be empty after adding var (https://github.com/ansible/ansible/pull/71207)
 - cron - encode and decode crontab files in UTF-8 explicitly to allow non-ascii chars in cron filepath and job (https://github.com/ansible/ansible/issues/69492)
+- debug action, prevent setting facts when displaying ansible_facts.
 - default callback - Ensure that the ``host_pinned`` strategy is not treated as lockstep (https://github.com/ansible/ansible/issues/73364)
 - delegate_to - Ensure that calculating ``delegate_to`` vars with a loop uses the correct context to correctly evaluate the loop (https://github.com/ansible/ansible/issues/37132)
 - display correct error information when an error exists in the last line of the file (https://github.com/ansible/ansible/issues/16456)
@@ -578,6 +608,7 @@ Bugfixes
 - file - the module should warn in check_mode when path an owner/group don't exist (https://github.com/ansible/ansible/issues/67307).
 - find module - Don't treat empty excludes as a match (https://github.com/ansible/ansible/issues/70640)
 - find module - Stop traversing directories past the requested depth. (https://github.com/ansible/ansible/issues/73627)
+- find module, fix default pattern when use_regex is true.
 - fix issue with inventory_hostname and delegated host vars mixing on connection settings.
 - fortimanager httpapi plugin - fix redirect to point to the ``fortinet.fortimanager`` collection (https://github.com/ansible/ansible/pull/71073).
 - galaxy - handle plus sign in user token appearing in role url (https://github.com/ansible/ansible/issues/45475).
@@ -595,15 +626,18 @@ Bugfixes
 - inventory plugins - Let plugins define the sanitization method for the constructed ``groups`` feature.
 - inventory_hostnames - Use ``InventoryManager`` instead of trying to replicate its behavior (https://github.com/ansible/ansible/issues/17268)
 - is_string/vault - Ensure the is_string helper properly identifies AnsibleVaultEncryptedUnicode as a string (https://github.com/ansible/ansible/pull/71609)
+- j2 plugin loader clarified comments, made note with better fqcn detection.
 - lineinfile - fix not subscriptable error in exception handling around file creation
 - linux network facts - get the correct value for broadcast address (https://github.com/ansible/ansible/issues/64384)
 - native jinja2 types - properly handle Undefined in nested data.
+- notify keyword is not ignored anymore on import_tasks, also able to apply to blocks now.
 - package - use list of built in package managers from facts rather than creating a new list
 - paramiko connection plugin - Ensure we only reset the connection when one has been previously established (https://github.com/ansible/ansible/issues/65812)
 - password hashing - Ensure we validate salts against allowed characters and length when using ``crypt`` (https://github.com/ansible/ansible/issues/71107)
 - password lookup - Try to automatically generate salts using known salt sizes (https://github.com/ansible/ansible/issues/53750)
 - pause - Fix indefinite hang when using a pause task on a background process (https://github.com/ansible/ansible/issues/32142)
 - pause - catch additional error on setting up curses (https://github.com/ansible/ansible/pull/73588).
+- pause - do not accept enter to continue when a timeout is set (https://github.com/ansible/ansible/issues/73948)
 - pause - do not warn when running in the background if a timeout is provided (https://github.com/ansible/ansible/issues/73042)
 - pause - handle exception when there is no stdout (https://github.com/ansible/ansible/pull/47851)
 - powershell - fix escaping of strings that broken modules like fetch when dealing with special chars - https://github.com/ansible/ansible/issues/62781
@@ -616,15 +650,19 @@ Bugfixes
 - remove contradictory recomendation from template docs. https://github.com/ansible/ansible/issues/63484
 - remove redundant remote_user setting in play_context for local as plugin already does it, also removes fork/thread issue from use of pwd library.
 - reset logging level to INFO due to CVE-2019-14846.
+- restrict module valid JSON parsed output to objects as lists are not valid responses.
 - runas - create a new token when running as ``SYSTEM`` to ensure it has the full privileges assigned to that account
 - service - Fix for the BSD rcconf code using a Python 2 specific string replace function
 - set_mode_if_different - handle symlink if it is inside a directory with sticky bit set (https://github.com/ansible/ansible/pull/45198)
+- setup module, fix error handling on bad subset given
+- setup, don't give up on all local facts gathering if one script file fails.
 - several fixes to make apt_key better at identifying needs for change and also to avoid changes in check_mode.
 - shell - fix quoting of mkdir command in creation of remote_tmp in order to allow spaces and other special characters (https://github.com/ansible/ansible/issues/69577).
 - splunk httpapi plugin - switch from splunk.enterprise_security to splunk.es in runtime.yml to reflect upstream change of Collection Name
 - ssh connection plugin - use ``get_option()`` rather than ``_play_context`` to ensure ``ANSBILE_SSH_ARGS`` are applied properly (https://github.com/ansible/ansible/issues/70437)
 - stat - handle colons in filename while parsing the mimetype output (https://github.com/ansible/ansible/issues/70256).
 - strftime filter - Input epoch is allowed to be a float (https://github.com/ansible/ansible/issues/71257)
+- su become plugin, ensure correct type for localization option.
 - systemd - account for templated unit files using ``@`` when searching for the unit file (https://github.com/ansible/ansible/pull/72347#issuecomment-730626228)
 - systemd - fixed chroot usage on new versions of systemd, that broke because of upstream changes in systemctl output
 - systemd - follow up fix to https://github.com/ansible/ansible/issues/72338 to use ``list-unit-files`` rather than ``list-units`` in order to show all units files on the system.
@@ -650,6 +688,7 @@ Bugfixes
 - vault - Support reading raw binary data from stdin under python3
 - virtual facts - kubevirt is now identified as "KubeVirt" and with a "guest" role instead of "kvm" and "host" role (https://github.com/ansible/ansible/issues/72001).
 - wait_for - catch and ignore errors when getting active connections with psutil (https://github.com/ansible/ansible/issues/72322)
+- wait_for module, move missing socket into function to get proper comparrison in time.
 - win setup - Fix redirection path for the windows setup module
 - windows async - use full path when calling PowerShell to reduce reliance on environment vars being correct - https://github.com/ansible/ansible/issues/70655
 - winrm - preserve winrm forensic data on put_file failures

changelogs/changelog.yaml

@@ -1,5 +1,32 @@
 ancestor: 2.10.0
 releases:
+  2.11.0:
+    changes:
+      bugfixes:
+      - ansible-test - ensure the correct unit test target is given when the ``__init__.py``
+        file is modified inside the connection plugins directory
+      major_changes:
+      - ansible-test - Tests run with the ``centos6`` and ``default`` test containers
+        now use a PyPI proxy container to access PyPI when Python 2.6 is used. This
+        allows tests running under Python 2.6 to continue functioning even though
+        PyPI is discontinuing support for non-SNI capable clients.
+      minor_changes:
+      - ansible-test - Update distribution test containers from version 2.0.1 to 2.0.2.
+      - ansible-test - Update the Ansible Core and Ansible Collection default test
+        containers to 3.2.0 and 3.2.2 respectively.
+      release_summary: '| Release Date: 2021-04-26
+
+        | `Porting Guide <https://docs.ansible.com/ansible/devel/porting_guides.html>`__
+
+        '
+    codename: Hey Hey, What Can I Do
+    fragments:
+    - ansible-test-connection-units-init.yml
+    - ansible-test-default-containers-3.2.yml
+    - ansible-test-distro-containers-2.0.2.yml
+    - ansible-test-pypi-test-container.yml
+    - v2.11.0_summary.yaml
+    release_date: '2021-04-26'
   2.11.0b1:
     changes:
       breaking_changes:
@@ -1586,3 +1613,220 @@ releases:
     - v2.11.0b4_summary.yaml
     - wait_for_fix.yml
     release_date: '2021-03-29'
+  2.11.0rc1:
+    changes:
+      bugfixes:
+      - OpenBSD module_utils - update sysctl variable name
+      - WorkerProcess - Implement workaround for stdout deadlock in multiprocessing
+        shutdown to avoid process hangs.
+      - ansible-test - Add a ``six < 1.14.0`` constraint for Python 2.6.
+      - ansible-test - The ``--export`` option for ``ansible-test coverage`` is now
+        limited to the ``combine`` command. It was previously available for reporting
+        commands on which it had no effect.
+      - ansible-test - The ``ansible-test coverage combine`` option ``--export`` now
+        exports relative paths. This avoids loss of coverage data when aggregating
+        across systems with different absolute paths. Paths will be converted back
+        to absolute when generating reports.
+      - debug action, prevent setting facts when displaying ansible_facts.
+      minor_changes:
+      - ansible-test - Add constraint for ``decorator`` for Python versions prior
+        to 3.5.
+      - service_facts - return service state information on OpenBSD.
+      release_summary: '| Release Date: 2021-04-05
+
+        | `Porting Guide <https://docs.ansible.com/ansible/devel/porting_guides.html>`__
+
+        '
+    codename: Hey Hey, What Can I Do
+    fragments:
+    - ansible-test-decorator-constraint.yml
+    - ansible-test-fix-coverage-export.yml
+    - ansible-test-six.yml
+    - debug_dont_set_facts.yml
+    - openbsd-service.yml
+    - openbsd-sysutil.yml
+    - v2.11.0rc1_summary.yaml
+    - workerprocess-stdout-deadlock.yml
+    release_date: '2021-04-05'
+  2.11.0rc2:
+    changes:
+      bugfixes:
+      - WorkerProcess - Python 3.5 fix for workaround for stdout deadlock in multiprocessing
+        shutdown to avoid process hangs. (https://github.com/ansible/ansible/issues/74149)
+      release_summary: '| Release Date: 2021-04-06
+
+        | `Porting Guide <https://docs.ansible.com/ansible/devel/porting_guides.html>`__
+
+        '
+    codename: Hey Hey, What Can I Do
+    fragments:
+    - fix-for-workerprocess-stdout-deadlock-fix.yml
+    - v2.11.0rc2_summary.yaml
+    release_date: '2021-04-06'
+  2.11.1:
+    changes:
+      release_summary: '| Release Date: 2021-05-24
+
+        | `Porting Guide <https://docs.ansible.com/ansible/devel/porting_guides.html>`__
+
+        '
+    codename: Hey Hey, What Can I Do
+    fragments:
+    - v2.11.1_summary.yaml
+    release_date: '2021-05-24'
+  2.11.1rc1:
+    changes:
+      bugfixes:
+      - Add RockyLinux to fact gathering (https://github.com/ansible/ansible/pull/74530).
+      - Improve resilience of ``ansible-galaxy collection`` by increasing the page
+        size to make fewer requests overall and retrying queries with a jittered exponential
+        backoff when rate limiting HTTP codes (520 and 429) occur. (https://github.com/ansible/ansible/issues/74191)
+      - Prevent ``ansible_failed_task`` from further templating (https://github.com/ansible/ansible/issues/74036)
+      - Remove 'default' from ssh plugin as we want to rely on default from ssh itself
+        or ssh/config.
+      - The error message about the failure to import a ``gpg`` key by the ``apt_key``
+        module was incorrect (https://github.com/ansible/ansible/issues/74423).
+      - ansible-test - Avoid publishing the port used by the ``pypi-test-container``
+        since it is only accessed by other containers. This avoids issues when trying
+        to run tests in parallel on a single host.
+      - ansible-test - Fix docker container IP address detection. The ``bridge`` network
+        is no longer assumed to be the default.
+      - ansible-test - Use documented API to retrieve build information from Azure
+        Pipelines.
+      - ansible.builtin.cron - Keep non-empty crontabs, when removing cron jobs (https://github.com/ansible/ansible/pull/74497).
+      - ansible.utils.encrypt now handles missing or unusable 'crypt' library.
+      - ansible_test - add constraint for ``MarkupSafe`` (https://github.com/ansible/ansible/pull/74666)
+      - apt_key - Binary GnuPG keys downloaded via URLs were corrupted so GnuPG could
+        not import them (https://github.com/ansible/ansible/issues/74424).
+      - become - fix a regression on Solaris where chmod can return 5 which we interpret
+        as auth failure and stop trying become tmpdir permission fallbacks
+      - become - work around setfacl not existing on modern Solaris (and possibly
+        failing on some filesystems even when it does exist)
+      - callback default, now uses task delegate_to instead of delegate vars to display
+        delegate to host
+      - callbacks, restores missing delegate_vars
+      - correct doc links for become on warnings over world readable settings.
+      - correctly use world readable setting since old constant is not 'settable'
+        anymore.
+      - facts - detect homebrew installed at /opt/homebrew/bin/brew
+      - filter plugins - patch new versions of Jinja2 to prevent warnings/errors on
+        renamed filter decorators (https://github.com/ansible/ansible/issues/74667)
+      - get_url - Fixed checksum validation for binary files (leading asterisk) in
+        checksum files (https://github.com/ansible/ansible/pull/74502).
+      - hostname - Add Rocky Linux support
+      - ini lookup - handle errors for duplicate keys and missing sections (https://github.com/ansible/ansible/issues/74601)
+      - interpreter discovery - Debian 8 and lower will avoid unsupported Python3
+        version in interpreter discovery
+      - pause - ensure control characters are always set to an appropriate value (https://github.com/ansible/ansible/issues/73264)
+      - playbook loaded from collection subdir now does not ignore subdirs.
+      - plugin config now allows list type options to have multiple valid choices
+        (#74225).
+      - replace - better handling of file operation exceptions (https://github.com/ansible/ansible/pull/74686).
+      - roles - allow for role arg specs in new meta file (https://github.com/ansible/ansible/issues/74525).
+      - service - compare version without LooseVersion API (https://github.com/ansible/ansible/issues/74488).
+      minor_changes:
+      - ansible adhoc, clarified the help to some options, also added some comments
+        to code.
+      - command - update the user warning message to point out command name (https://github.com/ansible/ansible/pull/74475).
+      release_summary: '| Release Date: 2021-05-17
+
+        | `Porting Guide <https://docs.ansible.com/ansible/devel/porting_guides.html>`__
+
+        '
+    codename: Hey Hey, What Can I Do
+    fragments:
+    - 73264-pause-emacs.yml
+    - 73887.mac-m1-homebrew.yaml
+    - 74036-unsafe-ansible_failed_task.yml
+    - 74240-ansible-galaxy-increase-pagesize-and-handle-throttling.yml
+    - 74474-apt_key-gpg-binary-import.yaml
+    - 74476-apt_key-gpg-inline-data.yaml
+    - 74488_solaris_looseversion.yml
+    - 74497-keep-non-empty-crontabs.yml
+    - 74502-get_url-filx-checksum-binary.yml
+    - 74582-role-argspec-new-file.yml
+    - 74601-ini-lookup-handle-errors.yml
+    - 74686-replace-handle-file-exc.yml
+    - adhoc_help_clarify.yml
+    - allow_lists_of_config_choices.yml
+    - ansible-test-azp-build-api.yml
+    - ansible-test-docker-network-detect.yml
+    - ansible-test-markupsafe-constraint.yml
+    - ansible-test-pypi-container-no-publish.yml
+    - cmd_wording.yml
+    - coll_pb_subdir_fixes.yml
+    - crypt_missing.yml
+    - debian8_discovery.yml
+    - jinja2_decorator_renames.yml
+    - macos-solaris-regression.yml
+    - missing_delegate_vars.yml
+    - solaris-setfacl-chmod-fallback.yml
+    - ssh_port_default_fix.yml
+    - support_rocky_linux_hostname.yml
+    - support_rockylinux.yml
+    - v2.11.1rc1_summary.yaml
+    - world_readable_fixes.yml
+    release_date: '2021-05-17'
+  2.11.2:
+    changes:
+      release_summary: '| Release Date: 2021-06-22
+
+        | `Porting Guide <https://docs.ansible.com/ansible/devel/porting_guides.html>`__
+
+        '
+    codename: Hey Hey, What Can I Do
+    fragments:
+    - v2.11.2_summary.yaml
+    release_date: '2021-06-22'
+  2.11.2rc1:
+    changes:
+      bugfixes:
+      - AnsibleModule.set_mode_if_different - don't check file existence when check_mode
+        is activated (https://github.com/ansible/ansible/issues/61185).
+      - Apply ``display_failed_stderr`` callback option on loop item results. (https://github.com/ansible/ansible/issues/74864)
+      - Avoid task executor from ending early as vars can come from delegated to host.
+      - ansible-pull - update documentation for ``--directory`` option to clarify
+        path must be absolute.
+      - config, ensure 'quoted' lists from ini or env do not take the quotes literally
+        as part of the list item.
+      - gather_facts, package, service - fix using module_defaults for the modules
+        in addition to the action plugins. (https://github.com/ansible/ansible/issues/72918)
+      - psrp - Always cleanup the last run pipeline if a second pipeline is invoked
+        to avoid violating any resource limits.
+      - psrp - Fix error when resetting a connection that was initialised but not
+        connected - (https://github.com/ansible/ansible/issues/74092).
+      - psrp - Try to clean up any server-side resources when resetting a connection.
+      - roles - make sure argspec validation task is tagged with ``always`` (https://github.com/ansible/ansible/pull/74994).
+      - slurp - Fix error messages for unreadable files and directories (https://github.com/ansible/ansible/issues/67340).
+      - slurp - handle error when ``path`` is a directory and not a file (https://github.com/ansible/ansible/pull/74930).
+      - ssh connection - fix interaction between transfer settings options.
+      - subversion - fix stack trace when getting information about the repository
+        (https://github.com/ansible/ansible/issues/36498)
+      - version test - improve error message when an empty version is provided
+      release_summary: '| Release Date: 2021-06-14
+
+        | `Porting Guide <https://docs.ansible.com/ansible/devel/porting_guides.html>`__
+
+        '
+      security_fixes:
+      - templating engine fix for not preserving usnafe status when trying to preserve
+        newlines. CVE-2021-3583
+    codename: Hey Hey, What Can I Do
+    fragments:
+    - 36498-subversion-fix-info-parsing.yml
+    - 61185-basic.py-fix-check_mode.yaml
+    - 67340-slurp_error_message.yml
+    - 73864-action-plugin-module-defaults.yml
+    - 74864-display_failed_stderr-per-item.yml
+    - ansible-pull-doc-update.yml
+    - config_lists_unquote.yml
+    - delegate_te_fix.yml
+    - fix_scp_ssh_settings.yml
+    - fix_unsafe_newline.yml
+    - psrp-cleanup.yml
+    - psrp-reset.yml
+    - role_argspec_tagged_always.yml
+    - slurp-handle-error-with-dir.yml
+    - v2.11.2rc1_summary.yaml
+    - version_compare-error-on-empty.yml
+    release_date: '2021-06-14'

changelogs/fragments/36498-subversion-fix-info-parsing.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - subversion - fix stack trace when getting information about the repository (https://github.com/ansible/ansible/issues/36498)

changelogs/fragments/61185-basic.py-fix-check_mode.yaml

@@ -0,0 +1,2 @@
+bugfixes:
+- AnsibleModule.set_mode_if_different - don't check file existence when check_mode is activated (https://github.com/ansible/ansible/issues/61185).

changelogs/fragments/67340-slurp_error_message.yml

@@ -0,0 +1,2 @@
+bugfixes:
+- "slurp - Fix error messages for unreadable files and directories (https://github.com/ansible/ansible/issues/67340)."

changelogs/fragments/73264-pause-emacs.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - pause - ensure control characters are always set to an appropriate value (https://github.com/ansible/ansible/issues/73264)

changelogs/fragments/73864-action-plugin-module-defaults.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - gather_facts, package, service - fix using module_defaults for the modules in addition to the action plugins. (https://github.com/ansible/ansible/issues/72918)

changelogs/fragments/73887.mac-m1-homebrew.yaml

@@ -0,0 +1,3 @@
+---
+bugfixes:
+  - facts - detect homebrew installed at /opt/homebrew/bin/brew

changelogs/fragments/74036-unsafe-ansible_failed_task.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - Prevent ``ansible_failed_task`` from further templating (https://github.com/ansible/ansible/issues/74036)

changelogs/fragments/74240-ansible-galaxy-increase-pagesize-and-handle-throttling.yml

@@ -0,0 +1,6 @@
+bugfixes:
+- >-
+  Improve resilience of ``ansible-galaxy collection`` by increasing the page
+  size to make fewer requests overall and retrying queries with a jittered
+  exponential backoff when rate limiting HTTP codes (520 and 429) occur.
+  (https://github.com/ansible/ansible/issues/74191)

changelogs/fragments/74474-apt_key-gpg-binary-import.yaml

@@ -0,0 +1,2 @@
+bugfixes:
+  - apt_key - Binary GnuPG keys downloaded via URLs were corrupted so GnuPG could not import them (https://github.com/ansible/ansible/issues/74424).

changelogs/fragments/74476-apt_key-gpg-inline-data.yaml

@@ -0,0 +1,2 @@
+bugfixes:
+  - The error message about the failure to import a ``gpg`` key by the ``apt_key`` module was incorrect (https://github.com/ansible/ansible/issues/74423).

changelogs/fragments/74488_solaris_looseversion.yml

@@ -0,0 +1,2 @@
+bugfixes:
+- service - compare version without LooseVersion API (https://github.com/ansible/ansible/issues/74488).

changelogs/fragments/74497-keep-non-empty-crontabs.yml

@@ -0,0 +1,3 @@
+bugfixes:
+  - ansible.builtin.cron - Keep non-empty crontabs, when removing cron jobs
+    (https://github.com/ansible/ansible/pull/74497).

changelogs/fragments/74502-get_url-filx-checksum-binary.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - get_url - Fixed checksum validation for binary files (leading asterisk) in checksum files (https://github.com/ansible/ansible/pull/74502).

changelogs/fragments/74582-role-argspec-new-file.yml

@@ -0,0 +1,2 @@
+bugfixes:
+    - roles - allow for role arg specs in new meta file (https://github.com/ansible/ansible/issues/74525).

changelogs/fragments/74601-ini-lookup-handle-errors.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - ini lookup - handle errors for duplicate keys and missing sections (https://github.com/ansible/ansible/issues/74601)

changelogs/fragments/74686-replace-handle-file-exc.yml

@@ -0,0 +1,2 @@
+bugfixes:
+    - replace - better handling of file operation exceptions (https://github.com/ansible/ansible/pull/74686).

changelogs/fragments/74864-display_failed_stderr-per-item.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - Apply ``display_failed_stderr`` callback option on loop item results. (https://github.com/ansible/ansible/issues/74864)

changelogs/fragments/adhoc_help_clarify.yml

@@ -0,0 +1,2 @@
+minor_changes:
+  - ansible adhoc, clarified the help to some options, also added some comments to code.

changelogs/fragments/allow_lists_of_config_choices.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - plugin config now allows list type options to have multiple valid choices (#74225).

changelogs/fragments/ansible-pull-doc-update.yml

@@ -0,0 +1,2 @@
+bugfixes:
+    - ansible-pull - update documentation for ``--directory`` option to clarify path must be absolute.

changelogs/fragments/ansible-test-azp-build-api.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - ansible-test - Use documented API to retrieve build information from Azure Pipelines.

changelogs/fragments/ansible-test-connection-units-init.yml

@@ -0,0 +1,4 @@
+bugfixes:
+  - >-
+    ansible-test - ensure the correct unit test target is given when the
+    ``__init__.py`` file is modified inside the connection plugins directory

changelogs/fragments/ansible-test-decorator-constraint.yml

@@ -0,0 +1,2 @@
+minor_changes:
+    - ansible-test - Add constraint for ``decorator`` for Python versions prior to 3.5.

changelogs/fragments/ansible-test-default-containers-3.2.yml

@@ -0,0 +1,2 @@
+minor_changes:
+    - ansible-test - Update the Ansible Core and Ansible Collection default test containers to 3.2.0 and 3.2.2 respectively.

changelogs/fragments/ansible-test-distro-containers-2.0.2.yml

@@ -0,0 +1,2 @@
+minor_changes:
+    - ansible-test - Update distribution test containers from version 2.0.1 to 2.0.2.

changelogs/fragments/ansible-test-docker-network-detect.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - ansible-test - Fix docker container IP address detection. The ``bridge`` network is no longer assumed to be the default.

changelogs/fragments/ansible-test-markupsafe-constraint.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - ansible_test - add constraint for ``MarkupSafe`` (https://github.com/ansible/ansible/pull/74666)

changelogs/fragments/ansible-test-pypi-container-no-publish.yml

@@ -0,0 +1,3 @@
+bugfixes:
+  - ansible-test - Avoid publishing the port used by the ``pypi-test-container`` since it is only accessed by other containers.
+                   This avoids issues when trying to run tests in parallel on a single host.

changelogs/fragments/ansible-test-pypi-test-container.yml

@@ -0,0 +1,3 @@
+major_changes:
+  - ansible-test - Tests run with the ``centos6`` and ``default`` test containers now use a PyPI proxy container to access PyPI when Python 2.6 is used.
+                   This allows tests running under Python 2.6 to continue functioning even though PyPI is discontinuing support for non-SNI capable clients.

changelogs/fragments/cmd_wording.yml

@@ -0,0 +1,2 @@
+minor_changes:
+- command - update the user warning message to point out command name (https://github.com/ansible/ansible/pull/74475).

changelogs/fragments/coll_pb_subdir_fixes.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - playbook loaded from collection subdir now does not ignore subdirs.

changelogs/fragments/config_lists_unquote.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - config, ensure 'quoted' lists from ini or env do not take the quotes literally as part of the list item.

changelogs/fragments/crypt_missing.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - ansible.utils.encrypt now handles missing or unusable 'crypt' library.

changelogs/fragments/debian8_discovery.yml

@@ -0,0 +1,2 @@
+bugfixes:
+- interpreter discovery - Debian 8 and lower will avoid unsupported Python3 version in interpreter discovery

changelogs/fragments/delegate_te_fix.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - Avoid task executor from ending early as vars can come from delegated to host.

changelogs/fragments/fix-for-workerprocess-stdout-deadlock-fix.yml

@@ -0,0 +1,2 @@
+bugfixes:
+ - "WorkerProcess - Python 3.5 fix for workaround for stdout deadlock in multiprocessing shutdown to avoid process hangs. (https://github.com/ansible/ansible/issues/74149)"

changelogs/fragments/fix_scp_ssh_settings.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - ssh connection - fix interaction between transfer settings options.

changelogs/fragments/fix_unsafe_newline.yml

@@ -0,0 +1,2 @@
+security_fixes:
+  - templating engine fix for not preserving usnafe status when trying to preserve newlines. CVE-2021-3583

changelogs/fragments/jinja2_decorator_renames.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - filter plugins - patch new versions of Jinja2 to prevent warnings/errors on renamed filter decorators (https://github.com/ansible/ansible/issues/74667)

changelogs/fragments/macos-solaris-regression.yml

@@ -0,0 +1,4 @@
+bugfixes:
+  - >-
+    become - fix a regression on Solaris where chmod can return 5 which we
+    interpret as auth failure and stop trying become tmpdir permission fallbacks

changelogs/fragments/missing_delegate_vars.yml

@@ -0,0 +1,3 @@
+bugfixes:
+  - callbacks, restores missing delegate_vars
+  - callback default, now uses task delegate_to instead of delegate vars to display delegate to host

changelogs/fragments/psrp-cleanup.yml

@@ -0,0 +1,2 @@
+bugfixes:
+- psrp - Always cleanup the last run pipeline if a second pipeline is invoked to avoid violating any resource limits.

changelogs/fragments/psrp-reset.yml

@@ -0,0 +1,3 @@
+bugfixes:
+- psrp - Fix error when resetting a connection that was initialised but not connected - (https://github.com/ansible/ansible/issues/74092).
+- psrp - Try to clean up any server-side resources when resetting a connection.

changelogs/fragments/role_argspec_tagged_always.yml

@@ -0,0 +1,2 @@
+bugfixes:
+    - roles - make sure argspec validation task is tagged with ``always`` (https://github.com/ansible/ansible/pull/74994).

changelogs/fragments/slurp-handle-error-with-dir.yml

@@ -0,0 +1,2 @@
+bugfixes:
+- slurp - handle error when ``path`` is a directory and not a file (https://github.com/ansible/ansible/pull/74930).

changelogs/fragments/solaris-setfacl-chmod-fallback.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - become - work around setfacl not existing on modern Solaris (and possibly failing on some filesystems even when it does exist)

changelogs/fragments/ssh_port_default_fix.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - Remove 'default' from ssh plugin as we want to rely on default from ssh itself or ssh/config.

changelogs/fragments/support_rocky_linux_hostname.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - hostname - Add Rocky Linux support

changelogs/fragments/support_rockylinux.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - Add RockyLinux to fact gathering (https://github.com/ansible/ansible/pull/74530).

changelogs/fragments/v2.11.0_summary.yaml

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

changelogs/fragments/v2.11.0rc1_summary.yaml

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

changelogs/fragments/v2.11.0rc2_summary.yaml

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

changelogs/fragments/v2.11.1_summary.yaml

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

changelogs/fragments/v2.11.1rc1_summary.yaml

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

changelogs/fragments/v2.11.2_summary.yaml

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

changelogs/fragments/v2.11.2rc1_summary.yaml

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

changelogs/fragments/version_compare-error-on-empty.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - version test - improve error message when an empty version is provided

changelogs/fragments/world_readable_fixes.yml

@@ -0,0 +1,3 @@
+bugfixes:
+  - correctly use world readable setting since old constant is not 'settable' anymore.
+  - correct doc links for become on warnings over world readable settings.

docs/docsite/README.md

@@ -11,7 +11,7 @@ Contributions to the documentation are welcome.
 
 The Ansible community produces guidance on contributions, building documentation, and submitting pull requests, which you can find in [Contributing to the Ansible Documentation](https://docs.ansible.com/ansible/latest/community/documentation_contributions.html).
 
-You can also join the [Docs Working Group](https://github.com/ansible/community/wiki/Docs) and/or the ``#ansible-docs`` channel on freenode IRC.
+You can also join the [Docs Working Group](https://github.com/ansible/community/wiki/Docs) and/or the ``#ansible-docs`` IRC channel on `irc.libera.chat <https://libera.chat/>`_
 
 Ansible style guide
 ===================

docs/docsite/_themes/sphinx_rtd_theme/ansible_banner.html

@@ -14,31 +14,40 @@
       current_url_path = window.location.pathname;
 
       if (startsWith(current_url_path, "/ansible-core/")) {
-        document.write('<div id="banner_id" class="admonition caution">');
+        document.write('<div id="core_banner_id" class="admonition caution">');
         document.write('<p>You are reading documentation for Ansible Core, which contains no plugins except for those in ansible.builtin. For documentation of the Ansible package, go to <a href="https://docs.ansible.com/ansible/latest">the latest documentation</a>.</p>');
         document.write('</div>');
 
       } else if (startsWith(current_url_path, "/ansible/latest/") || startsWith(current_url_path, "/ansible/{{ latest_version }}/")) {
-        document.write('<div id="banner_id" class="admonition caution">');
+        /* temp banner to advertise GalaxyNG survey */
+        document.write('<div id="latest_survey_banner_id" class="admonition important">');
+        document.write('<br><p>Please take our <a href="https://www.surveymonkey.co.uk/r/2VWVJY3">survey</a> to help us improve support for collections and roles in GalaxyNG.</p><br>');
+        document.write('</div>');
+
+        document.write('<div id="latest_banner_id" class="admonition caution">');
         document.write('<p>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.</p>');
         document.write('</div>');
 
       } else if (startsWith(current_url_path, "/ansible/2.9/")) {
-        document.write('<div id="banner_id" class="admonition caution">');
-        document.write('<p>You are reading the latest Red Hat released version of the Ansible documentation. Community users can use this, or select any version in version selection to the left, including <b>latest</b> for the most recent community version.</p>');
+        document.write('<div id="2dot9_banner_id" class="admonition caution">');
+        document.write('<p>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.</p>');
         document.write('</div>');
       } else if (startsWith(current_url_path, "/ansible/devel/")) {
+        /* temp banner to advertise GalaxyNG survey */
+        document.write('<div id="devel_survey_banner_id" class="admonition important">');
+        document.write('<br><p>Please take our <a href="https://www.surveymonkey.co.uk/r/2VWVJY3">survey</a> to help us improve support for collections and roles in GalaxyNG.</p><br>');
+        document.write('</div>');
         /* temp banner to advertise survey
-        document.write('<div id="banner_id" class="admonition important">');
+        document.write('<div id="devel_survey_banner_id" class="admonition important">');
         document.write('<br><p>Please take our <a href="https://www.surveymonkey.co.uk/r/B9V3CDY">Docs survey</a> before December 31 to help us improve Ansible documentation.</p><br>');
         document.write('</div>'); */
 
-        document.write('<div id="banner_id" class="admonition caution">');
+        document.write('<div id="devel_banner_id" class="admonition caution">');
         document.write('<p>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.</p>');
         document.write('</div>');
 
       } else {
-        document.write('<div id="banner_id" class="admonition caution">');
+        document.write('<div id="EOL_banner_id" class="admonition caution">');
         document.write('<p>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.</p>');
         document.write('</div>');
       }

docs/docsite/_themes/sphinx_rtd_theme/ansible_versions.html

@@ -13,10 +13,10 @@
             if ( "{{ slug }}" == "{{ current_version }}" ) {
               option.selected = true;
             }
-            if (current_url.search("{{ current_version }}") > -1) {
-              option.value = current_url.replace("{{ current_version }}","{{ slug }}");
+            if (current_url.search("/{{ current_version }}/") > -1) {
+              option.value = current_url.replace("/{{ current_version }}/","/{{ slug }}/");
             } else {
-              option.value = current_url.replace("latest","{{ slug }}");
+              option.value = current_url.replace("/latest/","/{{ slug }}/");
             }
             x.add(option);
           </script>

docs/docsite/requirements.txt

@@ -9,3 +9,4 @@ resolvelib
 Pygments >= 2.4.0
 straight.plugin # Needed for hacking/build-ansible.py which is the backend build script
 antsibull >= 0.25.0
+docutils==0.16 # pin for now until sphinx_rtd_theme is compatible with 0.17 or later

docs/docsite/rst/community/communication.rst

@@ -18,7 +18,7 @@ Mailing list information
 Ansible has several mailing lists.  Your first post to the mailing list will be moderated (to reduce spam), so please allow up to a day or so for your first post to appear.
 
 * `Ansible Announce list <https://groups.google.com/forum/#!forum/ansible-announce>`_ is a read-only list that shares information about new releases of Ansible, and also rare infrequent event information, such as announcements about an upcoming AnsibleFest, which is our official conference series. Worth subscribing to!
-* `Ansible AWX List <https://groups.google.com/forum/#!forum/awx-project>`_ is for `Ansible AWX <https://github.com/ansible/awx>`_ the upstream version of `Red Hat Ansible Tower <https://www.ansible.com/products/tower>`_
+* `Ansible AWX List <https://groups.google.com/forum/#!forum/awx-project>`_ is for `Ansible AWX <https://github.com/ansible/awx>`_ 
 * `Ansible Container List <https://groups.google.com/forum/#!forum/ansible-container>`_ is for users and developers of the Ansible Container project.
 * `Ansible Development List <https://groups.google.com/forum/#!forum/ansible-devel>`_ is for learning how to develop on Ansible, asking about prospective feature design, or discussions about extending ansible or features in progress.
 * `Ansible Lockdown List <https://groups.google.com/forum/#!forum/ansible-lockdown>`_ is for all things related to Ansible Lockdown projects, including DISA STIG automation and CIS Benchmarks.
@@ -33,21 +33,22 @@ To subscribe to a group from a non-Google account, you can send an email to the
 IRC channels
 ============
 
-Ansible has several IRC channels on `Freenode <https://freenode.net/>`_.
+Ansible has several IRC channels on `irc.libera.chat <https://libera.chat/>`_.
 
-Our IRC channels may require you to register your nickname. If you receive an error when you connect, see `Freenode's Nickname Registration guide <https://freenode.net/kb/answer/registration>`_ for instructions.
+Our IRC channels may require you to register your nickname. If you receive an error when you connect, see `libera.chat's Nickname Registration guide <https://libera.chat/guides/registration>`_ for instructions.
 
-To find all ``ansible`` specific channels on a freenode network, use the following command in your IRC client::
+To find all ``ansible`` specific channels on the libera.chat network, use the following command in your IRC client::
 
    /msg alis LIST #ansible* -min 5
 
-as described in `freenode docs <https://freenode.net/kb/answer/findingchannels>`_.
+as described in the `libera.chat docs <https://libera.chat/guides/findingchannels>`_.
 
 General channels
 ----------------
 
 - ``#ansible`` - For general use questions and support.
 - ``#ansible-devel`` - For discussions on developer topics and code related to features or bugs.
+- ``#ansible-community`` - For discussions on community and collections related topics. 
 - ``#ansible-meeting`` - For public community meetings. 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>`_
 
 .. _working_group_list:
@@ -55,11 +56,11 @@ General channels
 Working groups
 --------------
 
-Many of our community `Working Groups <https://github.com/ansible/community/wiki#working-groups>`_ meet on Freenode IRC channels. If you want to get involved in a working group, join the channel where it meets or comment on the agenda.
+Many of our community `Working Groups <https://github.com/ansible/community/wiki#working-groups>`_ meet on libera.chat IRC channels. If you want to get involved in a working group, join the channel where it meets or comment on the agenda.
 
 - `Amazon (AWS) Working Group <https://github.com/ansible/community/wiki/AWS>`_ - ``#ansible-aws``
 - `Ansible Lockdown Working Group <https://github.com/ansible/community/wiki/Lockdown>`_ | `gh/ansible/ansible-lockdown <https://github.com/ansible/ansible-lockdown>`_ - ``#ansible-lockdown``- Security playbooks/roles
-- `AWX Working Group <https://github.com/ansible/awx>`_ - ``#ansible-awx`` - Upstream for Ansible Tower
+- `AWX Working Group <https://github.com/ansible/awx>`_ - ``#ansible-awx``
 - `Azure Working Group <https://github.com/ansible/community/wiki/Azure>`_ - ``#ansible-azure``
 - `Community Working Group <https://github.com/ansible/community/wiki/Community>`_ - ``#ansible-community`` - Including Meetups
 - `Container Working Group <https://github.com/ansible/community/wiki/Container>`_ - ``#ansible-container``
@@ -95,13 +96,13 @@ IRC meetings
 The Ansible community holds regular IRC meetings on various topics, and anyone who is interested is invited to
 participate. For more information about Ansible meetings, consult the `meeting schedule and agenda page <https://github.com/ansible/community/blob/master/meetings/README.md>`_.
 
-Ansible Tower support questions
-===============================
+Ansible Automation Platform support questions
+=============================================
 
-Red Hat Ansible `Tower <https://www.ansible.com/products/tower>`_ is a UI, Server, and REST endpoint for Ansible.
-The Red Hat Ansible Automation subscription contains support for Ansible, Ansible Tower, Ansible Automation for Networking, and more.
+Red Hat Ansible `Automation Platform <https://www.ansible.com/products/automation-platform>`_ is a subscription that contains support, certified content, and tooling for Ansible including
+content management, a controller, UI and REST API.
 
-If you have a question about Ansible Tower, visit `Red Hat support <https://access.redhat.com/products/ansible-tower-red-hat/>`_ rather than using the IRC channel or the general project mailing list.
+If you have a question about Ansible Automation Platform, visit `Red Hat support <https://access.redhat.com/products/red-hat-ansible-automation-platform/>`_ rather than using the IRC channel or the general project mailing list.
 
 The Bullhorn
 ============

docs/docsite/rst/community/development_process.rst

@@ -22,8 +22,7 @@ If you want to follow the conversation about what features will be added to ``an
 * the :ref:`Ansible Release Schedule <release_and_maintenance>`
 * various GitHub `projects <https://github.com/ansible/ansible/projects>`_ - for example:
 
-   * the `2.10 release project <https://github.com/ansible/ansible/projects/39>`_
-   * the `network bugs project <https://github.com/ansible/ansible/projects/20>`_
+   * 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:
@@ -38,7 +37,7 @@ Here's an overview of the PR lifecycle:
 * Ansibot reviews the PR
 * Ansibot assigns labels
 * Ansibot pings maintainers
-* Shippable runs the test suite
+* Azure Pipelines runs the test suite
 * Developers, maintainers, community review the PR
 * Contributor addresses any feedback from reviewers
 * Developers, maintainers, community re-review
@@ -81,7 +80,7 @@ Ansibullbot runs continuously. You can generally expect to see changes to your i
 -  If the pull request is labeled **community_review** and the reviewer has not responded lately:
 
    -  The reviewer is first politely pinged after two weeks, pinged again after two more weeks and labeled **pending_action**, and then may be reassigned to ``$team_ansible`` or labeled **core_review**, or often the submitter of the pull request is asked to step up as a maintainer.
--  If Shippable tests fail, or if the code is not able to be merged, the pull request is automatically put into **needs_revision** along with a message to the submitter explaining why.
+-  If Azure Pipelines tests fail, or if the code is not able to be merged, the pull request is automatically put into **needs_revision** along with a message to the submitter explaining why.
 
 There are corner cases and frequent refinements, but this is the workflow in general.
 
@@ -143,7 +142,22 @@ We do not merge every PR. Here are some tips for making your PR useful, attracti
 Changelogs
 ----------
 
-Changelogs help users and developers keep up with changes to Ansible. Ansible builds a changelog for each release from fragments. You **must** add a changelog fragment to any PR that changes functionality or fixes a bug in ansible-core. You do not have to add a changelog fragment for PRs that add new modules and plugins, because our tooling does that for you automatically.
+Changelogs help users and developers keep up with changes to ansible-core and Ansible collections. Ansible and many collections build changelogs for each release from fragments. For ansible-core and collections using this model, you **must** add a changelog fragment to any PR that changes functionality or fixes a bug.
+
+You do not need a changelog fragment for PRs that:
+
+* add new modules and plugins, because Ansible tooling does that automatically;
+* contain only documentation changes.
+
+.. note::
+  Some collections require a changelog fragment for every pull request. They use the ``trivial:`` section for entries mentioned above that will be skipped when building a release changelog.
+
+
+More precisely:
+* Every bugfix PR must have a changelog fragment. The only exception are fixes to a change that has not yet been included in a release.
+* Every feature PR must have a changelog fragment.
+* New modules and plugins (except jinja2 filter and test plugins) must have ``versions_added`` set correctly, and do not need a changelog fragment. The tooling detects new modules and plugins by their ``versions_added`` value and announces them in the next release's changelog automatically.
+* New jinja2 filter and test plugins, and also new roles and playbooks (for collections) must have a changelog fragment. See :ref:`changelogs_how_to_format_j2_roles_playbooks` or the `antsibull-changelog documentation for such changelog fragments <https://github.com/ansible-community/antsibull-changelog/blob/main/docs/changelogs.rst#adding-new-roles-playbooks-test-and-filter-plugins>_` for information on how the fragments should look like.
 
 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.
 
@@ -154,6 +168,8 @@ Creating a changelog fragment
 
 A basic changelog fragment is a ``.yaml`` file placed in the ``changelogs/fragments/`` directory.  Each file contains a yaml dict with keys like ``bugfixes`` or ``major_changes`` followed by a list of changelog entries of bugfixes or features.  Each changelog entry is rst embedded inside of the yaml file which means that certain constructs would need to be escaped so they can be interpreted by rst and not by yaml (or escaped for both yaml and rst if you prefer).  Each PR **must** use a new fragment file rather than adding to an existing one, so we can trace the change back to the PR that introduced it.
 
+PRs which add a new module or plugin do not necessarily need a changelog fragment. See the previous section :ref:`community_changelogs`. Also see the next section :ref:`changelogs_how_to_format` for the precise format changelog fragments should have.
+
 To create a changelog entry, create a new file with a unique name in the ``changelogs/fragments/`` directory of the corresponding repository. The file name should include the PR number and a description of the change. It must end with the file extension ``.yaml``. For example: ``40696-user-backup-shadow-file.yaml``
 
 A single changelog fragment may contain multiple sections but most will only contain one section. The toplevel keys (bugfixes, major_changes, and so on) are defined in the `config file <https://github.com/ansible/ansible/blob/devel/changelogs/config.yaml>`_ for our `release note tool <https://github.com/ansible-community/antsibull-changelog/blob/main/docs/changelogs.rst>`_. Here are the valid sections and a description of each:
@@ -186,6 +202,8 @@ Each changelog entry must contain a link to its issue between parentheses at the
 
 Most changelog entries are ``bugfixes`` or ``minor_changes``.
 
+.. _changelogs_how_to_format:
+
 Changelog fragment entry format
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -224,10 +242,57 @@ Here are some examples:
       remote_src=True even if mode was not set as a parameter.  This failed on
       filesystems which do not have permission bits (https://github.com/ansible/ansible/issues/29444).
 
-You can find more example changelog fragments in the `changelog directory <https://github.com/ansible/ansible/tree/stable-2.10/changelogs/fragments>`_ for the 2.10 release.
+You can find more example changelog fragments in the `changelog directory <https://github.com/ansible/ansible/tree/stable-2.11/changelogs/fragments>`_ for the 2.11 release.
 
 After you have written the changelog fragment for your PR, commit the file and include it with the pull request.
 
+.. _changelogs_how_to_format_j2_roles_playbooks:
+
+Changelog fragment entry format for new jinja2 plugins, roles, and playbooks
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+While new modules and plugins that are not jinja2 filter or test plugins are mentioned automatically in the generated changelog, jinja2 filter and test plugins, roles, and playbooks are not. To make sure they are mentioned, a changelog fragment in a specific format is needed:
+
+.. code-block:: yaml
+
+    # A new jinja2 filter plugin:
+    add plugin.filter:
+      - # The following needs to be the name of the filter itself, not of the file
+        # the filter is included in!
+        name: to_time_unit
+        # The description should be in the same format as short_description for
+        # other plugins and modules: it should start with an upper-case letter and
+        # not have a period at the end.
+        description: Converts a time expression to a given unit
+
+    # A new jinja2 test plugin:
+    add plugin.test:
+      - # The following needs to be the name of the test itself, not of the file
+        # the test is included in!
+        name: asn1time
+        # The description should be in the same format as short_description for
+        # other plugins and modules: it should start with an upper-case letter and
+        # not have a period at the end.
+        description: Check whether the given string is an ASN.1 time
+
+    # A new role:
+    add object.role:
+      - # This should be the short (non-FQCN) name of the role.
+        name: nginx
+        # The description should be in the same format as short_description for
+        # plugins and modules: it should start with an upper-case letter and
+        # not have a period at the end.
+        description: A nginx installation role
+
+    # A new playbook:
+    add object.playbook:
+      - # This should be the short (non-FQCN) name of the playbook.
+        name: wipe_server
+        # The description should be in the same format as short_description for
+        # plugins and modules: it should start with an upper-case letter and
+        # not have a period at the end.
+        description: Wipes a server
+
 .. _backport_process:
 
 Backporting merged PRs in ``ansible-core``
@@ -241,23 +306,18 @@ We do **not** backport features.
 
    These instructions assume that:
 
-    * ``stable-2.10`` 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.
+    * ``stable-2.11`` is the targeted release branch for the backport
+    * ``https://github.com/ansible/ansible.git`` is configured as a ``git remote`` named ``upstream``. If you do not use a ``git remote`` named ``upstream``, adjust the instructions accordingly.
+    * ``https://github.com/<yourgithubaccount>/ansible.git`` is configured as a ``git remote`` named ``origin``. If you do not use a ``git remote`` named ``origin``, adjust the instructions accordingly.
 
 #. Prepare your devel, stable, and feature branches:
 
    ::
 
        git fetch upstream
-       git checkout -b backport/2.10/[PR_NUMBER_FROM_DEVEL] upstream/stable-2.10
+       git checkout -b backport/2.11/[PR_NUMBER_FROM_DEVEL] upstream/stable-2.11
 
-#. Cherry pick the relevant commit SHA from the devel branch into your feature
-   branch, handling merge conflicts as necessary:
+#. Cherry pick the relevant commit SHA from the devel branch into your feature branch, handling merge conflicts as necessary:
 
    ::
 
@@ -269,27 +329,16 @@ We do **not** backport features.
 
    ::
 
-       git push origin backport/2.10/[PR_NUMBER_FROM_DEVEL]
+       git push origin backport/2.11/[PR_NUMBER_FROM_DEVEL]
 
-#. Submit the pull request for ``backport/2.10/[PR_NUMBER_FROM_DEVEL]``
-   against the ``stable-2.10`` branch
+#. Submit the pull request for ``backport/2.11/[PR_NUMBER_FROM_DEVEL]`` against the ``stable-2.11`` 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.
+#. 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 choice to use ``backport/2.10/[PR_NUMBER_FROM_DEVEL]`` as the
-    name for the feature branch is somewhat arbitrary, but conveys meaning
-    about the purpose of that branch. It is not required to use this format,
-    but it can be helpful, especially when making multiple backport PRs for
-    multiple stable branches.
+    The branch name ``backport/2.11/[PR_NUMBER_FROM_DEVEL]`` is somewhat arbitrary, but conveys meaning about the purpose of the branch. This branch name format is not required, but it can be helpful, especially when making multiple backport PRs for multiple stable branches.
 
 .. note::
 
-    If you prefer, you can use CPython's cherry-picker tool
-    (``pip install --user 'cherry-picker >= 1.3.2'``) to backport commits
-    from devel to stable branches in Ansible. Take a look at the `cherry-picker
-    documentation <https://pypi.org/p/cherry-picker#cherry-picking>`_ for
-    details on installing, configuring, and using it.
+    If you prefer, you can use CPython's cherry-picker tool (``pip install --user 'cherry-picker >= 1.3.2'``) to backport commits from devel to stable branches in Ansible. Take a look at the `cherry-picker documentation <https://pypi.org/p/cherry-picker#cherry-picking>`_ for details on installing, configuring, and using it.

docs/docsite/rst/community/documentation_contributions.rst

@@ -206,7 +206,7 @@ Unfortunately, leftover rST-files from previous document-generating can occasion
 Joining the documentation working group
 =======================================
 
-The Documentation Working Group (DaWGs) meets weekly on Tuesdays on the #ansible-docs channel on freenode IRC. For more information, including links to our agenda and a calendar invite, please visit the `working group page in the community repo <https://github.com/ansible/community/wiki/Docs>`_.
+The Documentation Working Group (DaWGs) meets weekly on Tuesdays on the #ansible-docs channel on the `libera.chat IRC network <https://libera.chat/>`_. For more information, including links to our agenda and a calendar invite, please visit the `working group page in the community repo <https://github.com/ansible/community/wiki/Docs>`_.
 
 .. seealso::
    :ref:`More about testing module documentation <testing_module_documentation>`

docs/docsite/rst/community/other_tools_and_programs.rst

@@ -115,7 +115,7 @@ Other tools
 - `Ansigenome <https://github.com/nickjj/ansigenome>`_ - a command line tool designed to help you manage your Ansible roles.
 - `ARA <https://github.com/openstack/ara>`_ - records Ansible playbook runs and makes the recorded data available and intuitive for users and systems by integrating with Ansible as a callback plugin.
 - `Awesome Ansible <https://github.com/jdauphant/awesome-ansible>`_ - a collaboratively curated list of awesome Ansible resources.
-- `AWX <https://github.com/ansible/awx>`_ - provides a web-based user interface, REST API, and task engine built on top of Ansible. AWX is the upstream project for Red Hat Ansible Tower, part of the Red Hat Ansible Automation subscription.
+- `AWX <https://github.com/ansible/awx>`_ - provides a web-based user interface, REST API, and task engine built on top of Ansible. Red Hat Ansible Automation Platform includes code from AWX.
 - `Mitogen for Ansible <https://mitogen.networkgenomics.com/ansible_detailed.html>`_ - uses the `Mitogen <https://github.com/dw/mitogen/>`_ library to execute Ansible playbooks in a more efficient way (decreases the execution time).
 - `nanvault <https://github.com/marcobellaccini/nanvault>`_ - a standalone tool to encrypt and decrypt files in the Ansible Vault format, featuring UNIX-style composability.
 - `OpsTools-ansible <https://github.com/centos-opstools/opstools-ansible>`_ - uses Ansible to configure an environment that provides the support of `OpsTools <https://wiki.centos.org/SpecialInterestGroup/OpsTools>`_, namely centralized logging and analysis, availability monitoring, and performance monitoring.

docs/docsite/rst/community/release_managers.rst

@@ -13,7 +13,6 @@ coordinate between:
 * Contributors without commit privileges
 * The community
 * Ansible documentation team
-* Ansible Tower team
 
 Pre-releases: what and why
 ==========================
@@ -70,7 +69,7 @@ The last RC should be as close to the final as possible. The following things ma
 .. note:: We want to specifically emphasize that code (in :file:`bin/`, :file:`lib/ansible/`, and
     :file:`setup.py`) must be the same unless there are extraordinary extenuating circumstances.  If
     there are extenuating circumstances, the Release Manager is responsible for notifying groups
-    (like the Tower Team) which would want to test the code.
+    which would want to test the code.
 
 
 Ansible release process

docs/docsite/rst/dev_guide/developing_api.rst

@@ -14,7 +14,7 @@ write plugins, and you can plug in inventory data from external data sources.  T
 gives a basic overview and examples of the Ansible execution and playbook API.
 
 If you would like to use Ansible programmatically from a language other than Python, trigger events asynchronously,
-or have access control and logging demands, please see the `Ansible Tower documentation <https://docs.ansible.com/ansible-tower/>`_.
+or have access control and logging demands, please see the `AWX project <https://github.com/ansible/awx/>`_.
 
 .. note:: Because Ansible relies on forking processes, this API is not thread safe.
 
@@ -43,5 +43,5 @@ command line tools (``lib/ansible/cli/``) is `available on GitHub <https://githu
        How to develop plugins
    `Development Mailing List <https://groups.google.com/group/ansible-devel>`_
        Mailing list for development topics
-   `irc.freenode.net <http://irc.freenode.net>`_
+   `irc.libera.chat <https://libera.chat>`_
        #ansible IRC chat channel

docs/docsite/rst/dev_guide/developing_collections.rst

@@ -1,826 +1,48 @@
-
 .. _developing_collections:
 
 **********************
 Developing collections
 **********************
 
-Collections are a distribution format for Ansible content. You can package and distribute playbooks, roles, modules, and plugins using collections.
+Collections are a distribution format for Ansible content. You can package and distribute playbooks, roles, modules, and plugins using collections. A typical collection addresses a set of related use cases. For example, the ``cisco.ios`` collection automates management of Cisco IOS devices.
 
-You can publish any collection to `Ansible Galaxy <https://galaxy.ansible.com>`_ or to a private Automation Hub instance. You can publish certified collections to the Red Hat Automation Hub, part of the Red Hat Ansible Automation Platform.
+You can create a collection and publish it to `Ansible Galaxy <https://galaxy.ansible.com>`_ or to a private Automation Hub instance. You can publish certified collections to the Red Hat Automation Hub, part of the Red Hat Ansible Automation Platform.
 
-* For details on how to *use* collections see :ref:`collections`.
-* For the current development status of Collections and FAQ see `Ansible Collections Overview and FAQ <https://github.com/ansible-collections/overview/blob/main/README.rst>`_.
+.. toctree::
+   :maxdepth: 2
+   :caption: Developing new collections
 
-.. contents::
-   :local:
-   :depth: 2
+   developing_collections_creating
+   developing_collections_shared
+   developing_collections_testing
+   developing_collections_distributing
 
-.. _collection_structure:
+.. toctree::
+   :maxdepth: 2
+   :caption: Working with existing collections
 
-Collection structure
-====================
+   developing_collections_migrating
+   developing_collections_contributing
+   developing_collections_changelogs
 
-Collections follow a simple data structure. None of the directories are required unless you have specific content that belongs in one of them. A collection does require a ``galaxy.yml`` file at the root level of the collection. This file contains all of the metadata that Galaxy and other tools need in order to package, build and publish the collection::
+.. toctree::
+   :maxdepth: 2
+   :caption: Collections references
 
-    collection/
-    ├── docs/
-    ├── galaxy.yml
-    ├── meta/
-    │   └── runtime.yml
-    ├── plugins/
-    │   ├── modules/
-    │   │   └── module1.py
-    │   ├── inventory/
-    │   └── .../
-    ├── README.md
-    ├── roles/
-    │   ├── role1/
-    │   ├── role2/
-    │   └── .../
-    ├── playbooks/
-    │   ├── files/
-    │   ├── vars/
-    │   ├── templates/
-    │   └── tasks/
-    └── tests/
+   developing_collections_structure
+   collections_galaxy_meta
 
-
-.. note::
-    * Ansible only accepts ``.md`` extensions for the :file:`README` file and any files in the :file:`/docs` folder.
-    * See the `ansible-collections <https://github.com/ansible-collections/>`_ GitHub Org for examples of collection structure.
-    * Not all directories are currently in use. Those are placeholders for future features.
-
-.. _galaxy_yml:
-
-galaxy.yml
-----------
-
-A collection must have a ``galaxy.yml`` file that contains the necessary information to build a collection artifact.
-See :ref:`collections_galaxy_meta` for details.
-
-.. _collections_doc_dir:
-
-docs directory
----------------
-
-Put general documentation for the collection here. Keep the specific documentation for plugins and modules embedded as Python docstrings. Use the ``docs`` folder to describe how to use the roles and plugins the collection provides, role requirements, and so on. Use markdown and do not add subfolders.
-
-Use ``ansible-doc`` to view documentation for plugins inside a collection:
-
-.. code-block:: bash
-
-    ansible-doc -t lookup my_namespace.my_collection.lookup1
-
-The ``ansible-doc`` command requires the fully qualified collection name (FQCN) to display specific plugin documentation. In this example, ``my_namespace`` is the Galaxy namespace and ``my_collection`` is the collection name within that namespace.
-
-.. note:: The Galaxy namespace of an Ansible collection is defined in the ``galaxy.yml`` file. It can be different from the GitHub organization or repository name.
-
-.. _collections_plugin_dir:
-
-plugins directory
-------------------
-
-Add a 'per plugin type' specific subdirectory here, including ``module_utils`` which is usable not only by modules, but by most plugins by using their FQCN. This is a way to distribute modules, lookups, filters, and so on without having to import a role in every play.
-
-Vars plugins are unsupported in collections. Cache plugins may be used in collections for fact caching, but are not supported for inventory plugins.
-
-.. _collection_module_utils:
-
-module_utils
-^^^^^^^^^^^^
-
-When coding with ``module_utils`` in a collection, the Python ``import`` statement needs to take into account the FQCN along with the ``ansible_collections`` convention. The resulting Python import will look like ``from ansible_collections.{namespace}.{collection}.plugins.module_utils.{util} import {something}``
-
-The following example snippets show a Python and PowerShell module using both default Ansible ``module_utils`` and
-those provided by a collection. In this example the namespace is ``community``, the collection is ``test_collection``.
-In the Python example the ``module_util`` in question is called ``qradar`` such that the FQCN is
-``community.test_collection.plugins.module_utils.qradar``:
-
-.. code-block:: python
-
-    from ansible.module_utils.basic import AnsibleModule
-    from ansible.module_utils._text import to_text
-
-    from ansible.module_utils.six.moves.urllib.parse import urlencode, quote_plus
-    from ansible.module_utils.six.moves.urllib.error import HTTPError
-    from ansible_collections.community.test_collection.plugins.module_utils.qradar import QRadarRequest
-
-    argspec = dict(
-        name=dict(required=True, type='str'),
-        state=dict(choices=['present', 'absent'], required=True),
-    )
-
-    module = AnsibleModule(
-        argument_spec=argspec,
-        supports_check_mode=True
-    )
-
-    qradar_request = QRadarRequest(
-        module,
-        headers={"Content-Type": "application/json"},
-        not_rest_data_keys=['state']
-    )
-
-Note that importing something from an ``__init__.py`` file requires using the file name:
-
-.. code-block:: python
-
-    from ansible_collections.namespace.collection_name.plugins.callback.__init__ import CustomBaseClass
-
-In the PowerShell example the ``module_util`` in question is called ``hyperv`` such that the FQCN is
-``community.test_collection.plugins.module_utils.hyperv``:
-
-.. code-block:: powershell
-
-    #!powershell
-    #AnsibleRequires -CSharpUtil Ansible.Basic
-    #AnsibleRequires -PowerShell ansible_collections.community.test_collection.plugins.module_utils.hyperv
-
-    $spec = @{
-        name = @{ required = $true; type = "str" }
-        state = @{ required = $true; choices = @("present", "absent") }
-    }
-    $module = [Ansible.Basic.AnsibleModule]::Create($args, $spec)
-
-    Invoke-HyperVFunction -Name $module.Params.name
-
-    $module.ExitJson()
-
-.. _collections_roles_dir:
-
-roles directory
-----------------
-
-Collection roles are mostly the same as existing roles, but with a couple of limitations:
-
- - Role names are now limited to contain only lowercase alphanumeric characters, plus ``_`` and start with an alpha character.
- - Roles in a collection cannot contain plugins any more. Plugins must live in the collection ``plugins`` directory tree. Each plugin is accessible to all roles in the collection.
-
-The directory name of the role is used as the role name. Therefore, the directory name must comply with the
-above role name rules.
-The collection import into Galaxy will fail if a role name does not comply with these rules.
-
-You can migrate 'traditional roles' into a collection but they must follow the rules above. You may need to rename roles if they don't conform. You will have to move or link any role-based plugins to the collection specific directories.
-
-.. note::
-
-    For roles imported into Galaxy directly from a GitHub repository, setting the ``role_name`` value in the role's metadata overrides the role name used by Galaxy. For collections, that value is ignored. When importing a collection, Galaxy uses the role directory as the name of the role and ignores the ``role_name`` metadata value.
-
-playbooks directory
---------------------
-
-TBD.
-
-.. _developing_collections_tests_directory:
-
-tests directory
-----------------
-
-Ansible Collections are tested much like Ansible itself, by using the
-`ansible-test` utility which is released as part of Ansible, version 2.9.0 and
-newer. Because Ansible Collections are tested using the same tooling as Ansible
-itself, via `ansible-test`, all Ansible developer documentation for testing is
-applicable for authoring Collections Tests with one key concept to keep in mind.
-
-See :ref:`testing_collections` for specific information on how to test collections
-with ``ansible-test``.
-
-When reading the :ref:`developing_testing` documentation, there will be content
-that applies to running Ansible from source code via a git clone, which is
-typical of an Ansible developer. However, it's not always typical for an Ansible
-Collection author to be running Ansible from source but instead from a stable
-release, and to create Collections it is not necessary to run Ansible from
-source. Therefore, when references of dealing with `ansible-test` binary paths,
-command completion, or environment variables are presented throughout the
-:ref:`developing_testing` documentation; keep in mind that it is not needed for
-Ansible Collection Testing because the act of installing the stable release of
-Ansible containing `ansible-test` is expected to setup those things for you.
-
-.. _meta_runtime_yml:
-
-meta directory
---------------
-
-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:
-
-- *requires_ansible*:
-
-  The version of Ansible required to use the collection. Multiple versions can be separated with a comma.
-
-  .. code:: yaml
-
-     requires_ansible: ">=2.10,<2.11"
-
-  .. note:: although the version is a `PEP440 Version Specifier <https://www.python.org/dev/peps/pep-0440/#version-specifiers>`_ under the hood, Ansible deviates from PEP440 behavior by truncating prerelease segments from the Ansible version. This means that Ansible 2.11.0b1 is compatible with something that ``requires_ansible: ">=2.11"``.
-
-- *plugin_routing*:
-
-  Content in a collection that Ansible needs to load from another location or that has been deprecated/removed.
-  The top level keys of ``plugin_routing`` are types of plugins, with individual plugin names as subkeys.
-  To define a new location for a plugin, set the ``redirect`` field to another name.
-  To deprecate a plugin, use the ``deprecation`` field to provide a custom warning message and the removal version or date. If the plugin has been renamed or moved to a new location, the ``redirect`` field should also be provided. If a plugin is being removed entirely, ``tombstone`` can be used for the fatal error message and removal version or date.
-
-  .. code:: yaml
-
-     plugin_routing:
-       inventory:
-         kubevirt:
-           redirect: community.general.kubevirt
-         my_inventory:
-           tombstone:
-             removal_version: "2.0.0"
-             warning_text: my_inventory has been removed. Please use other_inventory instead.
-       modules:
-         my_module:
-           deprecation:
-             removal_date: "2021-11-30"
-             warning_text: my_module will be removed in a future release of this collection. Use another.collection.new_module instead.
-           redirect: another.collection.new_module
-         podman_image:
-           redirect: containers.podman.podman_image
-       module_utils:
-         ec2:
-           redirect: amazon.aws.ec2
-         util_dir.subdir.my_util:
-           redirect: namespace.name.my_util
-
-- *import_redirection*
-
-  A mapping of names for Python import statements and their redirected locations.
-
-  .. code:: yaml
-
-     import_redirection:
-       ansible.module_utils.old_utility:
-         redirect: ansible_collections.namespace_name.collection_name.plugins.module_utils.new_location
-
-
-.. _creating_collections_skeleton:
-
-Creating a collection skeleton
-------------------------------
-
-To start a new collection:
-
-.. code-block:: bash
-
-    collection_dir#> ansible-galaxy collection init my_namespace.my_collection
-
-.. note::
-
-	Both the namespace and collection names use the same strict set of requirements. See `Galaxy namespaces <https://galaxy.ansible.com/docs/contributing/namespaces.html#galaxy-namespaces>`_ on the Galaxy docsite for those requirements.
-
-Once the skeleton exists, you can populate the directories with the content you want inside the collection. See `ansible-collections <https://github.com/ansible-collections/>`_ GitHub Org to get a better idea of what you can place inside a collection.
-
-.. _creating_collections:
-
-Creating collections
-======================
-
-To create a collection:
-
-#. Create a collection skeleton with the ``collection init`` command. See :ref:`creating_collections_skeleton` above.
-#. Add your content to the collection.
-#. Build the collection into a collection artifact with :ref:`ansible-galaxy collection build<building_collections>`.
-#. Publish the collection artifact to Galaxy with :ref:`ansible-galaxy collection publish<publishing_collections>`.
-
-A user can then install your collection on their systems.
-
-Currently the ``ansible-galaxy collection`` command implements the following sub commands:
-
-* ``init``: Create a basic collection skeleton based on the default template included with Ansible or your own template.
-* ``build``: Create a collection artifact that can be uploaded to Galaxy or your own repository.
-* ``publish``: Publish a built collection artifact to Galaxy.
-* ``install``: Install one or more collections.
-
-To learn more about the ``ansible-galaxy`` command-line tool, see the :ref:`ansible-galaxy` man page.
-
-
-.. _docfragments_collections:
-
-Using documentation fragments in collections
---------------------------------------------
-
-To include documentation fragments in your collection:
-
-#. Create the documentation fragment: ``plugins/doc_fragments/fragment_name``.
-
-#. Refer to the documentation fragment with its FQCN.
-
-.. code-block:: yaml
-
-   extends_documentation_fragment:
-     - community.kubernetes.k8s_name_options
-     - community.kubernetes.k8s_auth_options
-     - community.kubernetes.k8s_resource_options
-     - community.kubernetes.k8s_scale_options
-
-:ref:`module_docs_fragments` covers the basics for documentation fragments. The `kubernetes <https://github.com/ansible-collections/kubernetes>`_ collection includes a complete example.
-
-You can also share documentation fragments across collections with the FQCN.
-
-.. _building_collections:
-
-Building collections
---------------------
-
-To build a collection, run ``ansible-galaxy collection build`` from inside the root directory of the collection:
-
-.. code-block:: bash
-
-    collection_dir#> ansible-galaxy collection build
-
-This creates a tarball of the built collection in the current directory which can be uploaded to Galaxy.::
-
-    my_collection/
-    ├── galaxy.yml
-    ├── ...
-    ├── my_namespace-my_collection-1.0.0.tar.gz
-    └── ...
-
-.. note::
-   * Certain files and folders are excluded when building the collection artifact. See :ref:`ignoring_files_and_folders_collections`  to exclude other files you would not want to distribute.
-   * If you used the now-deprecated ``Mazer`` tool for any of your collections, delete any and all files it added to your :file:`releases/` directory before you build your collection with ``ansible-galaxy``.
-   * The current Galaxy maximum tarball size is 2 MB.
-
-
-This tarball is mainly intended to upload to Galaxy
-as a distribution method, but you can use it directly to install the collection on target systems.
-
-.. _ignoring_files_and_folders_collections:
-
-Ignoring files and folders
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-By default the build step will include all the files in the collection directory in the final build artifact except for the following:
-
-* ``galaxy.yml``
-* ``*.pyc``
-* ``*.retry``
-* ``tests/output``
-* previously built artifacts in the root directory
-* various version control directories like ``.git/``
-
-To exclude other files and folders when building the collection, you can set a list of file glob-like patterns in the
-``build_ignore`` key in the collection's ``galaxy.yml`` file. These patterns use the following special characters for
-wildcard matching:
-
-* ``*``: Matches everything
-* ``?``: Matches any single character
-* ``[seq]``: Matches and character in seq
-* ``[!seq]``:Matches any character not in seq
-
-For example, if you wanted to exclude the :file:`sensitive` folder within the ``playbooks`` folder as well any ``.tar.gz`` archives you
-can set the following in your ``galaxy.yml`` file:
-
-.. code-block:: yaml
-
-     build_ignore:
-     - playbooks/sensitive
-     - '*.tar.gz'
-
-.. note::
-     This feature is only supported when running ``ansible-galaxy collection build`` with Ansible 2.10 or newer.
-
-
-.. _trying_collection_locally:
-
-Trying collections locally
---------------------------
-
-You can try your collection locally by installing it from the tarball. The following will enable an adjacent playbook to
-access the collection:
-
-.. code-block:: bash
-
-   ansible-galaxy collection install my_namespace-my_collection-1.0.0.tar.gz -p ./collections
-
-
-You should use one of the values configured in :ref:`COLLECTIONS_PATHS` for your path. This is also where Ansible itself will
-expect to find collections when attempting to use them. If you don't specify a path value, ``ansible-galaxy collection install``
-installs the collection in the first path defined in :ref:`COLLECTIONS_PATHS`, which by default is ``~/.ansible/collections``.
-
-If you want to use a collection directly out of a checked out git repository, see :ref:`hacking_collections`.
-
-Next, try using the local collection inside a playbook. For examples and more details see :ref:`Using collections <using_collections>`
-
-.. _collections_scm_install:
-
-Installing collections from a git repository
---------------------------------------------
-
-You can also test a version of your collection in development by installing it from a git repository.
-
-.. code-block:: bash
-
-   ansible-galaxy collection install git+https://github.com/org/repo.git,devel
-
-.. include:: ../shared_snippets/installing_collections_git_repo.txt
-
-.. _publishing_collections:
-
-Distributing collections
-========================
-
-You can distribute your collections by publishing them on a distribution server. Distribution servers include Ansible Galaxy, Red Hat Automation Hub, and privately hosted Automation Hub instances. You can publish any collection to Ansible Galaxy and/or to a privately hosted Automation Hub instance. If your collection is certified by Red Hat, you can publish it to the Red Hat Automation Hub.
-
-Prerequisites
--------------
-
-1. Get a namespace on each distribution server you want to use (Galaxy, private Automation Hub, Red Hat Automation Hub).
-2. Get an API token for each distribution server you want to use.
-3. Specify your API token(s).
-
-Getting a namespace
-^^^^^^^^^^^^^^^^^^^
-
-You need a namespace on Galaxy and/or Automation Hub to upload your collection. To get a namespace:
-
-* For Galaxy, see `Galaxy namespaces <https://galaxy.ansible.com/docs/contributing/namespaces.html#galaxy-namespaces>`_ on the Galaxy docsite for details.
-* For Automation Hub, see the `Ansible Certified Content FAQ <https://access.redhat.com/articles/4916901>`_.
-
-.. _galaxy_get_token:
-
-Getting your API token
-^^^^^^^^^^^^^^^^^^^^^^
-
-You need an API token for Galaxy and/or Automation Hub to upload your collection. Use the API token(s) to authenticate your connection to the distribution server(s) and protect your content.
-
-To get your API token:
-
-* For Galaxy, go to the `Galaxy profile preferences <https://galaxy.ansible.com/me/preferences>`_ page and click :guilabel:`API Key`.
-* For Automation Hub, go to `the token page <https://cloud.redhat.com/ansible/automation-hub/token/>`_ and click :guilabel:`Load token`.
-
-Specifying your API token
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Once you have retrieved your API token, you can specify the correct token for each distribution server in two ways:
-
-* Pass the token to  the ``ansible-galaxy`` command using the ``--token``.
-* Configure the token within a Galaxy server list in your :file:`ansible.cfg` file.
-
-Specifying your API token with the ``--token`` argument
-.......................................................
-
-You can use the ``--token`` argument with the ``ansible-galaxy`` command (in conjunction with the ``--server`` argument or :ref:`GALAXY_SERVER` setting in your :file:`ansible.cfg` file). You cannot use ``apt-key`` with any servers defined in your :ref:`Galaxy server list <galaxy_server_config>`.
-
-.. code-block:: text
-
-    ansible-galaxy collection publish ./geerlingguy-collection-1.2.3.tar.gz --token=<key goes here>
-
-Specifying your API token with a Galaxy server list
-...................................................
-
-You can configure one or more distribution servers for Galaxy in your :file:`ansible.cfg` file under the ``galaxy_server_list`` section. For each server, you also configure the token.
-
-
-.. code-block:: ini
-
-   [galaxy]
-   server_list = release_galaxy
-
-   [galaxy_server.release_galaxy]
-   url=https://galaxy.ansible.com/
-   token=my_token
-
-See :ref:`galaxy_server_config` for complete details.
-
-Publishing a collection
------------------------
-
-Once you have a namespace and an API token for each distribution server you want to use, you can distribute your collection by publishing it to Ansible Galaxy, Red Hat Automation Hub, or a privately hosted Automation Hub instance. You can use either the ``ansible-galaxy collection publish`` command or the distribution server (Galaxy, Automation Hub) itself.
-
-Each time you add features or make changes to your collection, you must publish a new version of the collection. For details on versioning, see :ref:`collection_versions`.
-
-.. _upload_collection_ansible_galaxy:
-
-Publish a collection using ``ansible-galaxy``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. note::
-  By default, ``ansible-galaxy`` uses https://galaxy.ansible.com as the Galaxy server (as listed in the :file:`ansible.cfg` file under :ref:`galaxy_server`). If you are only publishing your collection to Ansible Galaxy, you do not need any further configuration. If you are using Red Hat Automation Hub or any other Galaxy server, see :ref:`Configuring the ansible-galaxy client <galaxy_server_config>`.
-
-To upload the collection artifact with the ``ansible-galaxy`` command:
-
-.. code-block:: bash
-
-     ansible-galaxy collection publish path/to/my_namespace-my_collection-1.0.0.tar.gz
-
-.. note::
-
-	The above command assumes you have retrieved and stored your API token as part of a Galaxy server list. See :ref:`galaxy_get_token` for details.
-
-The ``ansible-galaxy collection publish`` command triggers an import process, just as if you uploaded the collection through the Galaxy website. The command waits until the import process completes before reporting the status back. If you want to continue without waiting for the import result, use the ``--no-wait`` argument and manually look at the import progress in your `My Imports <https://galaxy.ansible.com/my-imports/>`_ page.
-
-
-.. _upload_collection_galaxy:
-
-Publishing a collection using the Galaxy website
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-To publish your collection directly on the Galaxy website:
-
-#. Go to the `My Content <https://galaxy.ansible.com/my-content/namespaces>`_ page, and click the **Add Content** button on one of your namespaces.
-#. From the **Add Content** dialogue, click **Upload New Collection**, and select the collection archive file from your local filesystem.
-
-When you upload a collection, it always uploads to the namespace specified in the collection metadata in the ``galaxy.yml`` file, no matter which namespace you select on the website. If you are not an owner of the namespace specified in your collection metadata, the upload request will fail.
-
-Once Galaxy uploads and accepts a collection, you will be redirected to the **My Imports** page, which displays output from the import process, including any errors or warnings about the metadata and content contained in the collection.
-
-.. _collection_versions:
-
-Collection versions
-^^^^^^^^^^^^^^^^^^^
-
-Each time you publish your collection, you create a new version. Once you publish a version of a collection, you cannot delete or modify that version. Ensure that everything looks okay before publishing. The only way to change a collection is to release a new version. The latest version of a collection (by highest version number) will be the version displayed everywhere in Galaxy or Automation Hub; however, users will still be able to download older versions.
-
-Collection versions use `Semantic Versioning <https://semver.org/>`_ for version numbers. Please read the official documentation for details and examples. In summary:
-
-* Increment major (for example: x in `x.y.z`) version number for an incompatible API change.
-* Increment minor (for example: y in `x.y.z`) version number for new functionality in a backwards compatible manner (for example new modules/plugins, parameters, return values).
-* Increment patch (for example: z in `x.y.z`) version number for backwards compatible bug fixes.
-
-.. _migrate_to_collection:
-
-Migrating Ansible content to a different collection
-====================================================
-
-First, look at `Ansible Collection Checklist <https://github.com/ansible-collections/overview/blob/main/collection_requirements.rst>`_.
-
-To migrate content from one collection to another, if the collections are parts of `Ansible distribution <https://github.com/ansible-community/ansible-build-data/blob/main/2.10/ansible.in>`_:
-
-#. Copy content from the source (old) collection to the target (new) collection.
-#. Deprecate the module/plugin with ``removal_version`` scheduled for the next major version in ``meta/runtime.yml`` of the old collection. The deprecation must be released after the copied content has been included in a release of the new collection.
-#. When the next major release of the old collection is prepared:
-
-  * remove the module/plugin from the old collection
-  * remove the symlink stored in ``plugin/modules`` directory if appropriate (mainly when removing from ``community.general`` and ``community.network``)
-  * remove related unit and integration tests
-  * remove specific module utils
-  * remove specific documentation fragments if there are any in the old collection
-  * add a changelog fragment containing entries for ``removed_features`` and ``breaking_changes``; you can see an example of a changelog fragment in this `pull request <https://github.com/ansible-collections/community.general/pull/1304>`_ 
-  * change ``meta/runtime.yml`` in the old collection:
-
-    * add ``redirect`` to the corresponding module/plugin's entry
-    * in particular, add ``redirect`` for the removed module utils and documentation fragments if applicable
-    * remove ``removal_version`` from there
-  * remove related entries from ``tests/sanity/ignore.txt`` files if exist
-  * remove changelog fragments for removed content that are not yet part of the changelog (in other words, do not modify `changelogs/changelog.yaml` and do not delete files mentioned in it)
-  * remove requirements that are no longer required in ``tests/unit/requirements.txt``, ``tests/requirements.yml`` and ``galaxy.yml``
-
-According to the above, you need to create at least three PRs as follows:
-
-#. Create a PR against the new collection to copy the content.
-#. Deprecate the module/plugin in the old collection.
-#. Later create a PR against the old collection to remove the content according to the schedule.
-
-
-Adding the content to the new collection
-----------------------------------------
-
-Create a PR in the new collection to:
-
-#. Copy ALL the related files from the old collection.
-#. If it is an action plugin, include the corresponding module with documentation.
-#. If it is a module, check if it has a corresponding action plugin that should move with it.
-#. Check ``meta/`` for relevant updates to ``runtime.yml`` if it exists.
-#. Carefully check the moved ``tests/integration`` and ``tests/units`` and update for FQCN.
-#. Review ``tests/sanity/ignore-*.txt`` entries in the old collection.
-#. Update ``meta/runtime.yml`` in the old collection.
-
-
-Removing the content from the old collection
---------------------------------------------
-
-Create a PR against the source collection repository to remove the modules, module_utils, plugins, and docs_fragments related to this migration:
-
-#. If you are removing an action plugin, remove the corresponding module that contains the documentation.
-#. If you are removing a module, remove any corresponding action plugin that should stay with it.
-#. Remove any entries about removed plugins from ``meta/runtime.yml``. Ensure they are added into the new repo.
-#. Remove sanity ignore lines from ``tests/sanity/ignore\*.txt``
-#. Remove associated integration tests from ``tests/integrations/targets/`` and unit tests from ``tests/units/plugins/``.
-#. if you are removing from content from ``community.general`` or ``community.network``, remove entries from ``.github/BOTMETA.yml``.
-#. Carefully review ``meta/runtime.yml`` for any entries you may need to remove or update, in particular deprecated entries.
-#. Update ``meta/runtime.yml`` to contain redirects for EVERY PLUGIN, pointing to the new collection name.
-
-.. warning::
-
-	Maintainers for the old collection have to make sure that the PR is merged in a way that it does not break user experience and semantic versioning:
-
-	#. A new version containing the merged PR must not be released before the collection the content has been moved to has been released again, with that content contained in it. Otherwise the redirects cannot work and users relying on that content will experience breakage.
-	#. Once 1.0.0 of the collection from which the content has been removed has been released, such PRs can only be merged for a new **major** version (in other words, 2.0.0, 3.0.0, and so on).
-
-
-BOTMETA.yml
------------
-
-The ``BOTMETA.yml``, for example in `community.general collection repository <https://github.com/ansible-collections/community.general/blob/main/.github/BOTMETA.yml>`_, is the source of truth for:
-
-* ansibullbot
-
-If the old and/or new collection has ``ansibullbot``, its ``BOTMETA.yml`` must be updated correspondingly.
-
-Ansibulbot will know how to redirect existing issues and PRs to the new repo.
-The build process for docs.ansible.com will know where to find the module docs.
-
-.. code-block:: yaml
-
-   $modules/monitoring/grafana/grafana_plugin.py:
-       migrated_to: community.grafana
-   $modules/monitoring/grafana/grafana_dashboard.py:
-       migrated_to: community.grafana
-   $modules/monitoring/grafana/grafana_datasource.py:
-       migrated_to: community.grafana
-   $plugins/callback/grafana_annotations.py:
-       maintainers: $team_grafana
-       labels: monitoring grafana
-       migrated_to: community.grafana
-   $plugins/doc_fragments/grafana.py:
-       maintainers: $team_grafana
-       labels: monitoring grafana
-       migrated_to: community.grafana
-
-`Example PR <https://github.com/ansible/ansible/pull/66981/files>`_
-
-* The ``migrated_to:`` key must be added explicitly for every *file*. You cannot add ``migrated_to`` at the directory level. This is to allow module and plugin webdocs to be redirected to the new collection docs.
-* ``migrated_to:`` MUST be added for every:
-
-  * module
-  * plugin
-  * module_utils
-  * contrib/inventory script
-
-* You do NOT need to add ``migrated_to`` for:
-
-  * Unit tests
-  * Integration tests
-  * ReStructured Text docs (anything under ``docs/docsite/rst/``)
-  * Files that never existed in ``ansible/ansible:devel``
-
-.. _testing_collections:
-
-Testing collections
-===================
-
-The main tool for testing collections is ``ansible-test``, Ansible's testing tool described in :ref:`developing_testing`. You can run several compile and sanity checks, as well as run unit and integration tests for plugins using ``ansible-test``. When you test collections, test against the ansible-core version(s) you are targeting.
-
-You must always execute ``ansible-test`` from the root directory of a collection. You can run ``ansible-test`` in Docker containers without installing any special requirements. The Ansible team uses this approach in Shippable both in the ansible/ansible GitHub repository and in the large community collections such as `community.general <https://github.com/ansible-collections/community.general/>`_ and `community.network <https://github.com/ansible-collections/community.network/>`_. The examples below demonstrate running tests in Docker containers.
-
-Compile and sanity tests
-------------------------
-
-To run all compile and sanity tests::
-
-    ansible-test sanity --docker default -v
-
-See :ref:`testing_compile` and :ref:`testing_sanity` for more information. See the :ref:`full list of sanity tests <all_sanity_tests>` for details on the sanity tests and how to fix identified issues.
-
-Unit tests
-----------
-
-You must place unit tests in the appropriate``tests/unit/plugins/`` directory. For example, you would place tests for ``plugins/module_utils/foo/bar.py`` in ``tests/unit/plugins/module_utils/foo/test_bar.py`` or ``tests/unit/plugins/module_utils/foo/bar/test_bar.py``. For examples, see the `unit tests in community.general <https://github.com/ansible-collections/community.general/tree/master/tests/unit/>`_.
-
-To run all unit tests for all supported Python versions::
-
-    ansible-test units --docker default -v
-
-To run all unit tests only for a specific Python version::
-
-    ansible-test units --docker default -v --python 3.6
-
-To run only a specific unit test::
-
-    ansible-test units --docker default -v --python 3.6 tests/unit/plugins/module_utils/foo/test_bar.py
-
-You can specify Python requirements in the ``tests/unit/requirements.txt`` file. See :ref:`testing_units` for more information, especially on fixture files.
-
-Integration tests
------------------
-
-You must place integration tests in the appropriate ``tests/integration/targets/`` directory. For module integration tests, you can use the module name alone. For example, you would place integration tests for ``plugins/modules/foo.py`` in a directory called ``tests/integration/targets/foo/``. For non-module plugin integration tests, you must add the plugin type to the directory name. For example, you would place integration tests for ``plugins/connections/bar.py`` in a directory called ``tests/integration/targets/connection_bar/``. For lookup plugins, the directory must be called ``lookup_foo``, for inventory plugins, ``inventory_foo``, and so on.
-
-You can write two different kinds of integration tests:
-
-* Ansible role tests run with ``ansible-playbook`` and validate various aspects of the module. They can depend on other integration tests (usually named ``prepare_bar`` or ``setup_bar``, which prepare a service or install a requirement named ``bar`` in order to test module ``foo``) to set-up required resources, such as installing required libraries or setting up server services.
-* ``runme.sh`` tests run directly as scripts. They can set up inventory files, and execute ``ansible-playbook`` or ``ansible-inventory`` with various settings.
-
-For examples, see the `integration tests in community.general <https://github.com/ansible-collections/community.general/tree/master/tests/integration/targets/>`_. See also :ref:`testing_integration` for more details.
-
-Since integration tests can install requirements, and set-up, start and stop services, we recommended running them in docker containers or otherwise restricted environments whenever possible. By default, ``ansible-test`` supports Docker images for several operating systems. See the `list of supported docker images <https://github.com/ansible/ansible/blob/devel/test/lib/ansible_test/_data/completion/docker.txt>`_ for all options. Use the ``default`` image mainly for platform-independent integration tests, such as those for cloud modules. The following examples use the ``centos8`` image.
-
-To execute all integration tests for a collection::
-
-    ansible-test integration --docker centos8 -v
-
-If you want more detailed output, run the command with ``-vvv`` instead of ``-v``. Alternatively, specify ``--retry-on-error`` to automatically re-run failed tests with higher verbosity levels.
-
-To execute only the integration tests in a specific directory::
-
-    ansible-test integration --docker centos8 -v connection_bar
-
-You can specify multiple target names. Each target name is the name of a directory in ``tests/integration/targets/``.
-
-.. _hacking_collections:
-
-Contributing to collections
-===========================
-
-If you want to add functionality to an existing collection, modify a collection you are using to fix a bug, or change the behavior of a module in a collection, clone the git repository for that collection and make changes on a branch. You can combine changes to a collection with a local checkout of Ansible (``source hacking/env-setup``).
-
-This section describes the process for `community.general <https://github.com/ansible-collections/community.general/>`_. To contribute to other collections, replace the folder names ``community`` and ``general`` with the namespace and collection name of a different collection.
-
-We assume that you have included ``~/dev/ansible/collections/`` in :ref:`COLLECTIONS_PATHS`, and if that path mentions multiple directories, that you made sure that no other directory earlier in the search path contains a copy of ``community.general``. Create the directory ``~/dev/ansible/collections/ansible_collections/community``, and in it clone `the community.general Git repository <https://github.com/ansible-collections/community.general/>`_ or a fork of it into the folder ``general``::
-
-    mkdir -p ~/dev/ansible/collections/ansible_collections/community
-    cd ~/dev/ansible/collections/ansible_collections/community
-    git clone git@github.com:ansible-collections/community.general.git general
-
-If you clone a fork, add the original repository as a remote ``upstream``::
-
-    cd ~/dev/ansible/collections/ansible_collections/community/general
-    git remote add upstream git@github.com:ansible-collections/community.general.git
-
-Now you can use this checkout of ``community.general`` in playbooks and roles with whichever version of Ansible you have installed locally, including a local checkout of ``ansible/ansible``'s ``devel`` branch.
-
-For collections hosted in the ``ansible_collections`` GitHub org, create a branch and commit your changes on the branch. When you are done (remember to add tests, see :ref:`testing_collections`), push your changes to your fork of the collection and create a Pull Request. For other collections, especially for collections not hosted on GitHub, check the ``README.md`` of the collection for information on contributing to it.
-
-.. _collection_changelogs:
-
-Generating changelogs for a collection
-======================================
-
-We recommend that you use the `antsibull-changelog <https://github.com/ansible-community/antsibull-changelog>`_ tool to generate Ansible-compatible changelogs for your collection. The Ansible changelog uses the output of this tool to collate all the collections included in an Ansible release into one combined changelog for the release.
-
-.. note::
-
-	Ansible here refers to the Ansible 2.10 or later release that includes a curated set of collections.
-
-Understanding antsibull-changelog
----------------------------------
-
-The ``antsibull-changelog`` tool allows you to create and update changelogs for Ansible collections that are compatible with the combined Ansible changelogs. This is an update to the changelog generator used in prior Ansible releases. The tool adds three new changelog fragment categories: ``breaking_changes``, ``security_fixes`` and ``trivial``. The tool also generates the ``changelog.yaml`` file that Ansible uses to create the combined ``CHANGELOG.rst`` file and Porting Guide for the release.
-
-See :ref:`changelogs_how_to` and the `antsibull-changelog documentation <https://github.com/ansible-community/antsibull-changelog/tree/main/docs>`_ for complete details.
-
-.. note::
-
-	The collection maintainers set the changelog policy for their collections. See the individual collection contributing guidelines for complete details.
-
-Generating changelogs
----------------------
-
-To initialize changelog generation:
-
-#. Install ``antsibull-changelog``: :code:`pip install antsibull-changelog`.
-#. Initialize changelogs for your repository: :code:`antsibull-changelog init <path/to/your/collection>`.
-#. Optionally, edit the ``changelogs/config.yaml`` file to customize the location of the generated changelog ``.rst`` file or other options. See `Bootstrapping changelogs for collections <https://github.com/ansible-community/antsibull-changelog/blob/main/docs/changelogs.rst#bootstrapping-changelogs-for-collections>`_ for details.
-
-To generate changelogs from the changelog fragments you created:
-
-#. Optionally, validate your changelog fragments: :code:`antsibull-changelog lint`.
-#. Generate the changelog for your release: :code:`antsibull-changelog release [--version version_number]`.
-
-.. note::
-
-  Add the  ``--reload-plugins`` option if you ran the ``antsibull-changelog release`` command previously and the version of the collection has not changed. ``antsibull-changelog`` caches the information on all plugins and does not update its cache until the collection version changes.
-
-
-Porting Guide entries
-----------------------
-
-The following changelog fragment categories are consumed by the Ansible changelog generator into the Ansible Porting Guide:
-
-* ``major_changes``
-* ``breaking_changes``
-* ``deprecated_features``
-* ``removed_features``
-
-Including collection changelogs into Ansible
-=============================================
-
-
-If your collection is part of Ansible, use one of the following three options  to include your changelog into the Ansible release changelog:
-
-* Use the ``antsibull-changelog`` tool.
-
-* If are not using this tool, include the properly formatted ``changelog.yaml`` file  into your collection. See the `changelog.yaml format <https://github.com/ansible-community/antsibull-changelog/blob/main/docs/changelog.yaml-format.md>`_ for details.
-
-* Add a link to own changelogs or release notes in any format by opening an issue at https://github.com/ansible-community/ansible-build-data/ with the HTML link to that information.
-
-.. note::
-
-  For the first two options, Ansible pulls the changelog details from Galaxy so your changelogs must be included in the collection version on Galaxy that is included in the upcoming Ansible release.
+For instructions on developing modules, see :ref:`developing_modules_general`.
 
 .. seealso::
 
    :ref:`collections`
-       Learn how to install and use collections.
-   :ref:`collections_galaxy_meta`
-       Understand the collections metadata structure.
-   :ref:`developing_modules_general`
-       Learn about how to write Ansible modules
+       Learn how to install and use collections in playbooks and roles
+   :ref:`contributing_maintained_collections`
+       Guidelines for contributing to selected collections
+   `Ansible Collections Overview and FAQ <https://github.com/ansible-collections/overview/blob/main/README.rst>`_
+       Current development status of community collections and FAQ
    `Mailing List <https://groups.google.com/group/ansible-devel>`_
        The development mailing list
-   `irc.freenode.net <http://irc.freenode.net>`_
+   `irc.libera.chat <https://libera.chat>`_
        #ansible IRC chat channel

docs/docsite/rst/dev_guide/developing_collections_changelogs.rst

@@ -0,0 +1,80 @@
+.. _collection_changelogs:
+
+***************************************************************
+Generating changelogs and porting guide entries in a collection
+***************************************************************
+
+You can create and share changelog and porting guide entries for your collection. If your collection is part of the Ansible Community package, we recommend that you use the `antsibull-changelog <https://github.com/ansible-community/antsibull-changelog>`_ tool to generate Ansible-compatible changelogs. The Ansible changelog uses the output of this tool to collate all the collections included in an Ansible release into one combined changelog for the release.
+
+.. note::
+
+	Ansible here refers to the Ansible 2.10 or later release that includes a curated set of collections.
+
+.. contents::
+   :local:
+   :depth: 2
+
+Understanding antsibull-changelog
+=================================
+
+The ``antsibull-changelog`` tool allows you to create and update changelogs for Ansible collections that are compatible with the combined Ansible changelogs. This is an update to the changelog generator used in prior Ansible releases. The tool adds three new changelog fragment categories: ``breaking_changes``, ``security_fixes`` and ``trivial``. The tool also generates the ``changelog.yaml`` file that Ansible uses to create the combined ``CHANGELOG.rst`` file and Porting Guide for the release.
+
+See :ref:`changelogs_how_to` and the `antsibull-changelog documentation <https://github.com/ansible-community/antsibull-changelog/tree/main/docs>`_ for complete details.
+
+.. note::
+
+	The collection maintainers set the changelog policy for their collections. See the individual collection contributing guidelines for complete details.
+
+Generating changelogs
+---------------------
+
+To initialize changelog generation:
+
+#. Install ``antsibull-changelog``: :code:`pip install antsibull-changelog`.
+#. Initialize changelogs for your repository: :code:`antsibull-changelog init <path/to/your/collection>`.
+#. Optionally, edit the ``changelogs/config.yaml`` file to customize the location of the generated changelog ``.rst`` file or other options. See `Bootstrapping changelogs for collections <https://github.com/ansible-community/antsibull-changelog/blob/main/docs/changelogs.rst#bootstrapping-changelogs-for-collections>`_ for details.
+
+To generate changelogs from the changelog fragments you created:
+
+#. Optionally, validate your changelog fragments: :code:`antsibull-changelog lint`.
+#. Generate the changelog for your release: :code:`antsibull-changelog release [--version version_number]`.
+
+.. note::
+
+  Add the  ``--reload-plugins`` option if you ran the ``antsibull-changelog release`` command previously and the version of the collection has not changed. ``antsibull-changelog`` caches the information on all plugins and does not update its cache until the collection version changes.
+
+Porting Guide entries from changelog fragments
+----------------------------------------------
+
+The Ansible changelog generator automatically adds several changelog fragment categories to the Ansible Porting Guide:
+
+* ``major_changes``
+* ``breaking_changes``
+* ``deprecated_features``
+* ``removed_features``
+
+Including collection changelogs into Ansible
+=============================================
+
+If your collection is part of Ansible, use one of the following three options  to include your changelog into the Ansible release changelog:
+
+* Use the ``antsibull-changelog`` tool.
+
+* If are not using this tool, include the properly formatted ``changelog.yaml`` file  into your collection. See the `changelog.yaml format <https://github.com/ansible-community/antsibull-changelog/blob/main/docs/changelog.yaml-format.md>`_ for details.
+
+* Add a link to own changelogs or release notes in any format by opening an issue at https://github.com/ansible-community/ansible-build-data/ with the HTML link to that information.
+
+.. note::
+
+   For the first two options, Ansible pulls the changelog details from Galaxy so your changelogs must be included in the collection version on Galaxy that is included in the upcoming Ansible release.
+
+.. seealso::
+
+   :ref:`collections`
+       Learn how to install and use collections.
+   :ref:`contributing_maintained_collections`
+       Guidelines for contributing to selected collections
+   `Mailing List <https://groups.google.com/group/ansible-devel>`_
+       The development mailing list
+   `irc.libera.chat <https://libera.chat/>`_
+       #ansible IRC chat channel

docs/docsite/rst/dev_guide/developing_collections_contributing.rst

@@ -0,0 +1,59 @@
+.. _hacking_collections:
+
+***************************
+Contributing to collections
+***************************
+
+If you want to add functionality to an existing collection, modify a collection you are using to fix a bug, or change the behavior of a module in a collection, clone the git repository for that collection and make changes on a branch. You can combine changes to a collection with a local checkout of Ansible (``source hacking/env-setup``).
+You should first check the collection repository to see if it has specific contribution guidelines. These are typically listed in the README.md or CONTRIBUTING.md files within the repository.
+
+Contributing to a collection: community.general
+===============================================
+
+These instructions apply to collections hosted in the `ansible_collections GitHub org <https://github.com/ansible-collections>`_. For other collections, especially for collections not hosted on GitHub, check the ``README.md`` of the collection for information on contributing to it.
+
+This example uses the `community.general collection <https://github.com/ansible-collections/community.general/>`_. To contribute to other collections in the same GitHub org, replace the folder names ``community`` and ``general`` with the namespace and collection name of a different collection.
+
+Prerequisites
+-------------
+
+* Include ``~/dev/ansible/collections/`` in :ref:`COLLECTIONS_PATHS`
+* If that path mentions multiple directories, make sure that no other directory earlier in the search path contains a copy of ``community.general``.
+
+Creating a PR
+-------------
+
+
+
+* Create the directory ``~/dev/ansible/collections/ansible_collections/community``::
+
+    mkdir -p ~/dev/ansible/collections/ansible_collections/community
+
+* Clone `the community.general Git repository <https://github.com/ansible-collections/community.general/>`_ or a fork of it into the directory ``general``::
+
+    cd ~/dev/ansible/collections/ansible_collections/community
+    git clone git@github.com:ansible-collections/community.general.git general
+
+* If you clone from a fork, add the original repository as a remote ``upstream``::
+
+    cd ~/dev/ansible/collections/ansible_collections/community/general
+    git remote add upstream git@github.com:ansible-collections/community.general.git
+
+* Create a branch and commit your changes on the branch.
+
+* Remember to add tests for your changes, see :ref:`testing_collections`.
+
+* Push your changes to your fork of the collection and create a Pull Request.
+
+You can test your changes by using this checkout of ``community.general`` in playbooks and roles with whichever version of Ansible you have installed locally, including a local checkout of ``ansible/ansible``'s ``devel`` branch.
+
+.. seealso::
+
+   :ref:`collections`
+       Learn how to install and use collections.
+   :ref:`contributing_maintained_collections`
+       Guidelines for contributing to selected collections
+   `Mailing List <https://groups.google.com/group/ansible-devel>`_
+       The development mailing list
+   `irc.libera.chat <https://libera.chat/>`_
+       #ansible IRC chat channel

docs/docsite/rst/dev_guide/developing_collections_creating.rst

@@ -0,0 +1,57 @@
+.. _creating_collections:
+
+********************
+Creating collections
+********************
+
+To create a collection:
+
+#. Create a :ref:`collection skeleton<creating_collections_skeleton>` with the ``collection init`` command.
+#. Add modules and other content to the collection.
+#. Build the collection into a collection artifact with :ref:`ansible-galaxy collection build<building_collections>`.
+#. Publish the collection artifact to Galaxy with :ref:`ansible-galaxy collection publish<publishing_collections>`.
+
+A user can then install your collection on their systems.
+
+.. contents::
+   :local:
+   :depth: 2
+
+.. _creating_collections_skeleton:
+
+Creating a collection skeleton
+==============================
+
+To start a new collection:
+
+.. code-block:: bash
+
+    collection_dir#> ansible-galaxy collection init my_namespace.my_collection
+
+.. note::
+
+	Both the namespace and collection names use the same strict set of requirements. See `Galaxy namespaces <https://galaxy.ansible.com/docs/contributing/namespaces.html#galaxy-namespaces>`_ on the Galaxy docsite for those requirements.
+
+Once the skeleton exists, you can populate the directories with the content you want inside the collection. See `ansible-collections <https://github.com/ansible-collections/>`_ GitHub Org to get a better idea of what you can place inside a collection.
+
+Reference: the ``ansible-galaxy collection`` command
+
+Currently the ``ansible-galaxy collection`` command implements the following sub commands:
+
+* ``init``: Create a basic collection skeleton based on the default template included with Ansible or your own template.
+* ``build``: Create a collection artifact that can be uploaded to Galaxy or your own repository.
+* ``publish``: Publish a built collection artifact to Galaxy.
+* ``install``: Install one or more collections.
+
+To learn more about the ``ansible-galaxy`` command-line tool, see the :ref:`ansible-galaxy` man page.
+
+.. seealso::
+
+   :ref:`collections`
+       Learn how to install and use collections.
+   :ref:`collection_structure`
+       Directories and files included in the collection skeleton
+   `Mailing List <https://groups.google.com/group/ansible-devel>`_
+       The development mailing list
+   `irc.libera.chat <https://libera.chat/>`_
+       #ansible IRC chat channel

docs/docsite/rst/dev_guide/developing_collections_distributing.rst

@@ -0,0 +1,241 @@
+.. _distributing_collections:
+
+************************
+Distributing collections
+************************
+
+You can distribute your collections by publishing them on a distribution server. Distribution servers include Ansible Galaxy, Red Hat Automation Hub, and privately hosted Automation Hub instances. You can publish any collection to Ansible Galaxy and/or to a privately hosted Automation Hub instance. If your collection is certified by Red Hat, you can publish it to the Red Hat Automation Hub.
+
+Distributing collections involves three major steps:
+#. Configuring your distribution server(s)
+#. Building your collection artifact
+#. Publishing your collection
+
+.. contents::
+   :local:
+   :depth: 2
+
+Configuring your distribution server or servers
+================================================
+
+1. Get a namespace on each distribution server you want to use (Galaxy, private Automation Hub, Red Hat Automation Hub).
+2. Get an API token for each distribution server you want to use.
+3. Specify the API token for each distribution server you want to use.
+
+Getting a namespace
+-------------------
+
+You need a namespace on Galaxy and/or Automation Hub to upload your collection. To get a namespace:
+
+* For Galaxy, see `Galaxy namespaces <https://galaxy.ansible.com/docs/contributing/namespaces.html#galaxy-namespaces>`_ on the Galaxy docsite for details.
+* For Automation Hub, see the `Ansible Certified Content FAQ <https://access.redhat.com/articles/4916901>`_.
+
+.. _galaxy_get_token:
+
+Getting your API token
+----------------------
+
+You need an API token for Galaxy and/or Automation Hub to upload your collection. Use the API token(s) to authenticate your connection to the distribution server(s) and protect your content.
+
+To get your API token:
+
+* For Galaxy, go to the `Galaxy profile preferences <https://galaxy.ansible.com/me/preferences>`_ page and click :guilabel:`API Key`.
+* For Automation Hub, go to `the token page <https://cloud.redhat.com/ansible/automation-hub/token/>`_ and click :guilabel:`Load token`.
+
+Specifying your API token
+-------------------------
+
+Once you have retrieved your API token, you can specify the correct token for each distribution server in two ways:
+
+* Pass the token to  the ``ansible-galaxy`` command using the ``--token``.
+* Configure the token within a Galaxy server list in your :file:`ansible.cfg` file.
+
+Specifying your API token with the ``--token`` argument
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can use the ``--token`` argument with the ``ansible-galaxy`` command (in conjunction with the ``--server`` argument or :ref:`GALAXY_SERVER` setting in your :file:`ansible.cfg` file). You cannot use ``apt-key`` with any servers defined in your :ref:`Galaxy server list <galaxy_server_config>`.
+
+.. code-block:: text
+
+    ansible-galaxy collection publish ./geerlingguy-collection-1.2.3.tar.gz --token=<key goes here>
+
+Specifying your API token with a Galaxy server list
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can configure one or more distribution servers for Galaxy in your :file:`ansible.cfg` file under the ``galaxy_server_list`` section. For each server, you also configure the token.
+
+
+.. code-block:: ini
+
+   [galaxy]
+   server_list = release_galaxy
+
+   [galaxy_server.release_galaxy]
+   url=https://galaxy.ansible.com/
+   token=my_token
+
+See :ref:`galaxy_server_config` for complete details.
+
+.. _building_collections:
+
+Building a collection tarball
+=============================
+
+Once you have configured one or more distribution servers, you must build a collection tarball. To build a collection, run ``ansible-galaxy collection build`` from inside the root directory of the collection:
+
+.. code-block:: bash
+
+    collection_dir#> ansible-galaxy collection build
+
+This creates a tarball of the built collection in the current directory which can be uploaded to your distribution server::
+
+    my_collection/
+    ├── galaxy.yml
+    ├── ...
+    ├── my_namespace-my_collection-1.0.0.tar.gz
+    └── ...
+
+.. note::
+   * Certain files and folders are excluded when building the collection artifact. See :ref:`ignoring_files_and_folders_collections`  to exclude other files you would not want to distribute.
+   * If you used the now-deprecated ``Mazer`` tool for any of your collections, delete any and all files it added to your :file:`releases/` directory before you build your collection with ``ansible-galaxy``.
+   * The current Galaxy maximum tarball size is 2 MB.
+
+This tarball is mainly intended to upload to Galaxy as a distribution method, but you can use it directly to install the collection on target systems.
+
+.. _ignoring_files_and_folders_collections:
+
+Ignoring files and folders
+--------------------------
+
+By default the build step will include all the files in the collection directory in the final build artifact except for the following:
+
+* ``galaxy.yml``
+* ``*.pyc``
+* ``*.retry``
+* ``tests/output``
+* previously built artifacts in the root directory
+* various version control directories like ``.git/``
+
+To exclude other files and folders when building the collection, you can set a list of file glob-like patterns in the
+``build_ignore`` key in the collection's ``galaxy.yml`` file. These patterns use the following special characters for
+wildcard matching:
+
+* ``*``: Matches everything
+* ``?``: Matches any single character
+* ``[seq]``: Matches and character in seq
+* ``[!seq]``:Matches any character not in seq
+
+For example, if you wanted to exclude the :file:`sensitive` folder within the ``playbooks`` folder as well any ``.tar.gz`` archives you
+can set the following in your ``galaxy.yml`` file:
+
+.. code-block:: yaml
+
+     build_ignore:
+     - playbooks/sensitive
+     - '*.tar.gz'
+
+.. note::
+     This feature is only supported when running ``ansible-galaxy collection build`` with Ansible 2.10 or newer.
+
+.. _collection_versions:
+
+Collection versions
+===================
+
+Each time you publish your collection, you create a new version. Once you publish a version of a collection, you cannot delete or modify that version. Ensure that everything looks okay before publishing. The only way to change a collection is to release a new version. The latest version of a collection (by highest version number) will be the version displayed everywhere in Galaxy or Automation Hub; however, users will still be able to download older versions.
+
+Collection versions use `Semantic Versioning <https://semver.org/>`_ for version numbers. Please read the official documentation for details and examples. In summary:
+
+* Increment major (for example: x in `x.y.z`) version number for an incompatible API change.
+* Increment minor (for example: y in `x.y.z`) version number for new functionality in a backwards compatible manner (for example new modules/plugins, parameters, return values).
+* Increment patch (for example: z in `x.y.z`) version number for backwards compatible bug fixes.
+
+
+.. _trying_collection_locally:
+
+Trying collections locally
+==========================
+
+Before you publish your collection, test it out locally. Every time you publish a tarball, you create a :ref:`new version <collection_versions>` of your collection. Testing the collection locally gives you confidence that the new version will contain the functionality you want without unexpected behavior.
+
+Trying your collection from the tarball
+---------------------------------------
+
+You can try your collection locally by installing it from the tarball. The following will enable an adjacent playbook to access the collection:
+
+.. code-block:: bash
+
+   ansible-galaxy collection install my_namespace-my_collection-1.0.0.tar.gz -p ./collections
+
+
+You should use one of the values configured in :ref:`COLLECTIONS_PATHS` for your path. This is also where Ansible itself will
+expect to find collections when attempting to use them. If you don't specify a path value, ``ansible-galaxy collection install``
+installs the collection in the first path defined in :ref:`COLLECTIONS_PATHS`, which by default is ``~/.ansible/collections``.
+
+If you want to use a collection directly out of a checked out git repository, see :ref:`hacking_collections`.
+
+Next, try using the local collection inside a playbook. For examples and more details see :ref:`Using collections <using_collections>`
+
+.. _collections_scm_install:
+
+Trying your collection from a git repository
+--------------------------------------------
+
+You can also test a version of your collection in development by installing it from a git repository.
+
+.. code-block:: bash
+
+   ansible-galaxy collection install git+https://github.com/org/repo.git,devel
+
+.. include:: ../shared_snippets/installing_collections_git_repo.txt
+
+Publishing a collection
+=======================
+
+Once you have a namespace and an API token for each distribution server you want to use, and you have created and tested a collection tarball, you can distribute your collection by publishing the tarball to Ansible Galaxy, Red Hat Automation Hub, or a privately hosted Automation Hub instance. You can use either the ``ansible-galaxy collection publish`` command or the distribution server (Galaxy, Automation Hub) itself.
+
+Each time you add features or make changes to your collection, you must create a new collection artifact and publish a new version of the collection. For details on versioning, see :ref:`collection_versions`.
+
+.. _upload_collection_ansible_galaxy:
+
+Publish a collection using ``ansible-galaxy``
+---------------------------------------------
+
+.. note::
+  By default, ``ansible-galaxy`` uses https://galaxy.ansible.com as the Galaxy server (as listed in the :file:`ansible.cfg` file under :ref:`galaxy_server`). If you are only publishing your collection to Ansible Galaxy, you do not need any further configuration. If you are using Red Hat Automation Hub or any other Galaxy server, see :ref:`Configuring the ansible-galaxy client <galaxy_server_config>`.
+
+To upload the collection artifact with the ``ansible-galaxy`` command:
+
+.. code-block:: bash
+
+     ansible-galaxy collection publish path/to/my_namespace-my_collection-1.0.0.tar.gz
+
+.. note::
+
+	The above command assumes you have retrieved and stored your API token as part of a Galaxy server list. See :ref:`galaxy_get_token` for details.
+
+The ``ansible-galaxy collection publish`` command triggers an import process, just as if you uploaded the collection through the Galaxy website. The command waits until the import process completes before reporting the status back. If you want to continue without waiting for the import result, use the ``--no-wait`` argument and manually look at the import progress in your `My Imports <https://galaxy.ansible.com/my-imports/>`_ page.
+
+
+.. _upload_collection_galaxy:
+
+Publishing a collection using the Galaxy website
+------------------------------------------------
+
+To publish your collection directly on the Galaxy website:
+
+#. Go to the `My Content <https://galaxy.ansible.com/my-content/namespaces>`_ page, and click the **Add Content** button on one of your namespaces.
+#. From the **Add Content** dialogue, click **Upload New Collection**, and select the collection archive file from your local filesystem.
+
+When you upload a collection, it always uploads to the namespace specified in the collection metadata in the ``galaxy.yml`` file, no matter which namespace you select on the website. If you are not an owner of the namespace specified in your collection metadata, the upload request will fail.
+
+Once Galaxy uploads and accepts a collection, you will be redirected to the **My Imports** page, which displays output from the import process, including any errors or warnings about the metadata and content contained in the collection.
+
+.. seealso::
+
+   :ref:`collections`
+       Learn how to install and use collections.
+   `Mailing List <https://groups.google.com/group/ansible-devel>`_
+       The development mailing list
+   `irc.libera.chat <https://libera.chat/>`_
+       #ansible IRC chat channel

docs/docsite/rst/dev_guide/developing_collections_migrating.rst

@@ -0,0 +1,136 @@
+.. _migrate_to_collection:
+
+***************************************************
+Migrating Ansible content to a different collection
+***************************************************
+
+When you move content from one collection to another, for example to extract a set of related modules out of ``community.general`` to create a more focused collection, you must make sure the transition is easy for users to follow. 
+ 
+.. contents::
+   :local:
+   :depth: 2
+
+Migrating content
+=================
+
+Before you start migrating content from one collection to another, look at `Ansible Collection Checklist <https://github.com/ansible-collections/overview/blob/main/collection_requirements.rst>`_.
+
+To migrate content from one collection to another, if the collections are parts of `Ansible distribution <https://github.com/ansible-community/ansible-build-data/blob/main/2.10/ansible.in>`_:
+
+#. Copy content from the source (old) collection to the target (new) collection.
+#. Deprecate the module/plugin with ``removal_version`` scheduled for the next major version in ``meta/runtime.yml`` of the old collection. The deprecation must be released after the copied content has been included in a release of the new collection.
+#. When the next major release of the old collection is prepared:
+
+  * remove the module/plugin from the old collection
+  * remove the symlink stored in ``plugin/modules`` directory if appropriate (mainly when removing from ``community.general`` and ``community.network``)
+  * remove related unit and integration tests
+  * remove specific module utils
+  * remove specific documentation fragments if there are any in the old collection
+  * add a changelog fragment containing entries for ``removed_features`` and ``breaking_changes``; you can see an example of a changelog fragment in this `pull request <https://github.com/ansible-collections/community.general/pull/1304>`_ 
+  * change ``meta/runtime.yml`` in the old collection:
+
+    * add ``redirect`` to the corresponding module/plugin's entry
+    * in particular, add ``redirect`` for the removed module utils and documentation fragments if applicable
+    * remove ``removal_version`` from there
+  * remove related entries from ``tests/sanity/ignore.txt`` files if exist
+  * remove changelog fragments for removed content that are not yet part of the changelog (in other words, do not modify `changelogs/changelog.yaml` and do not delete files mentioned in it)
+  * remove requirements that are no longer required in ``tests/unit/requirements.txt``, ``tests/requirements.yml`` and ``galaxy.yml``
+
+To implement these changes, you need to create at least three PRs:
+
+#. Create a PR against the new collection to copy the content.
+#. Deprecate the module/plugin in the old collection.
+#. Later create a PR against the old collection to remove the content according to the schedule.
+
+
+Adding the content to the new collection
+----------------------------------------
+
+Create a PR in the new collection to:
+
+#. Copy ALL the related files from the old collection.
+#. If it is an action plugin, include the corresponding module with documentation.
+#. If it is a module, check if it has a corresponding action plugin that should move with it.
+#. Check ``meta/`` for relevant updates to ``runtime.yml`` if it exists.
+#. Carefully check the moved ``tests/integration`` and ``tests/units`` and update for FQCN.
+#. Review ``tests/sanity/ignore-*.txt`` entries in the old collection.
+#. Update ``meta/runtime.yml`` in the old collection.
+
+
+Removing the content from the old collection
+--------------------------------------------
+
+Create a PR against the source collection repository to remove the modules, module_utils, plugins, and docs_fragments related to this migration:
+
+#. If you are removing an action plugin, remove the corresponding module that contains the documentation.
+#. If you are removing a module, remove any corresponding action plugin that should stay with it.
+#. Remove any entries about removed plugins from ``meta/runtime.yml``. Ensure they are added into the new repo.
+#. Remove sanity ignore lines from ``tests/sanity/ignore\*.txt``
+#. Remove associated integration tests from ``tests/integrations/targets/`` and unit tests from ``tests/units/plugins/``.
+#. if you are removing from content from ``community.general`` or ``community.network``, remove entries from ``.github/BOTMETA.yml``.
+#. Carefully review ``meta/runtime.yml`` for any entries you may need to remove or update, in particular deprecated entries.
+#. Update ``meta/runtime.yml`` to contain redirects for EVERY PLUGIN, pointing to the new collection name.
+
+.. warning::
+
+	Maintainers for the old collection have to make sure that the PR is merged in a way that it does not break user experience and semantic versioning:
+
+	#. A new version containing the merged PR must not be released before the collection the content has been moved to has been released again, with that content contained in it. Otherwise the redirects cannot work and users relying on that content will experience breakage.
+	#. Once 1.0.0 of the collection from which the content has been removed has been released, such PRs can only be merged for a new **major** version (in other words, 2.0.0, 3.0.0, and so on).
+
+
+Updating BOTMETA.yml
+--------------------
+
+The ``BOTMETA.yml``, for example in `community.general collection repository <https://github.com/ansible-collections/community.general/blob/main/.github/BOTMETA.yml>`_, is the source of truth for:
+
+* ansibullbot
+
+If the old and/or new collection has ``ansibullbot``, its ``BOTMETA.yml`` must be updated correspondingly.
+
+Ansibulbot will know how to redirect existing issues and PRs to the new repo. The build process for docs.ansible.com will know where to find the module docs.
+
+.. code-block:: yaml
+
+   $modules/monitoring/grafana/grafana_plugin.py:
+       migrated_to: community.grafana
+   $modules/monitoring/grafana/grafana_dashboard.py:
+       migrated_to: community.grafana
+   $modules/monitoring/grafana/grafana_datasource.py:
+       migrated_to: community.grafana
+   $plugins/callback/grafana_annotations.py:
+       maintainers: $team_grafana
+       labels: monitoring grafana
+       migrated_to: community.grafana
+   $plugins/doc_fragments/grafana.py:
+       maintainers: $team_grafana
+       labels: monitoring grafana
+       migrated_to: community.grafana
+
+`Example PR <https://github.com/ansible/ansible/pull/66981/files>`_
+
+* The ``migrated_to:`` key must be added explicitly for every *file*. You cannot add ``migrated_to`` at the directory level. This is to allow module and plugin webdocs to be redirected to the new collection docs.
+* ``migrated_to:`` MUST be added for every:
+
+  * module
+  * plugin
+  * module_utils
+  * contrib/inventory script
+
+* You do NOT need to add ``migrated_to`` for:
+
+  * Unit tests
+  * Integration tests
+  * ReStructured Text docs (anything under ``docs/docsite/rst/``)
+  * Files that never existed in ``ansible/ansible:devel``
+
+.. seealso::
+
+   :ref:`collections`
+       Learn how to install and use collections.
+   :ref:`contributing_maintained_collections`
+       Guidelines for contributing to selected collections
+   `Mailing List <https://groups.google.com/group/ansible-devel>`_
+       The development mailing list
+   `irc.libera.chat <https://libera.chat/>`_
+       #ansible IRC chat channel

docs/docsite/rst/dev_guide/developing_collections_shared.rst

@@ -0,0 +1,77 @@
+.. _collections_shared_resources:
+
+*************************************
+Using shared resources in collections
+*************************************
+
+Although developing Ansible modules contained in collections is similar to developing standalone Ansible modules, you use shared resources like documentation fragments and module utilities differently in collections. You can use documentation fragments within and across collections. You can use optional module utilities to support multiple versions of ansible-core in your collection.
+
+.. contents::
+   :local:
+   :depth: 2
+
+.. _docfragments_collections:
+
+Using documentation fragments in collections
+============================================
+
+To include documentation fragments in your collection:
+
+#. Create the documentation fragment: ``plugins/doc_fragments/fragment_name``.
+
+#. Refer to the documentation fragment with its FQCN.
+
+.. code-block:: yaml
+
+   extends_documentation_fragment:
+     - kubernetes.core.k8s_name_options
+     - kubernetes.core.k8s_auth_options
+     - kubernetes.core.k8s_resource_options
+     - kubernetes.core.k8s_scale_options
+
+:ref:`module_docs_fragments` covers the basics for documentation fragments. The `kubernetes.core <https://github.com/ansible-collections/kubernetes.core>`_ collection includes a complete example.
+
+If you use FQCN, you can use documentation fragments from one collection in another collection.
+
+.. _optional_module_utils:
+
+Leveraging optional module utilities in collections
+===================================================
+
+Optional module utilities let you adopt the latest features from the most recent ansible-core release in your collection-based modules without breaking your collection on older Ansible versions. With optional module utilities, you can leverage the latest features when running against the latest versions, while still providing fallback behaviors when running against older versions.
+
+This implementation, widely used in Python programming, wraps optional imports in conditionals or defensive `try/except` blocks, and implements fallback behaviors for missing imports. Ansible's module payload builder supports these patterns by treating any module_utils import nested in a block (e.g., `if`, `try`) as optional. If the requested import cannot be found during the payload build, it is simply omitted from the target payload and assumed that the importing code will handle its absence at runtime. Missing top-level imports of module_utils packages (imports that are not wrapped in a block statement of any kind) will fail the module payload build, and will not execute on the target.
+
+For example, the `ansible.module_utils.common.respawn` package is only available in Ansible 2.11 and higher. The following module code would fail during the payload build on Ansible 2.10 or earlier (as the requested Python module does not exist, and is not wrapped in a block to signal to the payload builder that it can be omitted from the module payload):
+
+.. code-block:: python
+
+   from ansible.module_utils.common.respawn import respawn_module
+
+By wrapping the import statement in a ``try`` block, the payload builder will omit the Python module if it cannot be located, and assume that the Ansible module will handle it at runtime:
+
+.. code-block:: python
+
+   try:
+       from ansible.module_utils.common.respawn import respawn_module
+   except ImportError:
+       respawn_module = None
+   ...
+   if needs_respawn:
+       if respawn_module:
+           respawn_module(target)
+       else:
+           module.fail_json('respawn is not available in Ansible < 2.11, ensure that foopkg is installed')
+
+The optional import behavior also applies to module_utils imported from collections.
+
+.. seealso::
+
+   :ref:`collections`
+       Learn how to install and use collections.
+   :ref:`contributing_maintained_collections`
+       Guidelines for contributing to selected collections
+   `Mailing List <https://groups.google.com/group/ansible-devel>`_
+       The development mailing list
+   `irc.libera.chat <https://libera.chat/>`_
+       #ansible IRC chat channel

docs/docsite/rst/dev_guide/developing_collections_structure.rst

@@ -0,0 +1,241 @@
+.. _collection_structure:
+
+********************
+Collection structure
+********************
+
+A collection is a simple data structure. None of the directories are required unless you have specific content that belongs in one of them. A collection does require a ``galaxy.yml`` file at the root level of the collection. This file contains all of the metadata that Galaxy and other tools need in order to package, build and publish the collection.
+
+.. contents::
+   :local:
+   :depth: 2
+
+Collection directories and files
+================================
+
+A collection can contain these directories and files::
+
+    collection/
+    ├── docs/
+    ├── galaxy.yml
+    ├── meta/
+    │   └── runtime.yml
+    ├── plugins/
+    │   ├── modules/
+    │   │   └── module1.py
+    │   ├── inventory/
+    │   └── .../
+    ├── README.md
+    ├── roles/
+    │   ├── role1/
+    │   ├── role2/
+    │   └── .../
+    ├── playbooks/
+    │   ├── files/
+    │   ├── vars/
+    │   ├── templates/
+    │   └── tasks/
+    └── tests/
+
+.. note::
+    * Ansible only accepts ``.md`` extensions for the :file:`README` file and any files in the :file:`/docs` folder.
+    * See the `ansible-collections <https://github.com/ansible-collections/>`_ GitHub Org for examples of collection structure.
+    * Not all directories are currently in use. Those are placeholders for future features.
+
+.. _galaxy_yml:
+
+galaxy.yml
+----------
+
+A collection must have a ``galaxy.yml`` file that contains the necessary information to build a collection artifact. See :ref:`collections_galaxy_meta` for details.
+
+.. _collections_doc_dir:
+
+docs directory
+---------------
+
+Put general documentation for the collection here. Keep the specific documentation for plugins and modules embedded as Python docstrings. Use the ``docs`` folder to describe how to use the roles and plugins the collection provides, role requirements, and so on. Use markdown and do not add subfolders.
+
+Use ``ansible-doc`` to view documentation for plugins inside a collection:
+
+.. code-block:: bash
+
+    ansible-doc -t lookup my_namespace.my_collection.lookup1
+
+The ``ansible-doc`` command requires the fully qualified collection name (FQCN) to display specific plugin documentation. In this example, ``my_namespace`` is the Galaxy namespace and ``my_collection`` is the collection name within that namespace.
+
+.. note:: The Galaxy namespace of an Ansible collection is defined in the ``galaxy.yml`` file. It can be different from the GitHub organization or repository name.
+
+.. _collections_plugin_dir:
+
+plugins directory
+-----------------
+
+Add a 'per plugin type' specific subdirectory here, including ``module_utils`` which is usable not only by modules, but by most plugins by using their FQCN. This is a way to distribute modules, lookups, filters, and so on without having to import a role in every play.
+
+Vars plugins are unsupported in collections. Cache plugins may be used in collections for fact caching, but are not supported for inventory plugins.
+
+.. _collection_module_utils:
+
+module_utils
+^^^^^^^^^^^^
+
+When coding with ``module_utils`` in a collection, the Python ``import`` statement needs to take into account the FQCN along with the ``ansible_collections`` convention. The resulting Python import will look like ``from ansible_collections.{namespace}.{collection}.plugins.module_utils.{util} import {something}``
+
+The following example snippets show a Python and PowerShell module using both default Ansible ``module_utils`` and
+those provided by a collection. In this example the namespace is ``community``, the collection is ``test_collection``.
+In the Python example the ``module_util`` in question is called ``qradar`` such that the FQCN is
+``community.test_collection.plugins.module_utils.qradar``:
+
+.. code-block:: python
+
+    from ansible.module_utils.basic import AnsibleModule
+    from ansible.module_utils.common.text.converters import to_text
+
+    from ansible.module_utils.six.moves.urllib.parse import urlencode, quote_plus
+    from ansible.module_utils.six.moves.urllib.error import HTTPError
+    from ansible_collections.community.test_collection.plugins.module_utils.qradar import QRadarRequest
+
+    argspec = dict(
+        name=dict(required=True, type='str'),
+        state=dict(choices=['present', 'absent'], required=True),
+    )
+
+    module = AnsibleModule(
+        argument_spec=argspec,
+        supports_check_mode=True
+    )
+
+    qradar_request = QRadarRequest(
+        module,
+        headers={"Content-Type": "application/json"},
+        not_rest_data_keys=['state']
+    )
+
+Note that importing something from an ``__init__.py`` file requires using the file name:
+
+.. code-block:: python
+
+    from ansible_collections.namespace.collection_name.plugins.callback.__init__ import CustomBaseClass
+
+In the PowerShell example the ``module_util`` in question is called ``hyperv`` such that the FQCN is
+``community.test_collection.plugins.module_utils.hyperv``:
+
+.. code-block:: powershell
+
+    #!powershell
+    #AnsibleRequires -CSharpUtil Ansible.Basic
+    #AnsibleRequires -PowerShell ansible_collections.community.test_collection.plugins.module_utils.hyperv
+
+    $spec = @{
+        name = @{ required = $true; type = "str" }
+        state = @{ required = $true; choices = @("present", "absent") }
+    }
+    $module = [Ansible.Basic.AnsibleModule]::Create($args, $spec)
+
+    Invoke-HyperVFunction -Name $module.Params.name
+
+    $module.ExitJson()
+
+.. _collections_roles_dir:
+
+roles directory
+----------------
+
+Collection roles are mostly the same as existing roles, but with a couple of limitations:
+
+ - Role names are now limited to contain only lowercase alphanumeric characters, plus ``_`` and start with an alpha character.
+ - Roles in a collection cannot contain plugins any more. Plugins must live in the collection ``plugins`` directory tree. Each plugin is accessible to all roles in the collection.
+
+The directory name of the role is used as the role name. Therefore, the directory name must comply with the above role name rules. The collection import into Galaxy will fail if a role name does not comply with these rules.
+
+You can migrate 'traditional roles' into a collection but they must follow the rules above. You may need to rename roles if they don't conform. You will have to move or link any role-based plugins to the collection specific directories.
+
+.. note::
+
+    For roles imported into Galaxy directly from a GitHub repository, setting the ``role_name`` value in the role's metadata overrides the role name used by Galaxy. For collections, that value is ignored. When importing a collection, Galaxy uses the role directory as the name of the role and ignores the ``role_name`` metadata value.
+
+playbooks directory
+--------------------
+
+TBD.
+
+.. _developing_collections_tests_directory:
+
+tests directory
+----------------
+
+Ansible Collections are tested much like Ansible itself, by using the `ansible-test` utility which is released as part of Ansible, version 2.9.0 and newer. Because Ansible Collections are tested using the same tooling as Ansible itself, via `ansible-test`, all Ansible developer documentation for testing is applicable for authoring Collections Tests with one key concept to keep in mind.
+
+See :ref:`testing_collections` for specific information on how to test collections with ``ansible-test``.
+
+When reading the :ref:`developing_testing` documentation, there will be content that applies to running Ansible from source code via a git clone, which is typical of an Ansible developer. However, it's not always typical for an Ansible Collection author to be running Ansible from source but instead from a stable release, and to create Collections it is not necessary to run Ansible from source. Therefore, when references of dealing with `ansible-test` binary paths, command completion, or environment variables are presented throughout the :ref:`developing_testing` documentation; keep in mind that it is not needed for Ansible Collection Testing because the act of installing the stable release of Ansible containing `ansible-test` is expected to setup those things for you.
+
+.. _meta_runtime_yml:
+
+meta directory
+--------------
+
+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:
+
+- *requires_ansible*:
+
+  The version of Ansible required to use the collection. Multiple versions can be separated with a comma.
+
+  .. code:: yaml
+
+     requires_ansible: ">=2.10,<2.11"
+
+  .. note:: although the version is a `PEP440 Version Specifier <https://www.python.org/dev/peps/pep-0440/#version-specifiers>`_ under the hood, Ansible deviates from PEP440 behavior by truncating prerelease segments from the Ansible version. This means that Ansible 2.11.0b1 is compatible with something that ``requires_ansible: ">=2.11"``.
+
+- *plugin_routing*:
+
+  Content in a collection that Ansible needs to load from another location or that has been deprecated/removed.
+  The top level keys of ``plugin_routing`` are types of plugins, with individual plugin names as subkeys.
+  To define a new location for a plugin, set the ``redirect`` field to another name.
+  To deprecate a plugin, use the ``deprecation`` field to provide a custom warning message and the removal version or date. If the plugin has been renamed or moved to a new location, the ``redirect`` field should also be provided. If a plugin is being removed entirely, ``tombstone`` can be used for the fatal error message and removal version or date.
+
+  .. code:: yaml
+
+     plugin_routing:
+       inventory:
+         kubevirt:
+           redirect: community.general.kubevirt
+         my_inventory:
+           tombstone:
+             removal_version: "2.0.0"
+             warning_text: my_inventory has been removed. Please use other_inventory instead.
+       modules:
+         my_module:
+           deprecation:
+             removal_date: "2021-11-30"
+             warning_text: my_module will be removed in a future release of this collection. Use another.collection.new_module instead.
+           redirect: another.collection.new_module
+         podman_image:
+           redirect: containers.podman.podman_image
+       module_utils:
+         ec2:
+           redirect: amazon.aws.ec2
+         util_dir.subdir.my_util:
+           redirect: namespace.name.my_util
+
+- *import_redirection*
+
+  A mapping of names for Python import statements and their redirected locations.
+
+  .. code:: yaml
+
+     import_redirection:
+       ansible.module_utils.old_utility:
+         redirect: ansible_collections.namespace_name.collection_name.plugins.module_utils.new_location
+
+.. seealso::
+
+   :ref:`distributing_collections`
+        Learn how to package and publish your collection
+   :ref:`contributing_maintained_collections`
+        Guidelines for contributing to selected collections
+   `Mailing List <https://groups.google.com/group/ansible-devel>`_
+        The development mailing list
+   `irc.libera.chat <https://libera.chat/>`_
+        #ansible IRC chat channel

docs/docsite/rst/dev_guide/developing_collections_testing.rst

@@ -0,0 +1,83 @@
+.. _testing_collections:
+
+*******************
+Testing collections
+*******************
+
+Testing your collection ensures that your code works well and integrates well with the rest of the Ansible ecosystem. Your collection should pass the general compile and sanity tests for Ansible code. You should also add unit tests to cover the code in your collection and integration tests to cover the interactions between your collection and ansible-core.
+
+.. contents::
+   :local:
+   :depth: 2
+
+Testing tools
+=============
+
+The main tool for testing collections is ``ansible-test``, Ansible's testing tool described in :ref:`developing_testing`. You can run several compile and sanity checks, as well as run unit and integration tests for plugins using ``ansible-test``. When you test collections, test against the ansible-core version(s) you are targeting.
+
+You must always execute ``ansible-test`` from the root directory of a collection. You can run ``ansible-test`` in Docker containers without installing any special requirements. The Ansible team uses this approach in Azure Pipelines both in the ansible/ansible GitHub repository and in the large community collections such as `community.general <https://github.com/ansible-collections/community.general/>`_ and `community.network <https://github.com/ansible-collections/community.network/>`_. The examples below demonstrate running tests in Docker containers.
+
+Compile and sanity tests
+------------------------
+
+To run all compile and sanity tests::
+
+    ansible-test sanity --docker default -v
+
+See :ref:`testing_compile` and :ref:`testing_sanity` for more information. See the :ref:`full list of sanity tests <all_sanity_tests>` for details on the sanity tests and how to fix identified issues.
+
+Adding unit tests
+-----------------
+
+You must place unit tests in the appropriate``tests/unit/plugins/`` directory. For example, you would place tests for ``plugins/module_utils/foo/bar.py`` in ``tests/unit/plugins/module_utils/foo/test_bar.py`` or ``tests/unit/plugins/module_utils/foo/bar/test_bar.py``. For examples, see the `unit tests in community.general <https://github.com/ansible-collections/community.general/tree/master/tests/unit/>`_.
+
+To run all unit tests for all supported Python versions::
+
+    ansible-test units --docker default -v
+
+To run all unit tests only for a specific Python version::
+
+    ansible-test units --docker default -v --python 3.6
+
+To run only a specific unit test::
+
+    ansible-test units --docker default -v --python 3.6 tests/unit/plugins/module_utils/foo/test_bar.py
+
+You can specify Python requirements in the ``tests/unit/requirements.txt`` file. See :ref:`testing_units` for more information, especially on fixture files.
+
+Adding integration tests
+------------------------
+
+You must place integration tests in the appropriate ``tests/integration/targets/`` directory. For module integration tests, you can use the module name alone. For example, you would place integration tests for ``plugins/modules/foo.py`` in a directory called ``tests/integration/targets/foo/``. For non-module plugin integration tests, you must add the plugin type to the directory name. For example, you would place integration tests for ``plugins/connections/bar.py`` in a directory called ``tests/integration/targets/connection_bar/``. For lookup plugins, the directory must be called ``lookup_foo``, for inventory plugins, ``inventory_foo``, and so on.
+
+You can write two different kinds of integration tests:
+
+* Ansible role tests run with ``ansible-playbook`` and validate various aspects of the module. They can depend on other integration tests (usually named ``prepare_bar`` or ``setup_bar``, which prepare a service or install a requirement named ``bar`` in order to test module ``foo``) to set-up required resources, such as installing required libraries or setting up server services.
+* ``runme.sh`` tests run directly as scripts. They can set up inventory files, and execute ``ansible-playbook`` or ``ansible-inventory`` with various settings.
+
+For examples, see the `integration tests in community.general <https://github.com/ansible-collections/community.general/tree/master/tests/integration/targets/>`_. See also :ref:`testing_integration` for more details.
+
+Since integration tests can install requirements, and set-up, start and stop services, we recommended running them in docker containers or otherwise restricted environments whenever possible. By default, ``ansible-test`` supports Docker images for several operating systems. See the `list of supported docker images <https://github.com/ansible/ansible/blob/devel/test/lib/ansible_test/_data/completion/docker.txt>`_ for all options. Use the ``default`` image mainly for platform-independent integration tests, such as those for cloud modules. The following examples use the ``centos8`` image.
+
+To execute all integration tests for a collection::
+
+    ansible-test integration --docker centos8 -v
+
+If you want more detailed output, run the command with ``-vvv`` instead of ``-v``. Alternatively, specify ``--retry-on-error`` to automatically re-run failed tests with higher verbosity levels.
+
+To execute only the integration tests in a specific directory::
+
+    ansible-test integration --docker centos8 -v connection_bar
+
+You can specify multiple target names. Each target name is the name of a directory in ``tests/integration/targets/``.
+
+.. seealso::
+
+   :ref:`developing_testing`
+       More resources on testing Ansible
+   :ref:`contributing_maintained_collections`
+       Guidelines for contributing to selected collections
+   `Mailing List <https://groups.google.com/group/ansible-devel>`_
+       The development mailing list
+   `irc.libera.chat <https://libera.chat/>`_
+       #ansible IRC chat channel

docs/docsite/rst/dev_guide/developing_core.rst

@@ -17,5 +17,5 @@ Although ``ansible-core`` (the code hosted in the `ansible/ansible repository <h
        Learn about developing plugins
    `Mailing List <https://groups.google.com/group/ansible-devel>`_
        The development mailing list
-   `irc.freenode.net <http://irc.freenode.net>`_
+   `irc.libera.chat <https://libera.chat>`_
        #ansible-devel IRC chat channel

docs/docsite/rst/dev_guide/developing_inventory.rst

@@ -469,9 +469,9 @@ An easy way to see how this should look is using :ref:`ansible-inventory`, which
        Get started with developing a module
    :ref:`developing_plugins`
        How to develop plugins
-   `Ansible Tower <https://www.ansible.com/products/tower>`_
+   `AWX <https://github.com/ansible/awx>`_
        REST API endpoint and GUI for Ansible, syncs with dynamic inventory
    `Development Mailing List <https://groups.google.com/group/ansible-devel>`_
        Mailing list for development topics
-   `irc.freenode.net <http://irc.freenode.net>`_
+   `irc.libera.chat <https://libera.chat/>`_
        #ansible IRC chat channel

docs/docsite/rst/dev_guide/developing_modules.rst

@@ -47,5 +47,5 @@ If your use case isn't covered by an existing module, an action plugin, or a rol
        Browse existing collections, modules, and plugins
    `Mailing List <https://groups.google.com/group/ansible-devel>`_
        Development mailing list
-   `irc.freenode.net <http://irc.freenode.net>`_
+   `irc.libera.chat <https://libera.chat/>`_
        #ansible IRC chat channel

docs/docsite/rst/dev_guide/developing_modules_checklist.rst

@@ -31,7 +31,7 @@ To contribute a module to most Ansible collections, you must:
 
 Additional requirements may apply for certain collections. Review the individual collection repositories for more information.
 
-Please make sure your module meets these requirements before you submit your PR/proposal. If you have questions, reach out via `Ansible's IRC chat channel <http://irc.freenode.net>`_ or the `Ansible development mailing list <https://groups.google.com/group/ansible-devel>`_.
+Please make sure your module meets these requirements before you submit your PR/proposal. If you have questions, reach out via ``#ansible-devel``, Ansible's IRC chat channel on `irc.libera.chat <http://libera.chat>`_ or the `Ansible development mailing list <https://groups.google.com/group/ansible-devel>`_.
 
 Contributing to Ansible: subjective requirements
 ================================================

docs/docsite/rst/dev_guide/developing_modules_documenting.rst

@@ -233,8 +233,8 @@ Linking and other format macros within module documentation
 
 You can link from your module documentation to other module docs, other resources on docs.ansible.com, and resources elsewhere on the internet with the help of some pre-defined macros. The correct formats for these macros are:
 
-* ``L()`` for links with a heading. For example: ``See L(Ansible Tower,https://www.ansible.com/products/tower).`` As of Ansible 2.10, do not use ``L()`` for relative links between Ansible documentation and collection documentation.
-* ``U()`` for URLs. For example: ``See U(https://www.ansible.com/products/tower) for an overview.``
+* ``L()`` for links with a heading. For example: ``See L(Ansible Automation Platform,https://www.ansible.com/products/automation-platform).`` As of Ansible 2.10, do not use ``L()`` for relative links between Ansible documentation and collection documentation.
+* ``U()`` for URLs. For example: ``See U(https://www.ansible.com/products/automation-platform) for an overview.``
 * ``R()`` for cross-references with a heading (added in Ansible 2.10). For example: ``See R(Cisco IOS Platform Guide,ios_platform_options)``.  Use the RST anchor for the cross-reference. See :ref:`adding_anchors_rst` for details.
 * ``M()`` for module names. For example: ``See also M(ansible.builtin.yum) or M(community.general.apt_rpm)``.
 
@@ -255,7 +255,7 @@ content in a uniform way:
 .. note::
     - To refer to a group of modules in a collection, use ``R()``.  When a collection is not the right granularity, use ``C(..)``:
 
-        - ``Refer to the R(community.kubernetes collection, plugins_in_community.kubernetes) for information on managing kubernetes clusters.``
+        - ``Refer to the R(kubernetes.core collection, plugins_in_kubernetes.core) for information on managing kubernetes clusters.``
         - ``The C(win_*) modules (spread across several collections) allow you to manage various aspects of windows hosts.``
 
 
@@ -268,7 +268,7 @@ content in a uniform way:
 Documentation fragments
 -----------------------
 
-If you are writing multiple related modules, they may share common documentation, such as authentication details, file mode settings, ``notes:`` or ``seealso:`` entries. Rather than duplicate that information in each module's ``DOCUMENTATION`` block, you can save it once as a doc_fragment plugin and use it in each module's documentation. In Ansible, shared documentation fragments are contained in a ``ModuleDocFragment`` class in `lib/ansible/plugins/doc_fragments/ <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/doc_fragments>`_ or the equivalent directory in a collection. To include a documentation fragment, add ``extends_documentation_fragment: FRAGMENT_NAME`` in your module documentation. Use the fully qualified collection name for the FRAGMENT_NAME (for example, ``community.kubernetes.k8s_auth_options``).
+If you are writing multiple related modules, they may share common documentation, such as authentication details, file mode settings, ``notes:`` or ``seealso:`` entries. Rather than duplicate that information in each module's ``DOCUMENTATION`` block, you can save it once as a doc_fragment plugin and use it in each module's documentation. In Ansible, shared documentation fragments are contained in a ``ModuleDocFragment`` class in `lib/ansible/plugins/doc_fragments/ <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/doc_fragments>`_ or the equivalent directory in a collection. To include a documentation fragment, add ``extends_documentation_fragment: FRAGMENT_NAME`` in your module documentation. Use the fully qualified collection name for the FRAGMENT_NAME (for example, ``kubernetes.core.k8s_auth_options``).
 
 Modules should only use items from a doc fragment if the module will implement all of the interface documented there in a manner that behaves the same as the existing modules which import that fragment. The goal is that items imported from the doc fragment will behave identically when used in another module that imports the doc fragment.
 

docs/docsite/rst/dev_guide/developing_modules_general.rst

@@ -218,8 +218,8 @@ The :ref:`Community Guide <ansible_community_guide>` covers how to open a pull r
 Communication and development support
 =====================================
 
-Join the IRC channel ``#ansible-devel`` on freenode for discussions
-surrounding Ansible development.
+Join the IRC channel ``#ansible-devel`` on `irc.libera.chat <https://libera.chat/>`_ for
+discussions surrounding Ansible development.
 
 For questions and discussions pertaining to using the Ansible product,
 use the ``#ansible`` channel.

docs/docsite/rst/dev_guide/developing_modules_general_windows.rst

@@ -690,8 +690,8 @@ idempotent and does not report changes. For example:
 Windows communication and development support
 =============================================
 
-Join the IRC channel ``#ansible-devel`` or ``#ansible-windows`` on freenode for
-discussions about Ansible development for Windows.
+Join the ``#ansible-devel`` or ``#ansible-windows`` irc channels on `irc.libera.chat
+<https://libera.chat/>`_ for discussions about Ansible development for Windows.
 
 For questions and discussions pertaining to using the Ansible product,
 use the ``#ansible`` channel.

docs/docsite/rst/dev_guide/developing_modules_in_groups.rst

@@ -45,6 +45,8 @@ Speak to us
 
 Circulating your ideas before coding helps you adopt good practices and avoid common mistakes. After reading the "Before you start coding" section you should have a reasonable idea of the structure of your modules. Write a list of your proposed plugin and/or module names, with a short description of what each one does. Circulate that list on IRC or a mailing list so the Ansible community can review your ideas for consistency and familiarity. Names and functionality that are consistent, predictable, and familiar make your collection easier to use.
 
+.. _developing_in_groups_support:
+
 Where to get support
 ====================
 
@@ -53,7 +55,7 @@ Ansible has a thriving and knowledgeable community of module developers that is
 In the :ref:`ansible_community_guide` you can find how to:
 
 * Subscribe to the Mailing Lists - We suggest "Ansible Development List" and "Ansible Announce list"
-* ``#ansible-devel`` - We have found that IRC ``#ansible-devel`` on FreeNode's IRC network works best for developers so we can have an interactive dialogue.
+* ``#ansible-devel`` - We have found that communicating on the IRC channel, ``#ansible-devel`` on `libera.chat's <https://libera.chat/>`_ IRC network works best for developers so we can have an interactive dialogue.
 * IRC meetings - Join the various weekly IRC meetings `meeting schedule and agenda page <https://github.com/ansible/community/blob/master/meetings/README.md>`_
 
 Required files
@@ -68,7 +70,7 @@ Your collection should include the following files to be usable:
 
 When you have these files ready, review the :ref:`developing_modules_checklist` again. If you are creating a new collection, you are responsible for all procedures related to your repository, including setting rules for contributions, finding reviewers, and testing and maintaining the code in your collection.
 
-If you need help or advice, consider join the ``#ansible-devel`` IRC channel (see how in the "Where to get support").
+If you need help or advice, consider joining the ``#ansible-devel`` IRC channel (see how in the :ref:`Where to get support <developing_in_groups_support>` section).
 
 New to git or GitHub
 ====================

docs/docsite/rst/dev_guide/developing_plugins.rst

@@ -29,7 +29,7 @@ You should return errors encountered during plugin execution by raising ``Ansibl
 
 .. code-block:: python
 
-    from ansible.module_utils._text import to_native
+    from ansible.module_utils.common.text.converters import to_native
 
     try:
         cause_an_exception()
@@ -45,7 +45,7 @@ You must convert any strings returned by your plugin into Python's unicode type.
 
 .. code-block:: python
 
-    from ansible.module_utils._text import to_text
+    from ansible.module_utils.common.text.converters import to_text
     result_string = to_text(result_string)
 
 Plugin configuration & documentation standards
@@ -497,5 +497,5 @@ For example vars plugins, see the source code for the `vars plugins included wit
        Learn about how to write Ansible modules
    `Mailing List <https://groups.google.com/group/ansible-devel>`_
        The development mailing list
-   `irc.freenode.net <http://irc.freenode.net>`_
+   `irc.libera.chat <https://libera.chat/>`_
        #ansible IRC chat channel

docs/docsite/rst/dev_guide/developing_python_3.rst

@@ -116,7 +116,7 @@ to yield text but instead do the conversion explicitly ourselves. For example:
 
 .. code-block:: python
 
-    from ansible.module_utils._text import to_text
+    from ansible.module_utils.common.text.converters import to_text
 
     with open('filename-with-utf8-data.txt', 'rb') as my_file:
         b_data = my_file.read()
@@ -136,7 +136,7 @@ Writing to files is the opposite process:
 
 .. code-block:: python
 
-    from ansible.module_utils._text import to_bytes
+    from ansible.module_utils.common.text.converters import to_bytes
 
     with open('filename.txt', 'wb') as my_file:
         my_file.write(to_bytes(some_text_string))
@@ -160,7 +160,7 @@ works on both versions:
 
     import os.path
 
-    from ansible.module_utils._text import to_bytes
+    from ansible.module_utils.common.text.converters import to_bytes
 
     filename = u'/var/tmp/くらとみ.txt'
     f = open(to_bytes(filename), 'wb')
@@ -246,9 +246,9 @@ In ``module_utils`` code:
 * Functions that return strings **must** document whether they return strings of the same type as they were given or native strings.
 
 Module-utils functions are therefore often very defensive in nature.
-They convert their string parameters into text (using ``ansible.module_utils._text.to_text``)
+They convert their string parameters into text (using ``ansible.module_utils.common.text.converters.to_text``)
 at the beginning of the function, do their work, and then convert
-the return values into the native string type (using ``ansible.module_utils._text.to_native``)
+the return values into the native string type (using ``ansible.module_utils.common.text.converters.to_native``)
 or back to the string type that their parameters received.
 
 Tips, tricks, and idioms for Python 2/Python 3 compatibility