New release v2.10.6

(cherry picked from commit 1a2da990a4)

Co-authored-by: Matt Clay <mclay@redhat.com>

.azure-pipelines/azure-pipelines.yml

@@ -0,0 +1,256 @@
+trigger:
+  batch: true
+  branches:
+    include:
+      - devel
+      - stable-*
+
+pr:
+  autoCancel: true
+  branches:
+    include:
+      - devel
+      - stable-*
+
+schedules:
+  - cron: 0 7 * * *
+    displayName: Nightly
+    always: true
+    branches:
+      include:
+        - devel
+        - stable-*
+
+variables:
+  - name: checkoutPath
+    value: ansible
+  - name: coverageBranches
+    value: devel
+  - name: pipelinesCoverage
+    value: coverage
+  - name: entryPoint
+    value: test/utils/shippable/shippable.sh
+  - name: fetchDepth
+    value: 500
+
+resources:
+  containers:
+    - container: default
+      image: quay.io/ansible/azure-pipelines-test-container:1.7.1
+
+pool: Standard
+
+stages:
+  - stage: Sanity
+    dependsOn: []
+    jobs:
+      - template: templates/matrix.yml
+        parameters:
+          nameFormat: Test {0}
+          testFormat: sanity/{0}
+          targets:
+            - test: 1
+            - test: 2
+            - test: 3
+            - test: 4
+            - test: 5
+  - stage: Units
+    dependsOn: []
+    jobs:
+      - template: templates/matrix.yml
+        parameters:
+          nameFormat: Python {0}
+          testFormat: units/{0}
+          targets:
+            - test: 2.6
+            - test: 2.7
+            - test: 3.5
+            - test: 3.6
+            - test: 3.7
+            - test: 3.8
+            - test: 3.9
+  - stage: Windows
+    dependsOn: []
+    jobs:
+      - template: templates/matrix.yml
+        parameters:
+          nameFormat: Server {0}
+          testFormat: windows/{0}/1
+          targets:
+            - test: 2012
+            - test: 2012-R2
+            - test: 2016
+            - test: 2019
+  - stage: Remote
+    dependsOn: []
+    jobs:
+      - template: templates/matrix.yml
+        parameters:
+          targets:
+            - name: macOS 11.1
+              test: macos/11.1
+            - name: RHEL 7.9
+              test: rhel/7.9
+            - name: RHEL 8.2
+              test: rhel/8.2
+            - name: FreeBSD 11.1
+              test: freebsd/11.1
+            - name: FreeBSD 12.1
+              test: freebsd/12.1
+          groups:
+            - 1
+            - 2
+            - 3
+            - 4
+            - 5
+  - stage: Docker
+    dependsOn: []
+    jobs:
+      - template: templates/matrix.yml
+        parameters:
+          testFormat: linux/{0}
+          targets:
+            - name: CentOS 6
+              test: centos6
+            - name: CentOS 7
+              test: centos7
+            - name: CentOS 8
+              test: centos8
+            - name: Fedora 31
+              test: fedora31
+            - name: Fedora 32
+              test: fedora32
+            - name: openSUSE 15 py2
+              test: opensuse15py2
+            - name: openSUSE 15 py3
+              test: opensuse15
+            - name: Ubuntu 16.04
+              test: ubuntu1604
+            - name: Ubuntu 18.04
+              test: ubuntu1804
+            - name: Ubuntu 20.04
+              test: ubuntu2004
+          groups:
+            - 1
+            - 2
+            - 3
+            - 4
+            - 5
+  - stage: Fallaxy
+    dependsOn: []
+    jobs:
+      - template: templates/matrix.yml
+        parameters:
+          nameFormat: Python {0}
+          testFormat: fallaxy/{0}/1
+          targets:
+            - test: 2.7
+            - test: 3.6
+  - stage: Generic
+    dependsOn: []
+    jobs:
+      - template: templates/matrix.yml
+        parameters:
+          nameFormat: Python {0}
+          testFormat: generic/{0}/1
+          targets:
+            - test: 2.7
+            - test: 3.6
+  - stage: Incidental_Remote
+    displayName: Incidental Remote
+    dependsOn: []
+    jobs:
+      - template: templates/matrix.yml
+        parameters:
+          testFormat: i/{0}
+          targets:
+            - name: OS X 10.11
+              test: osx/10.11
+            - name: RHEL 7.9
+              test: rhel/7.9
+            - name: RHEL 8.2
+              test: rhel/8.2
+            - name: FreeBSD 11.1
+              test: freebsd/11.1
+            - name: FreeBSD 12.1
+              test: freebsd/12.1
+  - stage: Incidental_Docker
+    displayName: Incidental Docker
+    dependsOn: []
+    jobs:
+      - template: templates/matrix.yml
+        parameters:
+          testFormat: i/linux/{0}
+          targets:
+            - name: CentOS 6
+              test: centos6
+            - name: CentOS 7
+              test: centos7
+            - name: CentOS 8
+              test: centos8
+            - name: Fedora 31
+              test: fedora31
+            - name: Fedora 32
+              test: fedora32
+            - name: openSUSE 15 py2
+              test: opensuse15py2
+            - name: openSUSE 15 py3
+              test: opensuse15
+            - name: Ubuntu 16.04
+              test: ubuntu1604
+            - name: Ubuntu 18.04
+              test: ubuntu1804
+            - name: Ubuntu 20.04
+              test: ubuntu2004
+  - stage: Incidental_Windows
+    displayName: Incidental Windows
+    dependsOn: []
+    jobs:
+      - template: templates/matrix.yml
+        parameters:
+          nameFormat: Server {0}
+          testFormat: i/windows/{0}
+          targets:
+            - test: 2012
+            - test: 2012-R2
+            - test: 2016
+            - test: 2019
+  - stage: Incidental
+    dependsOn: []
+    jobs:
+      - template: templates/matrix.yml
+        parameters:
+          testFormat: i/{0}/1
+          targets:
+            - name: IOS Python
+              test: ios/csr1000v/
+            - name: VyOS Python 2.7
+              test: vyos/1.1.8/2.7
+            - name: VyOS Python 3.6
+              test: vyos/1.1.8/3.6
+            - name: AWS Python 2.7
+              test: aws/2.7
+            - name: AWS Python 3.6
+              test: aws/3.6
+            - name: Azure Python 2.7
+              test: azure/2.7
+            - name: Azure Python 3.6
+              test: azure/3.6
+            - name: Cloud Python
+              test: cloud/
+  - stage: Summary
+    condition: succeededOrFailed()
+    dependsOn:
+      - Sanity
+      - Units
+      - Windows
+      - Remote
+      - Docker
+      - Fallaxy
+      - Generic
+      - Incidental_Remote
+      - Incidental_Docker
+      - Incidental_Windows
+      - Incidental
+    jobs:
+      - template: templates/coverage.yml

.azure-pipelines/scripts/aggregate-coverage.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# Aggregate code coverage results for later processing.
+
+set -o pipefail -eu
+
+agent_temp_directory="$1"
+
+PATH="${PWD}/bin:${PATH}"
+
+mkdir "${agent_temp_directory}/coverage/"
+
+options=(--venv --venv-system-site-packages --color -v)
+
+ansible-test coverage combine --export "${agent_temp_directory}/coverage/" "${options[@]}"
+
+if ansible-test coverage analyze targets generate --help >/dev/null 2>&1; then
+    # Only analyze coverage if the installed version of ansible-test supports it.
+    # Doing so allows this script to work unmodified for multiple Ansible versions.
+    ansible-test coverage analyze targets generate "${agent_temp_directory}/coverage/coverage-analyze-targets.json" "${options[@]}"
+fi

.azure-pipelines/scripts/combine-coverage.py

@@ -0,0 +1,60 @@
+#!/usr/bin/env python
+"""
+Combine coverage data from multiple jobs, keeping the data only from the most recent attempt from each job.
+Coverage artifacts must be named using the format: "Coverage $(System.JobAttempt) {StableUniqueNameForEachJob}"
+The recommended coverage artifact name format is: Coverage $(System.JobAttempt) $(System.StageDisplayName) $(System.JobDisplayName)
+Keep in mind that Azure Pipelines does not enforce unique job display names (only names).
+It is up to pipeline authors to avoid name collisions when deviating from the recommended format.
+"""
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+import os
+import re
+import shutil
+import sys
+
+
+def main():
+    """Main program entry point."""
+    source_directory = sys.argv[1]
+
+    if '/ansible_collections/' in os.getcwd():
+        output_path = "tests/output"
+    else:
+        output_path = "test/results"
+
+    destination_directory = os.path.join(output_path, 'coverage')
+
+    if not os.path.exists(destination_directory):
+        os.makedirs(destination_directory)
+
+    jobs = {}
+    count = 0
+
+    for name in os.listdir(source_directory):
+        match = re.search('^Coverage (?P<attempt>[0-9]+) (?P<label>.+)$', name)
+        label = match.group('label')
+        attempt = int(match.group('attempt'))
+        jobs[label] = max(attempt, jobs.get(label, 0))
+
+    for label, attempt in jobs.items():
+        name = 'Coverage {attempt} {label}'.format(label=label, attempt=attempt)
+        source = os.path.join(source_directory, name)
+        source_files = os.listdir(source)
+
+        for source_file in source_files:
+            source_path = os.path.join(source, source_file)
+            destination_path = os.path.join(destination_directory, source_file + '.' + label)
+            print('"%s" -> "%s"' % (source_path, destination_path))
+            shutil.copyfile(source_path, destination_path)
+            count += 1
+
+    print('Coverage file count: %d' % count)
+    print('##vso[task.setVariable variable=coverageFileCount]%d' % count)
+    print('##vso[task.setVariable variable=outputPath]%s' % output_path)
+
+
+if __name__ == '__main__':
+    main()

.azure-pipelines/scripts/process-results.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# Check the test results and set variables for use in later steps.
+
+set -o pipefail -eu
+
+if [[ "$PWD" =~ /ansible_collections/ ]]; then
+    output_path="tests/output"
+else
+    output_path="test/results"
+fi
+
+echo "##vso[task.setVariable variable=outputPath]${output_path}"
+
+if compgen -G "${output_path}"'/junit/*.xml' > /dev/null; then
+    echo "##vso[task.setVariable variable=haveTestResults]true"
+fi
+
+if compgen -G "${output_path}"'/bot/ansible-test-*' > /dev/null; then
+    echo "##vso[task.setVariable variable=haveBotResults]true"
+fi
+
+if compgen -G "${output_path}"'/coverage/*' > /dev/null; then
+    echo "##vso[task.setVariable variable=haveCoverageData]true"
+fi

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

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# Upload code coverage reports to codecov.io.
+# Multiple coverage files from multiple languages are accepted and aggregated after upload.
+# Python coverage, as well as PowerShell and Python stubs can all be uploaded.
+
+set -o pipefail -eu
+
+output_path="$1"
+
+curl --silent --show-error https://codecov.io/bash > codecov.sh
+
+for file in "${output_path}"/reports/coverage*.xml; do
+    name="${file}"
+    name="${name##*/}"  # remove path
+    name="${name##coverage=}"  # remove 'coverage=' prefix if present
+    name="${name%.xml}"  # remove '.xml' suffix
+
+    bash codecov.sh \
+        -f "${file}" \
+        -n "${name}" \
+        -X coveragepy \
+        -X gcov \
+        -X fix \
+        -X search \
+        -X xcode \
+        || echo "Failed to upload code coverage report to codecov.io: ${file}"
+done

.azure-pipelines/scripts/report-coverage.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# Generate code coverage reports for uploading to Azure Pipelines and codecov.io.
+
+set -o pipefail -eu
+
+PATH="${PWD}/bin:${PATH}"
+
+if ! ansible-test --help >/dev/null 2>&1; then
+    # Install the devel version of ansible-test for generating code coverage reports.
+    # This is only used by Ansible Collections, which are typically tested against multiple Ansible versions (in separate jobs).
+    # Since a version of ansible-test is required that can work the output from multiple older releases, the devel version is used.
+    pip install https://github.com/ansible/ansible/archive/devel.tar.gz --disable-pip-version-check
+fi
+
+ansible-test coverage xml --stub --venv --venv-system-site-packages --color -v

.azure-pipelines/scripts/run-tests.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# Configure the test environment and run the tests.
+
+set -o pipefail -eu
+
+entry_point="$1"
+test="$2"
+read -r -a coverage_branches <<< "$3"  # space separated list of branches to run code coverage on for scheduled builds
+
+export COMMIT_MESSAGE
+export COMPLETE
+export COVERAGE
+export IS_PULL_REQUEST
+
+if [ "${SYSTEM_PULLREQUEST_TARGETBRANCH:-}" ]; then
+    IS_PULL_REQUEST=true
+    COMMIT_MESSAGE=$(git log --format=%B -n 1 HEAD^2)
+else
+    IS_PULL_REQUEST=
+    COMMIT_MESSAGE=$(git log --format=%B -n 1 HEAD)
+fi
+
+COMPLETE=
+COVERAGE=
+
+if [ "${BUILD_REASON}" = "Schedule" ]; then
+    COMPLETE=yes
+
+    if printf '%s\n' "${coverage_branches[@]}" | grep -q "^${BUILD_SOURCEBRANCHNAME}$"; then
+        COVERAGE=yes
+    fi
+fi
+
+"${entry_point}" "${test}" 2>&1 | "$(dirname "$0")/time-command.py"

.azure-pipelines/scripts/time-command.py

@@ -0,0 +1,25 @@
+#!/usr/bin/env python
+"""Prepends a relative timestamp to each input line from stdin and writes it to stdout."""
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+import sys
+import time
+
+
+def main():
+    """Main program entry point."""
+    start = time.time()
+
+    sys.stdin.reconfigure(errors='surrogateescape')
+    sys.stdout.reconfigure(errors='surrogateescape')
+
+    for line in sys.stdin:
+        seconds = time.time() - start
+        sys.stdout.write('%02d:%02d %s' % (seconds // 60, seconds % 60, line))
+        sys.stdout.flush()
+
+
+if __name__ == '__main__':
+    main()

.azure-pipelines/templates/coverage.yml

@@ -0,0 +1,39 @@
+# This template adds a job for processing code coverage data.
+# It will upload results to Azure Pipelines and codecov.io.
+# Use it from a job stage that completes after all other jobs have completed.
+# This can be done by placing it in a separate summary stage that runs after the test stage(s) have completed.
+
+jobs:
+  - job: Coverage
+    displayName: Code Coverage
+    container: default
+    workspace:
+      clean: all
+    steps:
+      - checkout: self
+        fetchDepth: $(fetchDepth)
+        path: $(checkoutPath)
+      - task: DownloadPipelineArtifact@2
+        displayName: Download Coverage Data
+        inputs:
+          path: coverage/
+          patterns: "Coverage */*=coverage.combined"
+      - bash: .azure-pipelines/scripts/combine-coverage.py coverage/
+        displayName: Combine Coverage Data
+      - bash: .azure-pipelines/scripts/report-coverage.sh
+        displayName: Generate Coverage Report
+        condition: gt(variables.coverageFileCount, 0)
+      - task: PublishCodeCoverageResults@1
+        inputs:
+          codeCoverageTool: Cobertura
+          # Azure Pipelines only accepts a single coverage data file.
+          # That means only Python or PowerShell coverage can be uploaded, but not both.
+          # Set the "pipelinesCoverage" variable to determine which type is uploaded.
+          # Use "coverage" for Python and "coverage-powershell" for PowerShell.
+          summaryFileLocation: "$(outputPath)/reports/$(pipelinesCoverage).xml"
+        displayName: Publish to Azure Pipelines
+        condition: gt(variables.coverageFileCount, 0)
+      - bash: .azure-pipelines/scripts/publish-codecov.sh "$(outputPath)"
+        displayName: Publish to codecov.io
+        condition: gt(variables.coverageFileCount, 0)
+        continueOnError: true

.azure-pipelines/templates/matrix.yml

@@ -0,0 +1,55 @@
+# This template uses the provided targets and optional groups to generate a matrix which is then passed to the test template.
+# If this matrix template does not provide the required functionality, consider using the test template directly instead.
+
+parameters:
+  # A required list of dictionaries, one per test target.
+  # Each item in the list must contain a "test" or "name" key.
+  # Both may be provided. If one is omitted, the other will be used.
+  - name: targets
+    type: object
+
+  # An optional list of values which will be used to multiply the targets list into a matrix.
+  # Values can be strings or numbers.
+  - name: groups
+    type: object
+    default: []
+
+  # An optional format string used to generate the job name.
+  # - {0} is the name of an item in the targets list.
+  - name: nameFormat
+    type: string
+    default: "{0}"
+
+  # An optional format string used to generate the test name.
+  # - {0} is the name of an item in the targets list.
+  - name: testFormat
+    type: string
+    default: "{0}"
+
+  # An optional format string used to add the group to the job name.
+  # {0} is the formatted name of an item in the targets list.
+  # {{1}} is the group -- be sure to include the double "{{" and "}}".
+  - name: nameGroupFormat
+    type: string
+    default: "{0} - {{1}}"
+
+  # An optional format string used to add the group to the test name.
+  # {0} is the formatted test of an item in the targets list.
+  # {{1}} is the group -- be sure to include the double "{{" and "}}".
+  - name: testGroupFormat
+    type: string
+    default: "{0}/{{1}}"
+
+jobs:
+  - template: test.yml
+    parameters:
+      jobs:
+        - ${{ if eq(length(parameters.groups), 0) }}:
+          - ${{ each target in parameters.targets }}:
+            - name: ${{ format(parameters.nameFormat, coalesce(target.name, target.test)) }}
+              test: ${{ format(parameters.testFormat, coalesce(target.test, target.name)) }}
+        - ${{ if not(eq(length(parameters.groups), 0)) }}:
+          - ${{ each group in parameters.groups }}:
+            - ${{ each target in parameters.targets }}:
+              - name: ${{ format(format(parameters.nameGroupFormat, parameters.nameFormat), coalesce(target.name, target.test), group) }}
+                test: ${{ format(format(parameters.testGroupFormat, parameters.testFormat), coalesce(target.test, target.name), group) }}

.azure-pipelines/templates/test.yml

@@ -0,0 +1,45 @@
+# This template uses the provided list of jobs to create test one or more test jobs.
+# It can be used directly if needed, or through the matrix template.
+
+parameters:
+  # A required list of dictionaries, one per test job.
+  # Each item in the list must contain a "job" and "name" key.
+  - name: jobs
+    type: object
+
+jobs:
+  - ${{ each job in parameters.jobs }}:
+    - job: test_${{ replace(replace(replace(job.test, '/', '_'), '.', '_'), '-', '_') }}
+      displayName: ${{ job.name }}
+      container: default
+      workspace:
+        clean: all
+      steps:
+        - checkout: self
+          fetchDepth: $(fetchDepth)
+          path: $(checkoutPath)
+        - bash: .azure-pipelines/scripts/run-tests.sh "$(entryPoint)" "${{ job.test }}" "$(coverageBranches)"
+          displayName: Run Tests
+        - bash: .azure-pipelines/scripts/process-results.sh
+          condition: succeededOrFailed()
+          displayName: Process Results
+        - bash: .azure-pipelines/scripts/aggregate-coverage.sh "$(Agent.TempDirectory)"
+          condition: eq(variables.haveCoverageData, 'true')
+          displayName: Aggregate Coverage Data
+        - task: PublishTestResults@2
+          condition: eq(variables.haveTestResults, 'true')
+          inputs:
+            testResultsFiles: "$(outputPath)/junit/*.xml"
+          displayName: Publish Test Results
+        - task: PublishPipelineArtifact@1
+          condition: eq(variables.haveBotResults, 'true')
+          displayName: Publish Bot Results
+          inputs:
+            targetPath: "$(outputPath)/bot/"
+            artifactName: "Bot $(System.JobAttempt) $(System.StageDisplayName) $(System.JobDisplayName)"
+        - task: PublishPipelineArtifact@1
+          condition: eq(variables.haveCoverageData, 'true')
+          displayName: Publish Coverage Data
+          inputs:
+            targetPath: "$(Agent.TempDirectory)/coverage/"
+            artifactName: "Coverage $(System.JobAttempt) $(System.StageDisplayName) $(System.JobDisplayName)"

.github/BOTMETA.yml

@@ -4553,8 +4553,6 @@ files:
     notified: mattclay
   hacking/shippable/:
     notified: mattclay
-  shippable.yml:
-    notified: mattclay
   lib/ansible/modules/cloud/podman/__init__.py:
     migrated_to: containers.podman
   lib/ansible/modules/cloud/podman/podman_container_info.py:

.gitignore

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

MANIFEST.in

@@ -2,8 +2,8 @@ include README.rst
 include COPYING
 include SYMLINK_CACHE.json
 include requirements.txt
-include shippable.yml
 recursive-include docs *
+include docs/docsite/rst/collections/all_plugins.rst
 exclude docs/docsite/rst_warnings
 recursive-exclude docs/docsite/_build *
 recursive-exclude docs/docsite/_extensions *.pyc *.pyo

README.rst

@@ -96,12 +96,12 @@ GNU General Public License v3.0 or later
 
 See `COPYING <COPYING>`_ to see the full text.
 
-.. |PyPI version| image:: https://img.shields.io/pypi/v/ansible.svg
-   :target: https://pypi.org/project/ansible
+.. |PyPI version| image:: https://img.shields.io/pypi/v/ansible-base.svg
+   :target: https://pypi.org/project/ansible-base
 .. |Docs badge| image:: https://img.shields.io/badge/docs-latest-brightgreen.svg
    :target: https://docs.ansible.com/ansible/latest/
-.. |Build Status| image:: https://api.shippable.com/projects/573f79d02a8192902e20e34b/badge?branch=devel
-   :target: https://app.shippable.com/projects/573f79d02a8192902e20e34b
+.. |Build Status| image:: https://dev.azure.com/ansible/ansible/_apis/build/status/CI?branchName=stable-2.10
+   :target: https://dev.azure.com/ansible/ansible/_build/latest?definitionId=20&branchName=stable-2.10
 .. |Chat badge| image:: https://img.shields.io/badge/chat-IRC-brightgreen.svg
    :target: https://docs.ansible.com/ansible/latest/community/communication.html
 .. |Code Of Conduct| image:: https://img.shields.io/badge/code%20of%20conduct-Ansible-silver.svg

changelogs/CHANGELOG-v2.10.rst

@@ -5,6 +5,140 @@ Ansible Base 2.10 "When the Levee Breaks" Release Notes
 .. contents:: Topics
 
 
+v2.10.6
+=======
+
+Release Summary
+---------------
+
+| Release Date: 2021-02-17
+| `Porting Guide <https://docs.ansible.com/ansible/devel/porting_guides.html>`__
+
+
+Minor Changes
+-------------
+
+- ansible-test - Added Ubuntu 20.04 LTS image to the default completion list
+- inventory cache - do not show a warning when the cache file does not (yet) exist.
+
+Security Fixes
+--------------
+
+- **security issue** - Mask default and fallback values for ``no_log`` module options (CVE-2021-20228)
+
+Bugfixes
+--------
+
+- Added unsafe_writes test.
+- Always mention the name of the deprecated or tombstoned plugin in routing deprecation/tombstone messages (https://github.com/ansible/ansible/pull/73059).
+- Correct the inventory source error parse handling, specifically make the config INVENTORY_ANY_UNPARSED_IS_FAILED work as expected.
+- Enabled unsafe_writes for get_url which was ignoring the paramter.
+- Fix incorrect variable scoping when using ``import with context`` in Jinja2 templates. (https://github.com/ansible/ansible/issues/72615)
+- Restored unsafe_writes functionality which was being skipped.
+- allow become method 'su' to work on 'local' connection by allocating a fake tty.
+- ansble-test - only require a collection name in deprecation warnings when necessary (https://github.com/ansible/ansible/pull/72987)
+- ansible-test - Temporarily limit ``cryptography`` to versions before 3.4 to enable tests to function.
+- 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 sanity changelog test - bump dependency on antsibull-changelog to 0.9.0 so that `fragments that add new plugins or objects <https://github.com/ansible-community/antsibull-changelog/blob/main/docs/changelogs.rst#adding-new-roles-playbooks-test-and-filter-plugins>`_ will not fail validation (https://github.com/ansible/ansible/pull/73428).
+- display correct error information when an error exists in the last line of the file (https://github.com/ansible/ansible/issues/16456)
+- facts - properly report virtualization facts for Linux guests running on bhyve (https://github.com/ansible/ansible/issues/73167)
+- git - Only pass ``--raw`` flag to git verify commands (verify-tag, verify-commit) when ``gpg_whitelist`` is in use. Otherwise don't pass it so that non-whitelist GPG validation still works on older Git versions. (https://github.com/ansible/ansible/issues/64469)
+- import_playbook - change warning about extra parameters to deprecation (https://github.com/ansible/ansible/issues/72745)
+- pause - do not warn when running in the background if a timeout is provided (https://github.com/ansible/ansible/issues/73042)
+- psrp connection plugin - ``to_text(stdout)`` before ``json.loads`` in psrp.Connection.put_file in case ``stdout`` is bytes.
+- validate-modules - do not raise an ``AttributeError`` if a value is assigned to a module attribute in a try/except block.
+
+v2.10.5
+=======
+
+Release Summary
+---------------
+
+| Release Date: 2021-01-18
+| `Porting Guide <https://docs.ansible.com/ansible/devel/porting_guides.html>`__
+
+
+Minor Changes
+-------------
+
+- ansible-test - Changed the internal name of the custom plugin used to identify use of unwanted imports and functions.
+- 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 - add macOS 11.1 as a remote target (https://github.com/ansible/ansible/pull/72622)
+- ansible-test - remote macOS instances no longer install ``virtualenv`` during provisioning
+- ansible-test - virtualenv helper scripts now prefer ``venv`` on Python 3 over ``virtualenv`` if the ``ANSIBLE_TEST_PREFER_VENV`` environment variable is set
+
+Bugfixes
+--------
+
+- Apply ``_wrap_native_text`` only for builtin filters specified in STRING_TYPE_FILTERS.
+- Documentation change to the apt module to reference lock files (https://github.com/ansible/ansible/issues/73079).
+- Fix --list-tasks format `role_name : task_name` when task name contains the role name. (https://github.com/ansible/ansible/issues/72505)
+- 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)
+- Fix notifying handlers via `role_name : handler_name` when handler name contains the role name. (https://github.com/ansible/ansible/issues/70582)
+- async - Fix Python 3 interpreter parsing from module by comparing with bytes (https://github.com/ansible/ansible/issues/70690)
+- inventory - pass the vars dictionary to combine_vars instead of an individual key's value (https://github.com/ansible/ansible/issues/72975).
+- paramiko connection plugin - Ensure we only reset the connection when one has been previously established (https://github.com/ansible/ansible/issues/65812)
+- systemd - preserve the full unit name when using a templated service and ``systemd`` failed to parse dbus due to a known bug in ``systemd`` (https://github.com/ansible/ansible/pull/72985)
+- user - do the right thing when ``password_lock=True`` and ``password`` are used together (https://github.com/ansible/ansible/issues/72992)
+
+v2.10.4
+=======
+
+Release Summary
+---------------
+
+| Release Date: 2020-12-14
+| `Porting Guide <https://docs.ansible.com/ansible/devel/porting_guides.html>`__
+
+
+Minor Changes
+-------------
+
+- ansible-doc - provide ``has_action`` field in JSON output for modules. That information is currently only available in the text view (https://github.com/ansible/ansible/pull/72359).
+- ansible-galaxy - find any collection dependencies in the globally configured Galaxy servers and not just the server the parent collection is from.
+- ansible-test - Added a ``--export`` option to the ``ansible-test coverage combine`` command to facilitate multi-stage aggregation of coverage in CI pipelines.
+- ansible-test - Added the ``-remote rhel/7.9`` option to run tests on RHEL 7.9
+- ansible-test - CentOS 8 container is now 8.2.2004 (https://github.com/ansible/distro-test-containers/pull/45).
+- ansible-test - Fix container hostname/IP discovery for the ``acme`` test plugin.
+- ansible-test - OpenSuse container now uses Leap 15.2 (https://github.com/ansible/distro-test-containers/pull/48).
+- 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 - ``default-test-container`` and ``ansible-base-test-container`` now use Python 3.9.0 instead of 3.9.0rc1.
+- ansible-test - centos6 end of life - container image updated to point to vault base repository (https://github.com/ansible/distro-test-containers/pull/54)
+- 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).
+- iptables - reorder comment postition to be at the end (https://github.com/ansible/ansible/issues/71444).
+
+Bugfixes
+--------
+
+- Adjust various hard-coded action names to also include their ``ansible.builtin.`` and ``ansible.legacy.`` prefixed version (https://github.com/ansible/ansible/issues/71817, https://github.com/ansible/ansible/issues/71818, https://github.com/ansible/ansible/pull/71824).
+- 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)
+- Fixed issue when `netstat` is either missing or doesn't have execution permissions leading to incorrect command being executed.
+- Improve Ansible config deprecations to show the source of the deprecation (ansible-base). Also remove space before a comma in config deprecations (https://github.com/ansible/ansible/pull/72697).
+- Skip invalid collection names when listing in ansible-doc instead of throwing exception. Issue#72257
+- The ``docker`` and ``k8s`` action groups / module default groups now also support the moved modules in `community.docker <https://galaxy.ansible.com/community/docker>`_, `community.kubevirt <https://github.com/ansible-collections/community.kubevirt>`_, `community.okd <https://galaxy.ansible.com/community/okd>`_, and `kubernetes.core <https://galaxy.ansible.com/kubernetes/core>`_ (https://github.com/ansible/ansible/pull/72428).
+- account for bug in Python 2.6 that occurs during interpreter shutdown to avoid stack trace
+- ansible-test - Correctly detect changes in a GitHub pull request when running on Azure Pipelines.
+- ansible-test - Skip installing requirements if they are already installed.
+- 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 - 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 validate-modules - when a module uses ``add_file_common_args=True`` and does not use a keyword argument for ``argument_spec`` in ``AnsibleModule()``, the common file arguments were not considered added during validation (https://github.com/ansible/ansible/pull/72334).
+- basic.AnsibleModule - AnsibleModule.run_command silently ignores a non-existent directory in the ``cwd`` argument (https://github.com/ansible/ansible/pull/72390).
+- blockinfile - properly insert a block at the end of a file that does not have a trailing newline character (https://github.com/ansible/ansible/issues/72055)
+- dnf - fix filtering to avoid dependncy conflicts (https://github.com/ansible/ansible/issues/72316)
+- ensure 'local' connection always has the correct default user for actions to consume.
+- pause - Fix indefinite hang when using a pause task on a background process (https://github.com/ansible/ansible/issues/32142)
+- 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.
+- set_mode_if_different - handle symlink if it is inside a directory with sticky bit set (https://github.com/ansible/ansible/pull/45198)
+- systemd - account for templated unit files using ``@`` when searching for the unit file (https://github.com/ansible/ansible/pull/72347#issuecomment-730626228)
+- 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.
+- systemd - work around bug with ``systemd`` 245 and 5.8 kernel that does not correctly report service state (https://github.com/ansible/ansible/issues/71528)
+- wait_for - catch and ignore errors when getting active connections with psutil (https://github.com/ansible/ansible/issues/72322)
+
 v2.10.3
 =======
 
@@ -242,7 +376,6 @@ Minor Changes
 - ansible-galaxy - Display message if both collections and roles are specified in a requirements file but can't be installed together.
 - ansible-galaxy - Install both collections and roles with ``ansible-galaxy install -r requirements.yml`` in certain scenarios.
 - ansible-galaxy - Requirement entries for collections now support a 'type' key to indicate whether the collection is a galaxy artifact, file, url, or git repo.
-- ansible-galaxy - Support both 'galaxy.yml' and 'galaxy.yaml' files for collections.
 - ansible-galaxy - add ``--token`` argument which is the same as ``--api-key`` (https://github.com/ansible/ansible/issues/65955)
 - ansible-galaxy - add ``collection list`` command for listing installed collections (https://github.com/ansible/ansible/pull/65022)
 - ansible-galaxy - add ``validate_collection_path()`` utility function ()

changelogs/changelog.yaml

@@ -802,7 +802,6 @@ releases:
       - ansible-galaxy - Requirement entries for collections now support a 'type'
         key to indicate whether the collection is a galaxy artifact, file, url, or
         git repo.
-      - ansible-galaxy - Support both 'galaxy.yml' and 'galaxy.yaml' files for collections.
       - ansible-galaxy - add ``--token`` argument which is the same as ``--api-key``
         (https://github.com/ansible/ansible/issues/65955)
       - ansible-galaxy - add ``collection list`` command for listing installed collections
@@ -2130,3 +2129,315 @@ releases:
     - url-lookup-ini.yml
     - v2.10.3rc1_summary.yaml
     release_date: '2020-10-26'
+  2.10.4:
+    changes:
+      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
+      release_summary: '| Release Date: 2020-12-14
+
+        | `Porting Guide <https://docs.ansible.com/ansible/devel/porting_guides.html>`__
+
+        '
+    codename: When the Levee Breaks
+    fragments:
+    - ansible-test-constraints-cryptography.yml
+    - v2.10.4_summary.yaml
+    release_date: '2020-12-14'
+  2.10.4rc1:
+    changes:
+      bugfixes:
+      - Adjust various hard-coded action names to also include their ``ansible.builtin.``
+        and ``ansible.legacy.`` prefixed version (https://github.com/ansible/ansible/issues/71817,
+        https://github.com/ansible/ansible/issues/71818, https://github.com/ansible/ansible/pull/71824).
+      - 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)
+      - Fixed issue when `netstat` is either missing or doesn't have execution permissions
+        leading to incorrect command being executed.
+      - Improve Ansible config deprecations to show the source of the deprecation
+        (ansible-base). Also remove space before a comma in config deprecations (https://github.com/ansible/ansible/pull/72697).
+      - Skip invalid collection names when listing in ansible-doc instead of throwing
+        exception. Issue#72257
+      - The ``docker`` and ``k8s`` action groups / module default groups now also
+        support the moved modules in `community.docker <https://galaxy.ansible.com/community/docker>`_,
+        `community.kubevirt <https://github.com/ansible-collections/community.kubevirt>`_,
+        `community.okd <https://galaxy.ansible.com/community/okd>`_, and `kubernetes.core
+        <https://galaxy.ansible.com/kubernetes/core>`_ (https://github.com/ansible/ansible/pull/72428).
+      - account for bug in Python 2.6 that occurs during interpreter shutdown to avoid
+        stack trace
+      - ansible-test - Correctly detect changes in a GitHub pull request when running
+        on Azure Pipelines.
+      - ansible-test - Skip installing requirements if they are already installed.
+      - '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 - 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 validate-modules - when a module uses ``add_file_common_args=True``
+        and does not use a keyword argument for ``argument_spec`` in ``AnsibleModule()``,
+        the common file arguments were not considered added during validation (https://github.com/ansible/ansible/pull/72334).
+      - basic.AnsibleModule - AnsibleModule.run_command silently ignores a non-existent
+        directory in the ``cwd`` argument (https://github.com/ansible/ansible/pull/72390).
+      - 'blockinfile - properly insert a block at the end of a file that does not
+        have a trailing newline character (https://github.com/ansible/ansible/issues/72055)
+
+        '
+      - dnf - fix filtering to avoid dependncy conflicts (https://github.com/ansible/ansible/issues/72316)
+      - ensure 'local' connection always has the correct default user for actions
+        to consume.
+      - 'pause - Fix indefinite hang when using a pause task on a background process
+        (https://github.com/ansible/ansible/issues/32142)
+
+        '
+      - 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.
+      - 'set_mode_if_different - handle symlink if it is inside a directory with sticky
+        bit set (https://github.com/ansible/ansible/pull/45198)
+
+        '
+      - 'systemd - account for templated unit files using ``@`` when searching for
+        the unit file (https://github.com/ansible/ansible/pull/72347#issuecomment-730626228)
+
+        '
+      - '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.
+
+        '
+      - 'systemd - work around bug with ``systemd`` 245 and 5.8 kernel that does not
+        correctly report service state (https://github.com/ansible/ansible/issues/71528)
+
+        '
+      - wait_for - catch and ignore errors when getting active connections with psutil
+        (https://github.com/ansible/ansible/issues/72322)
+      minor_changes:
+      - ansible-doc - provide ``has_action`` field in JSON output for modules. That
+        information is currently only available in the text view (https://github.com/ansible/ansible/pull/72359).
+      - 'ansible-galaxy - find any collection dependencies in the globally configured
+        Galaxy servers and not just the server the parent collection is from.
+
+        '
+      - ansible-test - Added a ``--export`` option to the ``ansible-test coverage
+        combine`` command to facilitate multi-stage aggregation of coverage in CI
+        pipelines.
+      - ansible-test - Added the ``-remote rhel/7.9`` option to run tests on RHEL
+        7.9
+      - ansible-test - CentOS 8 container is now 8.2.2004 (https://github.com/ansible/distro-test-containers/pull/45).
+      - ansible-test - Fix container hostname/IP discovery for the ``acme`` test plugin.
+      - ansible-test - OpenSuse container now uses Leap 15.2 (https://github.com/ansible/distro-test-containers/pull/48).
+      - 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 - ``default-test-container`` and ``ansible-base-test-container``
+        now use Python 3.9.0 instead of 3.9.0rc1.
+      - ansible-test - centos6 end of life - container image updated to point to vault
+        base repository (https://github.com/ansible/distro-test-containers/pull/54)
+      - 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).
+      - iptables - reorder comment postition to be at the end (https://github.com/ansible/ansible/issues/71444).
+      release_summary: '| Release Date: 2020-12-07
+
+        | `Porting Guide <https://docs.ansible.com/ansible/devel/porting_guides.html>`__
+
+        '
+    codename: When the Levee Breaks
+    fragments:
+    - 32143-pause-background-hangs.yml
+    - 71496-iptables-reorder-comment-position.yml
+    - 71528-systemd-capbpf-workaround.yml
+    - 71528-systemd-improve-unit-searching.yml
+    - 71528-systemd-list-unit-files.yml
+    - 71824-action-fqcns.yml
+    - 72055-blockinfile-fix-insert-after-line-no-linesep.yml
+    - 72316-dnf-filtering.yml
+    - 72322-wait-for-handle-errors.yml
+    - 72390-return-error-if-cwd-directory-does-not-exist.yml
+    - 72428-action-groups-docker-k8s.yml
+    - 72516-fix-aix-network-facts.yml
+    - 72623-ansible-test-unicode-paths.yml
+    - 72697-improve-config-deprecations.yml
+    - 72699-validate-modules-default-for-bools.yml
+    - ansible-base-update-containers.yml
+    - ansible-doc-has_action.yml
+    - ansible-test-acme-test-plugin.yml
+    - ansible-test-azp-change-detection.yml
+    - ansible-test-centos6-eol.yml
+    - ansible-test-collection-classification.yml
+    - ansible-test-coverage-combine-export.yml
+    - ansible-test-validate-modules-file-common-args.yml
+    - cffi-constraint.yml
+    - ensure_local_user_correctness.yml
+    - galaxy-servers.yml
+    - play_context_remove_redundant_pwd.yml
+    - ps-sanity-requirements.yml
+    - py26-multiprocess-queue-bug.yml
+    - rhel-7.9.yml
+    - run-command-cwd.yml
+    - set_mode_if_different-symlink-sticky-dir.yml
+    - skip_invalid_coll_name_when_listing.yml
+    - v2.10.4rc1_summary.yaml
+    release_date: '2020-12-07'
+  2.10.5:
+    changes:
+      release_summary: '| Release Date: 2021-01-18
+
+        | `Porting Guide <https://docs.ansible.com/ansible/devel/porting_guides.html>`__
+
+        '
+    codename: When the Levee Breaks
+    fragments:
+    - v2.10.5_summary.yaml
+    release_date: '2021-01-18'
+  2.10.5rc1:
+    changes:
+      bugfixes:
+      - Apply ``_wrap_native_text`` only for builtin filters specified in STRING_TYPE_FILTERS.
+      - Documentation change to the apt module to reference lock files (https://github.com/ansible/ansible/issues/73079).
+      - 'Fix --list-tasks format `role_name : task_name` when task name contains the
+        role name. (https://github.com/ansible/ansible/issues/72505)'
+      - 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)
+      - 'Fix notifying handlers via `role_name : handler_name` when handler name contains
+        the role name. (https://github.com/ansible/ansible/issues/70582)'
+      - async - Fix Python 3 interpreter parsing from module by comparing with bytes
+        (https://github.com/ansible/ansible/issues/70690)
+      - inventory - pass the vars dictionary to combine_vars instead of an individual
+        key's value (https://github.com/ansible/ansible/issues/72975).
+      - paramiko connection plugin - Ensure we only reset the connection when one
+        has been previously established (https://github.com/ansible/ansible/issues/65812)
+      - 'systemd - preserve the full unit name when using a templated service and
+        ``systemd`` failed to parse dbus due to a known bug in ``systemd`` (https://github.com/ansible/ansible/pull/72985)
+
+        '
+      - 'user - do the right thing when ``password_lock=True`` and ``password`` are
+        used together (https://github.com/ansible/ansible/issues/72992)
+
+        '
+      minor_changes:
+      - ansible-test - Changed the internal name of the custom plugin used to identify
+        use of unwanted imports and functions.
+      - 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 - add macOS 11.1 as a remote target (https://github.com/ansible/ansible/pull/72622)
+      - ansible-test - remote macOS instances no longer install ``virtualenv`` during
+        provisioning
+      - ansible-test - virtualenv helper scripts now prefer ``venv`` on Python 3 over
+        ``virtualenv`` if the ``ANSIBLE_TEST_PREFER_VENV`` environment variable is
+        set
+      release_summary: '| Release Date: 2021-01-11
+
+        | `Porting Guide <https://docs.ansible.com/ansible/devel/porting_guides.html>`__
+
+        '
+    codename: When the Levee Breaks
+    fragments:
+    - 65812-paramiko-attribute-error.yml
+    - 70244-selinux-special-fs.yml
+    - 70690-async-interpreter.yml
+    - 72511-always-prepend-role-to-task-name.yml
+    - 72979-fix-inventory-merge-hash-replace.yaml
+    - 72992-user-account-lock-always-changes.yml
+    - 73079-update-documentation-around-apt-lock.yml
+    - ansible-test-pylint-plugin-name.yml
+    - ansible-test-pylint-python-3.8-3.9.yml
+    - ansible-test-venv-virtualenv-fallback.yml
+    - ci-add-macos-11.yml
+    - collection-list-site-packages.yaml
+    - systemd-preserve-full-unit-name.yml
+    - v2.10.5rc1_summary.yaml
+    - wrap_native_text-non-collections-only.yml
+    release_date: '2021-01-11'
+  2.10.6:
+    changes:
+      release_summary: '| Release Date: 2021-02-17
+
+        | `Porting Guide <https://docs.ansible.com/ansible/devel/porting_guides.html>`__
+
+        '
+    codename: When the Levee Breaks
+    fragments:
+    - v2.10.6_summary.yaml
+    release_date: '2021-02-17'
+  2.10.6rc1:
+    changes:
+      bugfixes:
+      - Added unsafe_writes test.
+      - Always mention the name of the deprecated or tombstoned plugin in routing
+        deprecation/tombstone messages (https://github.com/ansible/ansible/pull/73059).
+      - Correct the inventory source error parse handling, specifically make the config
+        INVENTORY_ANY_UNPARSED_IS_FAILED work as expected.
+      - Enabled unsafe_writes for get_url which was ignoring the paramter.
+      - Fix incorrect variable scoping when using ``import with context`` in Jinja2
+        templates. (https://github.com/ansible/ansible/issues/72615)
+      - Restored unsafe_writes functionality which was being skipped.
+      - allow become method 'su' to work on 'local' connection by allocating a fake
+        tty.
+      - ansble-test - only require a collection name in deprecation warnings when
+        necessary (https://github.com/ansible/ansible/pull/72987)
+      - ansible-test - Temporarily limit ``cryptography`` to versions before 3.4 to
+        enable tests to function.
+      - 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 sanity changelog test - bump dependency on antsibull-changelog
+        to 0.9.0 so that `fragments that add new plugins or objects <https://github.com/ansible-community/antsibull-changelog/blob/main/docs/changelogs.rst#adding-new-roles-playbooks-test-and-filter-plugins>`_
+        will not fail validation (https://github.com/ansible/ansible/pull/73428).
+      - display correct error information when an error exists in the last line of
+        the file (https://github.com/ansible/ansible/issues/16456)
+      - facts - properly report virtualization facts for Linux guests running on bhyve
+        (https://github.com/ansible/ansible/issues/73167)
+      - git - Only pass ``--raw`` flag to git verify commands (verify-tag, verify-commit)
+        when ``gpg_whitelist`` is in use. Otherwise don't pass it so that non-whitelist
+        GPG validation still works on older Git versions. (https://github.com/ansible/ansible/issues/64469)
+      - import_playbook - change warning about extra parameters to deprecation (https://github.com/ansible/ansible/issues/72745)
+      - pause - do not warn when running in the background if a timeout is provided
+        (https://github.com/ansible/ansible/issues/73042)
+      - psrp connection plugin - ``to_text(stdout)`` before ``json.loads`` in psrp.Connection.put_file
+        in case ``stdout`` is bytes.
+      - validate-modules - do not raise an ``AttributeError`` if a value is assigned
+        to a module attribute in a try/except block.
+      minor_changes:
+      - ansible-test - Added Ubuntu 20.04 LTS image to the default completion list
+      - inventory cache - do not show a warning when the cache file does not (yet)
+        exist.
+      release_summary: '| Release Date: 2021-02-08
+
+        | `Porting Guide <https://docs.ansible.com/ansible/devel/porting_guides.html>`__
+
+        '
+      security_fixes:
+      - '**security issue** - Mask default and fallback values for ``no_log`` module
+        options (CVE-2021-20228)'
+    codename: When the Levee Breaks
+    fragments:
+    - 16456-correct-YAML-error-message-when-file-load-failed.yml
+    - 64469_git_no_raw.yml
+    - 72615-jinja-import-context-fix.yml
+    - 72745-import_playbook-deprecation-extra-params.yml
+    - 73059-improve-deprecation-texts.yml
+    - 73167-bhyve-facts.yml
+    - 73428-changelog-linting-bump-version.yml
+    - ansible-test-pip-bootstrap-s3.yml
+    - ansible-test-pip-bootstrap.yml
+    - ansible-test-sanity-deprecation-collection-name.yml
+    - ansible-test-ubuntu2004.yml
+    - cryptography-fix.yml
+    - enable_su_on_local.yaml
+    - fix_inventory_source_parse_error_handling.yml
+    - inventory-cache-file-missing-warning.yaml
+    - no_log-fallback.yml
+    - pause-do-not-warn-background-with-seconds.yml
+    - psrp-json-loads-bytes.yml
+    - unsafe_writes_fix.yml
+    - v2.10.6rc1_summary.yaml
+    - validate-modules_found_try_except_import_fails_module_attribute.yaml
+    release_date: '2021-02-08'

changelogs/fragments/16456-correct-YAML-error-message-when-file-load-failed.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - display correct error information when an error exists in the last line of the file (https://github.com/ansible/ansible/issues/16456)

changelogs/fragments/32143-pause-background-hangs.yml

@@ -0,0 +1,4 @@
+bugfixes:
+  - >
+    pause - Fix indefinite hang when using a pause task on a background
+    process (https://github.com/ansible/ansible/issues/32142)

changelogs/fragments/64469_git_no_raw.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - git - Only pass ``--raw`` flag to git verify commands (verify-tag, verify-commit) when ``gpg_whitelist`` is in use. Otherwise don't pass it so that non-whitelist GPG validation still works on older Git versions. (https://github.com/ansible/ansible/issues/64469)

changelogs/fragments/65812-paramiko-attribute-error.yml

@@ -0,0 +1,3 @@
+bugfixes:
+- paramiko connection plugin - Ensure we only reset the connection when one has been
+  previously established (https://github.com/ansible/ansible/issues/65812)

changelogs/fragments/69154-install-collection-from-git-repo.yml

@@ -1,4 +1,3 @@
 minor_changes:
   - ansible-galaxy - Allow installing collections from git repositories.
   - ansible-galaxy - Requirement entries for collections now support a 'type' key to indicate whether the collection is a galaxy artifact, file, url, or git repo.
-  - ansible-galaxy - Support both 'galaxy.yml' and 'galaxy.yaml' files for collections.

changelogs/fragments/70244-selinux-special-fs.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - 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)

changelogs/fragments/70690-async-interpreter.yml

@@ -0,0 +1,3 @@
+bugfixes:
+- async - Fix Python 3 interpreter parsing from module by comparing with bytes
+  (https://github.com/ansible/ansible/issues/70690)

changelogs/fragments/71496-iptables-reorder-comment-position.yml

@@ -0,0 +1,2 @@
+minor_changes:
+  - iptables - reorder comment postition to be at the end (https://github.com/ansible/ansible/issues/71444).

changelogs/fragments/71528-systemd-capbpf-workaround.yml

@@ -0,0 +1,4 @@
+bugfixes:
+  - >
+    systemd - work around bug with ``systemd`` 245 and 5.8 kernel that does not correctly
+    report service state (https://github.com/ansible/ansible/issues/71528)

changelogs/fragments/71528-systemd-improve-unit-searching.yml

@@ -0,0 +1,4 @@
+bugfixes:
+  - >
+    systemd - account for templated unit files using ``@`` when searching for
+    the unit file (https://github.com/ansible/ansible/pull/72347#issuecomment-730626228)

changelogs/fragments/71528-systemd-list-unit-files.yml

@@ -0,0 +1,5 @@
+bugfixes:
+  - >
+    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.

changelogs/fragments/71824-action-fqcns.yml

@@ -0,0 +1,2 @@
+bugfixes:
+- "Adjust various hard-coded action names to also include their ``ansible.builtin.`` and ``ansible.legacy.`` prefixed version (https://github.com/ansible/ansible/issues/71817, https://github.com/ansible/ansible/issues/71818, https://github.com/ansible/ansible/pull/71824)."

changelogs/fragments/72055-blockinfile-fix-insert-after-line-no-linesep.yml

@@ -0,0 +1,4 @@
+bugfixes:
+  - >
+    blockinfile - properly insert a block at the end of a file that does not
+    have a trailing newline character (https://github.com/ansible/ansible/issues/72055)

changelogs/fragments/72316-dnf-filtering.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - dnf - fix filtering to avoid dependncy conflicts (https://github.com/ansible/ansible/issues/72316)

changelogs/fragments/72322-wait-for-handle-errors.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - wait_for - catch and ignore errors when getting active connections with psutil (https://github.com/ansible/ansible/issues/72322)

changelogs/fragments/72390-return-error-if-cwd-directory-does-not-exist.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - basic.AnsibleModule - AnsibleModule.run_command silently ignores a non-existent directory in the ``cwd`` argument (https://github.com/ansible/ansible/pull/72390).

changelogs/fragments/72428-action-groups-docker-k8s.yml

@@ -0,0 +1,2 @@
+bugfixes:
+- "The ``docker`` and ``k8s`` action groups / module default groups now also support the moved modules in `community.docker <https://galaxy.ansible.com/community/docker>`_, `community.kubevirt <https://github.com/ansible-collections/community.kubevirt>`_, `community.okd <https://galaxy.ansible.com/community/okd>`_, and `kubernetes.core <https://galaxy.ansible.com/kubernetes/core>`_ (https://github.com/ansible/ansible/pull/72428)."

changelogs/fragments/72511-always-prepend-role-to-task-name.yml

@@ -0,0 +1,3 @@
+bugfixes:
+  - 'Fix notifying handlers via `role_name : handler_name` when handler name contains the role name. (https://github.com/ansible/ansible/issues/70582)'
+  - 'Fix --list-tasks format `role_name : task_name` when task name contains the role name. (https://github.com/ansible/ansible/issues/72505)'

changelogs/fragments/72516-fix-aix-network-facts.yml

@@ -0,0 +1,2 @@
+bugfixes:
+    - Fixed issue when `netstat` is either missing or doesn't have execution permissions leading to incorrect command being executed. 

changelogs/fragments/72615-jinja-import-context-fix.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - Fix incorrect variable scoping when using ``import with context`` in Jinja2 templates. (https://github.com/ansible/ansible/issues/72615)

changelogs/fragments/72623-ansible-test-unicode-paths.yml

@@ -0,0 +1,2 @@
+bugfixes:
+- "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)."

changelogs/fragments/72697-improve-config-deprecations.yml

@@ -0,0 +1,2 @@
+bugfixes:
+- "Improve Ansible config deprecations to show the source of the deprecation (ansible-base). Also remove space before a comma in config deprecations (https://github.com/ansible/ansible/pull/72697)."

changelogs/fragments/72699-validate-modules-default-for-bools.yml

@@ -0,0 +1,2 @@
+minor_changes:
+- "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)."

changelogs/fragments/72745-import_playbook-deprecation-extra-params.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - import_playbook - change warning about extra parameters to deprecation (https://github.com/ansible/ansible/issues/72745)

changelogs/fragments/72979-fix-inventory-merge-hash-replace.yaml

@@ -0,0 +1,2 @@
+bugfixes:
+  - inventory - pass the vars dictionary to combine_vars instead of an individual key's value (https://github.com/ansible/ansible/issues/72975).

changelogs/fragments/72992-user-account-lock-always-changes.yml

@@ -0,0 +1,4 @@
+bugfixes:
+  - >
+    user - do the right thing when ``password_lock=True`` and ``password``
+    are used together (https://github.com/ansible/ansible/issues/72992)

changelogs/fragments/73059-improve-deprecation-texts.yml

@@ -0,0 +1,2 @@
+bugfixes:
+- "Always mention the name of the deprecated or tombstoned plugin in routing deprecation/tombstone messages (https://github.com/ansible/ansible/pull/73059)."

changelogs/fragments/73079-update-documentation-around-apt-lock.yml

@@ -0,0 +1,2 @@
+bugfixes:
+- "Documentation change to the apt module to reference lock files (https://github.com/ansible/ansible/issues/73079)."

changelogs/fragments/73167-bhyve-facts.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - facts - properly report virtualization facts for Linux guests running on bhyve (https://github.com/ansible/ansible/issues/73167)

changelogs/fragments/73428-changelog-linting-bump-version.yml

@@ -0,0 +1,2 @@
+bugfixes:
+- "ansible-test sanity changelog test - bump dependency on antsibull-changelog to 0.9.0 so that `fragments that add new plugins or objects <https://github.com/ansible-community/antsibull-changelog/blob/main/docs/changelogs.rst#adding-new-roles-playbooks-test-and-filter-plugins>`_ will not fail validation (https://github.com/ansible/ansible/pull/73428)."

changelogs/fragments/ansible-base-update-containers.yml

@@ -0,0 +1,5 @@
+minor_changes:
+  - ansible-test - OpenSuse container now uses Leap 15.2 (https://github.com/ansible/distro-test-containers/pull/48).
+  - 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 - CentOS 8 container is now 8.2.2004 (https://github.com/ansible/distro-test-containers/pull/45).
+  - ansible-test - ``default-test-container`` and ``ansible-base-test-container`` now use Python 3.9.0 instead of 3.9.0rc1.

changelogs/fragments/ansible-doc-has_action.yml

@@ -0,0 +1,2 @@
+minor_changes:
+- "ansible-doc - provide ``has_action`` field in JSON output for modules. That information is currently only available in the text view (https://github.com/ansible/ansible/pull/72359)."

changelogs/fragments/ansible-test-acme-test-plugin.yml

@@ -0,0 +1,2 @@
+minor_changes:
+  - ansible-test - Fix container hostname/IP discovery for the ``acme`` test plugin.

changelogs/fragments/ansible-test-azp-change-detection.yml

@@ -0,0 +1,2 @@
+bugfixes:
+    - ansible-test - Correctly detect changes in a GitHub pull request when running on Azure Pipelines.

changelogs/fragments/ansible-test-centos6-eol.yml

@@ -0,0 +1,2 @@
+minor_changes:
+  - ansible-test - centos6 end of life - container image updated to point to vault base repository (https://github.com/ansible/distro-test-containers/pull/54)

changelogs/fragments/ansible-test-collection-classification.yml

@@ -0,0 +1,2 @@
+bugfixes:
+- "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)."

changelogs/fragments/ansible-test-constraints-cryptography.yml

@@ -0,0 +1,2 @@
+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

changelogs/fragments/ansible-test-coverage-combine-export.yml

@@ -0,0 +1,2 @@
+minor_changes:
+  - ansible-test - Added a ``--export`` option to the ``ansible-test coverage combine`` command to facilitate multi-stage aggregation of coverage in CI pipelines.

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

@@ -0,0 +1,2 @@
+bugfixes:
+  - ansible-test - The ``--remote`` option has been updated to use a versioned ``get-pip.py`` bootstrapper to avoid issues with future releases.

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

@@ -0,0 +1,2 @@
+bugfixes:
+  - 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.

changelogs/fragments/ansible-test-pylint-plugin-name.yml

@@ -0,0 +1,2 @@
+minor_changes:
+  - ansible-test - Changed the internal name of the custom plugin used to identify use of unwanted imports and functions.

changelogs/fragments/ansible-test-pylint-python-3.8-3.9.yml

@@ -0,0 +1,3 @@
+minor_changes:
+  - ansible-test - The ``pylint`` sanity test is now supported on Python 3.8.
+  - ansible-test - The ``pylint`` sanity test is now skipped with a warning on Python 3.9 due to unresolved upstream regressions.

changelogs/fragments/ansible-test-sanity-deprecation-collection-name.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - ansble-test - only require a collection name in deprecation warnings when necessary (https://github.com/ansible/ansible/pull/72987)

changelogs/fragments/ansible-test-ubuntu2004.yml

@@ -0,0 +1,2 @@
+minor_changes:
+  - ansible-test - Added Ubuntu 20.04 LTS image to the default completion list

changelogs/fragments/ansible-test-validate-modules-file-common-args.yml

@@ -0,0 +1,2 @@
+bugfixes:
+- "ansible-test validate-modules - when a module uses ``add_file_common_args=True`` and does not use a keyword argument for ``argument_spec`` in ``AnsibleModule()``, the common file arguments were not considered added during validation (https://github.com/ansible/ansible/pull/72334)."

changelogs/fragments/ansible-test-venv-virtualenv-fallback.yml

@@ -0,0 +1,3 @@
+minor_changes:
+  - ansible-test - virtualenv helper scripts now prefer ``venv`` on Python 3 over ``virtualenv`` if the ``ANSIBLE_TEST_PREFER_VENV`` environment variable is set
+  - ansible-test - remote macOS instances no longer install ``virtualenv`` during provisioning

changelogs/fragments/cffi-constraint.yml

@@ -0,0 +1,4 @@
+bugfixes:
+  - >
+    ansible-test - add constraint for ``cffi`` to prevent failure on systems with
+    older versions of ``gcc`` (https://foss.heptapod.net/pypy/cffi/-/issues/480)

changelogs/fragments/ci-add-macos-11.yml

@@ -0,0 +1,2 @@
+minor_changes:
+  - ansible-test - add macOS 11.1 as a remote target (https://github.com/ansible/ansible/pull/72622)

changelogs/fragments/collection-list-site-packages.yaml

@@ -0,0 +1,3 @@
+bugfixes:
+- Fix ansible-galaxy collection list to show collections in site-packages
+  (https://github.com/ansible/ansible/issues/70147)

changelogs/fragments/cryptography-fix.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - ansible-test - Temporarily limit ``cryptography`` to versions before 3.4 to enable tests to function.

changelogs/fragments/enable_su_on_local.yaml

@@ -0,0 +1,2 @@
+bugfixes:
+    - allow become method 'su' to work on 'local' connection by allocating a fake tty.

changelogs/fragments/ensure_local_user_correctness.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - ensure 'local' connection always has the correct default user for actions to consume.

changelogs/fragments/fix_inventory_source_parse_error_handling.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - Correct the inventory source error parse handling, specifically make the config INVENTORY_ANY_UNPARSED_IS_FAILED work as expected.

changelogs/fragments/galaxy-servers.yml

@@ -0,0 +1,4 @@
+minor_changes:
+- >
+  ansible-galaxy - find any collection dependencies in the globally configured Galaxy servers and not just the server
+  the parent collection is from.

changelogs/fragments/inventory-cache-file-missing-warning.yaml

@@ -0,0 +1,2 @@
+minor_changes:
+  - inventory cache - do not show a warning when the cache file does not (yet) exist.

changelogs/fragments/no_log-fallback.yml

@@ -0,0 +1,2 @@
+security_fixes:
+  - '**security issue** - Mask default and fallback values for ``no_log`` module options (CVE-2021-20228)'

changelogs/fragments/pause-do-not-warn-background-with-seconds.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - pause - do not warn when running in the background if a timeout is provided (https://github.com/ansible/ansible/issues/73042)

changelogs/fragments/play_context_remove_redundant_pwd.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - 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.

changelogs/fragments/ps-sanity-requirements.yml

@@ -0,0 +1,2 @@
+bugfixes:
+- ansible-test - Skip installing requirements if they are already installed.

changelogs/fragments/psrp-json-loads-bytes.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - psrp connection plugin - ``to_text(stdout)`` before ``json.loads`` in psrp.Connection.put_file in case ``stdout`` is bytes.

changelogs/fragments/py26-multiprocess-queue-bug.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - account for bug in Python 2.6 that occurs during interpreter shutdown to avoid stack trace

changelogs/fragments/rhel-7.9.yml

@@ -0,0 +1,2 @@
+minor_changes:
+- ansible-test - Added the ``-remote rhel/7.9`` option to run tests on RHEL 7.9

changelogs/fragments/run-command-cwd.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - 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)

changelogs/fragments/set_mode_if_different-symlink-sticky-dir.yml

@@ -0,0 +1,4 @@
+bugfixes:
+  - >
+    set_mode_if_different - handle symlink if it is inside a directory with
+    sticky bit set (https://github.com/ansible/ansible/pull/45198)

changelogs/fragments/skip_invalid_coll_name_when_listing.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - Skip invalid collection names when listing in ansible-doc instead of throwing exception. Issue#72257

changelogs/fragments/systemd-preserve-full-unit-name.yml

@@ -0,0 +1,4 @@
+bugfixes:
+  - >
+    systemd - preserve the full unit name when using a templated service and
+    ``systemd`` failed to parse dbus due to a known bug in ``systemd`` (https://github.com/ansible/ansible/pull/72985)

changelogs/fragments/unsafe_writes_fix.yml

@@ -0,0 +1,4 @@
+bugfixes:
+  - Restored unsafe_writes functionality which was being skipped.
+  - Added unsafe_writes test.
+  - Enabled unsafe_writes for get_url which was ignoring the paramter.

changelogs/fragments/v2.10.4_summary.yaml

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

changelogs/fragments/v2.10.4rc1_summary.yaml

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

changelogs/fragments/v2.10.5_summary.yaml

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

changelogs/fragments/v2.10.5rc1_summary.yaml

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

changelogs/fragments/v2.10.6_summary.yaml

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

changelogs/fragments/v2.10.6rc1_summary.yaml

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

changelogs/fragments/validate-modules_found_try_except_import_fails_module_attribute.yaml

@@ -0,0 +1,3 @@
+---
+bugfixes:
+- validate-modules - do not raise an ``AttributeError`` if a value is assigned to a module attribute in a try/except block.

changelogs/fragments/wrap_native_text-non-collections-only.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - Apply ``_wrap_native_text`` only for builtin filters specified in STRING_TYPE_FILTERS.

docs/docsite/Makefile

@@ -94,7 +94,11 @@ clean:
 	rm -f rst/reference_appendices/playbooks_keywords.rst
 	rm -f rst/dev_guide/collections_galaxy_meta.rst
 	rm -f rst/cli/*.rst
-	rm -rf rst/collections/*
+	for filename in `ls rst/collections/` ; do \
+		if test x"$$filename" != x'all_plugins.rst' ; then \
+			rm -rf "rst/collections/$$filename"; \
+		fi \
+	done
 	@echo "Cleaning up legacy generated rst locations"
 	rm -rf rst/modules
 	rm -f rst/plugins/*/*.rst

docs/docsite/_themes/sphinx_rtd_theme/ansible_banner.html

@@ -10,19 +10,27 @@
       document.write('</div>');
     }
     {% if (not READTHEDOCS) and (available_versions is defined) %}
-      // Create a banner if we're not the latest version
+      // Create a banner
       current_url_path = window.location.pathname;
       if (startsWith(current_url_path, "/ansible/latest/") || startsWith(current_url_path, "/ansible/{{ latest_version }}/")) {
-       // no banner for latest release
-       /* temp banner to advertise AnsibleFest
+        document.write('<div id="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>');
+      } else if (startsWith(current_url_path, "/ansible/devel/")) {
+        /* temp banner to advertise survey
         document.write('<div id="banner_id" class="admonition important">');
-        document.write('<p><a href="https://www.ansible.com/ansiblefest?sc_cid=7013a000002gyPxAAI">AnsibleFest</a> is going virtual with two days of expert speakers, live demos and hands-on labs Oct 13-14!</p>');
+        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>'); */
 
-      } else if (startsWith(current_url_path, "/ansible/devel/")) {
         document.write('<div id="banner_id" class="admonition caution">');
-        document.write('<p>You are reading the *devel* 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('<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('<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>');

docs/docsite/rst/collections/all_plugins.rst

@@ -0,0 +1,11 @@
+.. _all_modules_and_plugins:
+
+Indexes of all modules and plugins
+----------------------------------
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Plugin indexes
+   :glob:
+
+   index_*

docs/docsite/rst/dev_guide/developing_collections.rst

@@ -536,19 +536,30 @@ First, look at `Ansible Collection Checklist <https://github.com/ansible-collect
 
 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 collection.
-#. Deprecate the module/plugin with ``removal_version`` scheduled for the next major version in ``meta/runtime.yml`` of the source collection. The deprecation must be released after the copied content has been included in a release of the target collection.
-#. When the next major release comes:
+#. 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 source collection
-  * add ``redirect`` to the corresponding entry in ``meta/runtime.yml``
-  * remove ``removal_version`` from there
+  * 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 target collection to copy the content.
-#. Deprecate the module/plugin in the source collection.
-#. Later create a PR against the source collection to remove the content according to the schedule.
+#. 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

docs/docsite/rst/dev_guide/developing_modules_documenting.rst

@@ -114,7 +114,8 @@ All fields in the ``DOCUMENTATION`` block are lower-case. All fields are require
 :version_added:
 
   * The version of Ansible when the module was added.
-  * This is a string, and not a float, for example, ``version_added: '2.1'``
+  * This is a string, and not a float, for example, ``version_added: '2.1'``.
+  * In collections, this must be the collection version the module was added to, not the Ansible version. For example, ``version_added: 1.0.0``.
 
 :author:
 
@@ -182,6 +183,7 @@ All fields in the ``DOCUMENTATION`` block are lower-case. All fields are require
 
     * Only needed if this option was extended after initial Ansible release, in other words, this is greater than the top level `version_added` field.
     * This is a string, and not a float, for example, ``version_added: '2.3'``.
+    * In collections, this must be the collection version the option was added to, not the Ansible version. For example, ``version_added: 1.0.0``.
 
   :suboptions:
 
@@ -241,7 +243,7 @@ content in a uniform way:
 
 * ``I()`` for option names. For example: ``Required if I(state=present).``  This is italicized in
   the documentation.
-* ``C()`` for files and option values. For example: ``If not set the environment variable C(ACME_PASSWORD) will be used.``  This displays with a mono-space font in the documentation.
+* ``C()`` for files, option values, and inline code. For example: ``If not set the environment variable C(ACME_PASSWORD) will be used.`` or ``Use C(var | foo.bar.my_filter) to transform C(var) into the required format.``  This displays with a mono-space font in the documentation.
 * ``B()`` currently has no standardized usage.  It is displayed in boldface in the documentation.
 * ``HORIZONTALLINE`` is used sparingly as a separator in long descriptions.  It becomes a horizontal rule (the ``<hr>`` html tag) in the documentation.
 
@@ -372,7 +374,7 @@ Otherwise, for each value returned, provide the following fields. All fields are
     Only needed if this return was extended after initial Ansible release, in other words, this is greater than the top level `version_added` field.
     This is a string, and not a float, for example, ``version_added: '2.3'``.
   :contains:
-    Optional. To describe nested return values, set ``type: complex``, ``type: dict``, or ``type: list``/``elements: dict`` and repeat the elements above for each sub-field.
+    Optional. To describe nested return values, set ``type: dict``, or ``type: list``/``elements: dict``, or if you really have to, ``type: complex``, and repeat the elements above for each sub-field.
 
 Here are two example ``RETURN`` sections, one with three simple fields and one with a complex nested field::
 
@@ -398,12 +400,13 @@ Here are two example ``RETURN`` sections, one with three simple fields and one w
     packages:
         description: Information about package requirements.
         returned: success
-        type: complex
+        type: dict
         contains:
             missing:
                 description: Packages that are missing from the system.
                 returned: success
                 type: list
+                elements: str
                 sample:
                     - libmysqlclient-dev
                     - libxml2-dev
@@ -411,6 +414,7 @@ Here are two example ``RETURN`` sections, one with three simple fields and one w
                 description: Packages that are installed but at bad versions.
                 returned: success
                 type: list
+                elements: dict
                 sample:
                     - package: libxml2-dev
                       version: 2.9.4+dfsg1-2

docs/docsite/rst/dev_guide/developing_modules_general.rst

@@ -75,7 +75,7 @@ To create an info module:
 
 1. Navigate to the correct directory for your new module: ``$ cd lib/ansible/modules/``. If you are developing module using collection, ``$ cd plugins/modules/`` inside your collection development tree.
 2. Create your new module file: ``$ touch my_test_info.py``.
-3. Paste the content below into your new info module file. It includes the :ref:`required Ansible format and documentation <developing_modules_documenting>` and some example code.
+3. Paste the content below into your new info module file. It includes the :ref:`required Ansible format and documentation <developing_modules_documenting>`, a simple :ref:`argument spec for declaring the module options <argument_spec>`, and some example code.
 4. Modify and extend the code to do what you want your new info module to do. See the :ref:`programming tips <developing_modules_best_practices>` and :ref:`Python 3 compatibility <developing_python_3>` pages for pointers on writing clean and concise module code.
 
 .. literalinclude:: ../../../../examples/scripts/my_test_info.py
@@ -93,8 +93,8 @@ To create a new module:
 
 1. Navigate to the correct directory for your new module: ``$ cd lib/ansible/modules/``. If you are developing a module in a :ref:`collection <developing_collections>`, ``$ cd plugins/modules/`` inside your collection development tree.
 2. Create your new module file: ``$ touch my_test.py``.
-3. Paste the content below into your new module file. It includes the :ref:`required Ansible format and documentation <developing_modules_documenting>` and some example code.
-4. Modify and extend the code to do what you want your new module to do. See the :ref:`programming tips <developing_modules_best_practices>` and :ref:`Python 3 compatibility <developing_python_3>` pages for pointers on writing clean, concise module code.
+3. Paste the content below into your new module file. It includes the :ref:`required Ansible format and documentation <developing_modules_documenting>`, a simple :ref:`argument spec for declaring the module options <argument_spec>`, and some example code.
+4. Modify and extend the code to do what you want your new module to do. See the :ref:`programming tips <developing_modules_best_practices>` and :ref:`Python 3 compatibility <developing_python_3>` pages for pointers on writing clean and concise module code.
 
 .. literalinclude:: ../../../../examples/scripts/my_test.py
    :language: python

docs/docsite/rst/dev_guide/developing_plugins.rst

@@ -221,7 +221,7 @@ but with an extra option so you can see how configuration works in Ansible versi
     requirements:
       - whitelist in configuration
     short_description: Adds time to play stats
-    version_added: "2.0"
+    version_added: "2.0"  # for collections, use the collection version, not the Ansible version
     description:
         - This callback just adds total play duration to the play stats.
     options:
@@ -334,7 +334,7 @@ Here's a simple lookup plugin implementation --- this lookup returns the content
   DOCUMENTATION = """
           lookup: file
           author: Daniel Hokka Zakrisson <daniel@hozac.com>
-          version_added: "0.9"
+          version_added: "0.9"  # for collections, use the collection version, not the Ansible version
           short_description: read file contents
           description:
               - This lookup returns the contents from a file on the Ansible controller's file system.
@@ -460,7 +460,7 @@ Include the ``vars_plugin_staging`` documentation fragment to allow users to det
 
     DOCUMENTATION = '''
         vars: custom_hostvars
-        version_added: "2.10"
+        version_added: "2.10"  # for collections, use the collection version, not the Ansible version
         short_description: Load custom host vars
         description: Load custom host vars
         options:

docs/docsite/rst/dev_guide/developing_program_flow_modules.rst

@@ -561,83 +561,320 @@ Example ``argument_spec``:
 
 This section will discuss the behavioral attributes for arguments:
 
-type
-""""
+:type:
 
-``type`` allows you to define the type of the value accepted for the argument. The default value for ``type`` is ``str``. Possible values are:
+  ``type`` allows you to define the type of the value accepted for the argument. The default value for ``type`` is ``str``. Possible values are:
 
-* str
-* list
-* dict
-* bool
-* int
-* float
-* path
-* raw
-* jsonarg
-* json
-* bytes
-* bits
+  * str
+  * list
+  * dict
+  * bool
+  * int
+  * float
+  * path
+  * raw
+  * jsonarg
+  * json
+  * bytes
+  * bits
 
-The ``raw`` type, performs no type validation or type casting, and maintains the type of the passed value.
+  The ``raw`` type, performs no type validation or type casting, and maintains the type of the passed value.
 
-elements
-""""""""
+:elements:
 
-``elements`` works in combination with ``type`` when ``type='list'``. ``elements`` can then be defined as ``elements='int'`` or any other type, indicating that each element of the specified list should be of that type.
+  ``elements`` works in combination with ``type`` when ``type='list'``. ``elements`` can then be defined as ``elements='int'`` or any other type, indicating that each element of the specified list should be of that type.
 
-default
-"""""""
+:default:
 
-The ``default`` option allows sets a default value for the argument for the scenario when the argument is not provided to the module. When not specified, the default value is ``None``.
+  The ``default`` option allows sets a default value for the argument for the scenario when the argument is not provided to the module. When not specified, the default value is ``None``.
 
-fallback
-""""""""
+:fallback:
 
-``fallback`` accepts a ``tuple`` where the first argument is a callable (function) that will be used to perform the lookup, based on the second argument. The second argument is a list of values to be accepted by the callable.
+  ``fallback`` accepts a ``tuple`` where the first argument is a callable (function) that will be used to perform the lookup, based on the second argument. The second argument is a list of values to be accepted by the callable.
 
-The most common callable used is ``env_fallback`` which will allow an argument to optionally use an environment variable when the argument is not supplied.
+  The most common callable used is ``env_fallback`` which will allow an argument to optionally use an environment variable when the argument is not supplied.
 
-Example::
+  Example:
 
-    username=dict(fallback=(env_fallback, ['ANSIBLE_NET_USERNAME']))
+  .. code-block:: python
 
-choices
-"""""""
+      username=dict(fallback=(env_fallback, ['ANSIBLE_NET_USERNAME']))
 
-``choices`` accepts a list of choices that the argument will accept. The types of ``choices`` should match the ``type``.
+:choices:
 
-required
-""""""""
+  ``choices`` accepts a list of choices that the argument will accept. The types of ``choices`` should match the ``type``.
 
-``required`` accepts a boolean, either ``True`` or ``False`` that indicates that the argument is required. When not specified, ``required`` defaults to ``False``. This should not be used in combination with ``default``.
+:required:
 
-no_log
-""""""
+  ``required`` accepts a boolean, either ``True`` or ``False`` that indicates that the argument is required. When not specified, ``required`` defaults to ``False``. This should not be used in combination with ``default``.
 
-``no_log`` accepts a boolean, either ``True`` or ``False``, that indicates explicitly whether or not the argument value should be masked in logs and output.
+:no_log:
 
-.. note::
-   In the absence of ``no_log``, if the parameter name appears to indicate that the argument value is a password or passphrase (such as "admin_password"), a warning will be shown and the value will be masked in logs but **not** output. To disable the warning and masking for parameters that do not contain sensitive information, set ``no_log`` to ``False``.
+  ``no_log`` accepts a boolean, either ``True`` or ``False``, that indicates explicitly whether or not the argument value should be masked in logs and output.
 
-aliases
-"""""""
+  .. note::
+     In the absence of ``no_log``, if the parameter name appears to indicate that the argument value is a password or passphrase (such as "admin_password"), a warning will be shown and the value will be masked in logs but **not** output. To disable the warning and masking for parameters that do not contain sensitive information, set ``no_log`` to ``False``.
 
-``aliases`` accepts a list of alternative argument names for the argument, such as the case where the argument is ``name`` but the module accepts ``aliases=['pkg']`` to allow ``pkg`` to be interchangeably with ``name``
+:aliases:
 
-options
-"""""""
+  ``aliases`` accepts a list of alternative argument names for the argument, such as the case where the argument is ``name`` but the module accepts ``aliases=['pkg']`` to allow ``pkg`` to be interchangeably with ``name``
 
-``options`` implements the ability to create a sub-argument_spec, where the sub options of the top level argument are also validated using the attributes discussed in this section. The example at the top of this section demonstrates use of ``options``. ``type`` or ``elements`` should be ``dict`` is this case.
+:options:
 
-apply_defaults
-""""""""""""""
+  ``options`` implements the ability to create a sub-argument_spec, where the sub options of the top level argument are also validated using the attributes discussed in this section. The example at the top of this section demonstrates use of ``options``. ``type`` or ``elements`` should be ``dict`` is this case.
 
-``apply_defaults`` works alongside ``options`` and allows the ``default`` of the sub-options to be applied even when the top-level argument is not supplied.
+:apply_defaults:
 
-In the example of the ``argument_spec`` at the top of this section, it would allow ``module.params['top_level']['second_level']`` to be defined, even if the user does not provide ``top_level`` when calling the module.
+  ``apply_defaults`` works alongside ``options`` and allows the ``default`` of the sub-options to be applied even when the top-level argument is not supplied.
 
-removed_in_version
-""""""""""""""""""
+  In the example of the ``argument_spec`` at the top of this section, it would allow ``module.params['top_level']['second_level']`` to be defined, even if the user does not provide ``top_level`` when calling the module.
 
-``removed_in_version`` indicates which version of Ansible a deprecated argument will be removed in.
+:removed_in_version:
+
+  ``removed_in_version`` indicates which version of ansible-base or a collection a deprecated argument will be removed in. Mutually exclusive with ``removed_at_date``, and must be used with ``removed_from_collection``.
+
+  Example:
+
+  .. code-block:: python
+
+      'option': {
+        'type': 'str',
+        'removed_in_version': '2.0.0',
+        'collection_name': 'testns.testcol',
+      },
+
+:removed_at_date:
+
+  ``removed_at_date`` indicates that a deprecated argument will be removed in a minor ansible-base release or major collection release after this date. Mutually exclusive with ``removed_in_version``, and must be used with ``removed_from_collection``.
+
+  Example:
+
+  .. code-block:: python
+
+      'option': {
+        'type': 'str',
+        'removed_at_date': '2020-12-31',
+        'collection_name': 'testns.testcol',
+      },
+
+:removed_from_collection:
+
+  Specifies which collection (or ansible-base) deprecates this deprecated argument. Specify ``ansible.builtin`` for ansible-base, or the collection's name (format ``foo.bar``). Must be used with ``removed_in_version`` or ``removed_at_date``.
+
+:deprecated_aliases:
+
+  Deprecates aliases of this argument. Must contain a list or tuple of dictionaries having some the following keys:
+
+  :name:
+
+    The name of the alias to deprecate. (Required.)
+
+  :version:
+
+    The version of ansible-base or the collection this alias will be removed in. Either ``version`` or ``date`` must be specified.
+
+  :date:
+
+    The a date after which a minor release of ansible-base or a major collection release will no longer contain this alias.. Either ``version`` or ``date`` must be specified.
+
+  :collection_name:
+
+    Specifies which collection (or ansible-base) deprecates this deprecated alias. Specify ``ansible.builtin`` for ansible-base, or the collection's name (format ``foo.bar``). Must be used with ``version`` or ``date``.
+
+  Examples:
+
+  .. code-block:: python
+
+      'option': {
+        'type': 'str',
+        'aliases': ['foo', 'bar'],
+        'depecated_aliases': [
+          {
+            'name': 'foo',
+            'version': '2.0.0',
+            'collection_name': 'testns.testcol',
+          },
+          {
+            'name': 'foo',
+            'date': '2020-12-31',
+            'collection_name': 'testns.testcol',
+          },
+        ],
+      },
+
+
+:mutually_exclusive:
+
+  If ``options`` is specified, ``mutually_exclusive`` refers to the sub-options described in ``options`` and behaves as in :ref:`argument_spec_dependencies`.
+
+:required_together:
+
+  If ``options`` is specified, ``required_together`` refers to the sub-options described in ``options`` and behaves as in :ref:`argument_spec_dependencies`.
+
+:required_one_of:
+
+  If ``options`` is specified, ``required_one_of`` refers to the sub-options described in ``options`` and behaves as in :ref:`argument_spec_dependencies`.
+
+:required_if:
+
+  If ``options`` is specified, ``required_if`` refers to the sub-options described in ``options`` and behaves as in :ref:`argument_spec_dependencies`.
+
+:required_by:
+
+  If ``options`` is specified, ``required_by`` refers to the sub-options described in ``options`` and behaves as in :ref:`argument_spec_dependencies`.
+
+
+.. _argument_spec_dependencies:
+
+Dependencies between module options
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following are optional arguments for ``AnsibleModule()``:
+
+.. code-block:: python
+
+    module = AnsibleModule(
+      argument_spec,
+      mutually_exclusive=[
+        ('path', 'content'),
+      ],
+      required_one_of=[
+        ('path', 'content'),
+      ],
+    )
+
+:mutually_exclusive:
+
+  Must be a sequence (list or tuple) of sequences of strings. Every sequence of strings is a list of option names which are mutually exclusive. If more than one options of a list are specified together, Ansible will fail the module with an error.
+
+  Example:
+
+  .. code-block:: python
+
+      mutually_exclusive=[
+        ('path', 'content'),
+        ('repository_url', 'repository_filename'),
+      ],
+
+  In this example, the options ``path`` and ``content`` must not specified at the same time. Also the options ``repository_url`` and ``repository_filename`` must not be specified at the same time. But specifying ``path`` and ``repository_url`` is accepted.
+
+  To ensure that precisely one of two (or more) options is specified, combine ``mutually_exclusive`` with ``required_one_of``.
+
+:required_together:
+
+  Must be a sequence (list or tuple) of sequences of strings. Every sequence of strings is a list of option names which are must be specified together. If at least one of these options are specified, the other ones from the same sequence must all be present.
+
+  Example:
+
+  .. code-block:: python
+
+      required_together=[
+        ('file_path', 'file_hash'),
+      ],
+
+  In this example, if one of the options ``file_path`` or ``file_hash`` is specified, Ansible will fail the module with an error if the other one is not specified.
+
+:required_one_of:
+
+  Must be a sequence (list or tuple) of sequences of strings. Every sequence of strings is a list of option names from which at least one must be specified. If none one of these options are specified, Ansible will fail module execution.
+
+  Example:
+
+  .. code-block:: python
+
+      required_one_of=[
+        ('path', 'content'),
+      ],
+
+  In this example, at least one of ``path`` and ``content`` must be specified. If none are specified, execution will fail. Specifying both is explicitly allowed; to prevent this, combine ``required_one_of`` with ``mutually_exclusive``.
+
+:required_if:
+
+  Must be a sequence of sequences. Every inner sequence describes one conditional dependency. Every sequence must have three or four values. The first two values are the option's name and the option's value which describes the condition. The further elements of the sequence are only needed if the option of that name has precisely this value.
+
+  If you want that all options in a list of option names are specified if the condition is met, use one of the following forms:
+
+  .. code-block:: python
+
+      ('option_name', option_value, ('option_a', 'option_b', ...)),
+      ('option_name', option_value, ('option_a', 'option_b', ...), False),
+
+  If you want that at least one option of a list of option names is specified if the condition is met, use the following form:
+
+  .. code-block:: python
+
+      ('option_name', option_value, ('option_a', 'option_b', ...), True),
+
+  Example:
+
+  .. code-block:: python
+
+      required_if=[
+        ('state', 'present', ('path', 'content'), True),
+        ('force', True, ('force_reason', 'force_code')),
+      ],
+
+  In this example, if the user specifies ``state=present``, at least one of the options ``path`` and ``content`` must be supplied (or both). To make sure that precisely one can be specified, combine ``required_if`` with ``mutually_exclusive``.
+
+  On the other hand, if ``force`` (a boolean parameter) is set to ``true``, ``yes`` etc., both ``force_reason`` and ``force_code`` must be specified.
+
+:required_by:
+
+  Must be a dictionary mapping option names to sequences of option names. If the option name in a dictionary key is specified, the option names it maps to must all also be specified. Note that instead of a sequence of option names, you can also specify one single option name.
+
+  Example:
+
+  .. code-block:: python
+
+      required_by={
+        'force': 'force_reason',
+        'path': ('mode', 'owner', 'group'),
+      },
+
+  In the example, if ``force`` is specified, ``force_reason`` must also be specified. Also, if ``path`` is specified, then three three options ``mode``, ``owner`` and ``group`` also must be specified.
+
+Declaring check mode support
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To declare that a module supports check mode, supply ``supports_check_mode=True`` to the ``AnsibleModule()`` call:
+
+.. code-block:: python
+
+    module = AnsibleModule(argument_spec, supports_check_mode=True)
+
+The module can determine whether it is called in check mode by checking the boolean value ``module.check_mode``. If it evaluates to ``True``, the module must take care not to do any modification.
+
+If ``supports_check_mode=False`` is specified, which is the default value, the module will exit in check mode with ``skipped=True`` and message ``remote module (<insert module name here>) does not support check mode``.
+
+Adding file options
+^^^^^^^^^^^^^^^^^^^
+
+To declare that a module should add support for all common file options, supply ``add_file_common_args=True`` to the ``AnsibleModule()`` call:
+
+.. code-block:: python
+
+    module = AnsibleModule(argument_spec, add_file_common_args=True)
+
+You can find `a list of all file options here <https://github.com/ansible/ansible/blob/devel/lib/ansible/plugins/doc_fragments/files.py>`_. It is recommended that you make your ``DOCUMENTATION`` extend the doc fragment ``ansible.builtin.files`` (see :ref:`module_docs_fragments`) in this case, to make sure that all these fields are correctly documented.
+
+The helper functions ``module.load_file_common_arguments()`` and ``module.set_fs_attributes_if_different()`` can be used to handle these arguments for you:
+
+.. code-block:: python
+
+    argument_spec = {
+      'path': {
+        'type': 'str',
+        'required': True,
+      },
+    }
+
+    module = AnsibleModule(argument_spec, add_file_common_args=True)
+    changed = False
+
+    # TODO do something with module.params['path'], like update it's contents
+
+    # Ensure that module.params['path'] satisfies the file options supplied by the user
+    file_args = module.load_file_common_arguments(module.params)
+    changed = module.set_fs_attributes_if_different(file_args, changed)
+
+    module.exit_json(changed=changed)