Backportapalooza 7 15 (#78277)

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

* Add context to inventory plugins documentation

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

(cherry picked from commit a77fc2e822effb6ad05037a52adf849adf2adedf)

* Update dpkg_selections.py (#78177)

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

* Fix pep8 issue: dpkg_selections.py

Missed some trailing spaces when adding example text.

(cherry picked from commit 489b7f18592b4eb57d919cfeffff953c650bb3dd)

* fix ternary problem (#78186)

(cherry picked from commit 7ec8916097a4c4281215c127c80ed07c5b0b370d)

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

fixes #78195

(cherry picked from commit e10851d495fd073e22bdd78ec45a1f8019604b35)

* Update python_3_support.rst (#78239)

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

(cherry picked from commit be88250a83805599570997d669891afff2709f1b)

* Adding applicable licensing requirements (#78162)

(cherry picked from commit 6ddccc1604173cfbd56f3abe6aa4d8868d21b82a)

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

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

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

(cherry picked from commit 221af7640d501ef894df9becd6a5a22599041a59)

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

(cherry picked from commit 0590ce065ce51c208bce863365fa981cd931ce93)

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

(cherry picked from commit 048adac5b72a8f4d9e3c13fc5888787309db0d79)

* Updated release_and_maintenance.rst (#78272)

(cherry picked from commit 358a8ad7af3acf7e0768c2b503d421219b3c951c)

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

13 files changed, 73 insertions, 128 deletions

diff --git a/docs/docsite/rst/dev_guide/developing_modules_documenting.rst b/docs/docsite/rst/dev_guide/developing_modules_documenting.rst
index c8f37e4a8d..9bd9cbd461 100644
--- a/docs/docsite/rst/dev_guide/developing_modules_documenting.rst
+++ b/docs/docsite/rst/dev_guide/developing_modules_documenting.rst
@@ -33,28 +33,24 @@ Begin your Ansible module with ``#!/usr/bin/python`` - this "shebang" allows ``a
 Copyright and license
 =====================
 
-After the shebang and UTF-8 coding, add a `copyright line <https://www.gnu.org/licenses/gpl-howto.en.html>`_ with the original copyright holder and a license declaration. The license declaration should be ONLY one line, not the full GPL prefix.:
+After the shebang and UTF-8 coding, add a `copyright line <https://www.linuxfoundation.org/blog/copyright-notices-in-open-source-software-projects/>`_ with the original copyright holder and a license declaration. The license declaration should be ONLY one line, not the full GPL prefix.:
 
 .. code-block:: python
 
     #!/usr/bin/python
     # -*- coding: utf-8 -*-
 
-    # Copyright: (c) 2018, Terry Jones <terry.jones@example.org>
+    # Copyright: Contributors to the Ansible project
     # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-Major additions to the module (for instance, rewrites) may add additional copyright lines. Any legal review will include the source control history, so an exhaustive copyright header is not necessary.
-Please do not edit the existing copyright year. This simplifies project administration and is unlikely to cause any interesting legal issues.
-When adding a second copyright line for a significant feature or rewrite, add the newer line above the older one:
+Additions to the module (for instance, rewrites) are not permitted to add additional copyright lines other than the default copyright statement if missing:
 
 .. code-block:: python
 
-    #!/usr/bin/python
-    # -*- coding: utf-8 -*-
-
-    # Copyright: (c) 2017, [New Contributor(s)]
-    # Copyright: (c) 2015, [Original Contributor(s)]
-    # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+    # Copyright: Contributors to the Ansible project
+    
+Any legal review will include the source control history, so an exhaustive copyright header is not necessary.
+Please do not include a copyright year. If the existing copyright statement includes a year, do not edit the existing copyright year. Any existing copyright header should not be modified without permission from the copyright author.
 
 .. _ansible_metadata_block:
 
diff --git a/docs/docsite/rst/dev_guide/platforms/vmware_rest_guidelines.rst b/docs/docsite/rst/dev_guide/platforms/vmware_rest_guidelines.rst
index db35559a22..c176dfdbc3 100644
--- a/docs/docsite/rst/dev_guide/platforms/vmware_rest_guidelines.rst
+++ b/docs/docsite/rst/dev_guide/platforms/vmware_rest_guidelines.rst
@@ -4,108 +4,4 @@
 Guidelines for VMware REST module development
 *********************************************
 
-The Ansible VMware REST collection (on `Galaxy <https://galaxy.ansible.com/vmware/vmware_rest>`_, source code `repository <https://github.com/ansible-collections/vmware.vmware_rest>`_) is maintained by Red Hat and the community.
-
-.. contents::
-   :local:
-
-Contribution process
-====================
-
-The modules of the vmware_rest collection are autogenerated by another tool called `vmware_rest_code_generator <https://github.com/ansible-collections/vmware_rest_code_generator>`.
-
-If you would like to contribute a change, we would appreciate if you:
-
-- submit a Github Pull Request (PR) against the vmware_rest_code_generator project
-- but also ensure the generated modules are compliant with our quality criteria.
-
-Requirements
-============
-
-You will need:
-
-- Python 3.6 or greater
-- the `tox <https://tox.readthedocs.io/en/latest/install.html>` command
-
-
-vmware_rest_code_generator
-==========================
-
-Your contribution should follow the coding style of `Black <https://github.com/psf/black>`.
-To run the code formatter, just run:
-
-.. code-block:: shell
-
-    tox -e black
-
-To regenerate the vmware_rest collection, you can use the following commands:
-
-.. code-block:: shell
-
-    tox -e refresh_modules -- --target-dir ~/.ansible/collections/ansible_collections/vmware/vmware_rest
-
-If you also want to update the EXAMPLE section of the modules, run:
-
-.. code-block:: shell
-
-    tox -e refresh_examples -- --target-dir ~/.ansible/collections/ansible_collections/vmware/vmware_rest
-
-Testing with ansible-test
-=========================
-
-All the modules are covered by a functional test. The tests are located in the :file:`tests/integration/targets/`.
-
-To run the tests, you will need a vcenter instance and an ESXi.
-
-black code formatter
-^^^^^^^^^^^^^^^^^^^^
-
-We follow the coding style of `Black <https://github.com/psf/black>`.
-You can run the code formatter with the following command.
-
-
-.. code-block:: shell
-
-    tox -e black
-
-sanity tests
-^^^^^^^^^^^^
-
-Here we use Python 3.8, the minimal version is 3.6.
-
-.. code-block:: shell
-
-    tox -e black
-    ansible-test sanity --debug --requirements --local --skip-test future-import-boilerplate --skip-test metaclass-boilerplate --python 3.8 -vvv
-
-
-integration tests
-^^^^^^^^^^^^^^^^^
-
-These tests should be run against your test environment.
-
-..warning:: The test suite will delete all the existing DC from your test environment. 
-
-First, prepare a configuration file, we call it :file:`/tmp/inventory-vmware_rest` in
-this example:
-
-.. code-block:: ini
-
-    [vmware_rest]
-    localhost ansible_connection=local ansible_python_interpreter=python
-    
-    [vmware_rest:vars]
-    vcenter_hostname=vcenter.test
-    vcenter_username=administrator@vsphere.local
-    vcenter_password=kLRy|FXwZSHXW0w?Q:sO
-    esxi1_hostname=esxi1.test
-    esxi1_username=zuul
-    esxi1_password=f6QYNi65k05kv8m56
-
-
-To run the tests, use the following command. You may want to adjust the Python version.
-
-.. code-block:: shell
-
-    ansible-test network-integration --diff --no-temp-workdir --python 3.8 --inventory /tmp/inventory-vmware_rest zuul/
-
+This guide has moved to :ref:`ansible_collections.vmware.vmware_rest.docsite.vmware_rest_devguide`.
diff --git a/docs/docsite/rst/dev_guide/shared_snippets/licensing.txt b/docs/docsite/rst/dev_guide/shared_snippets/licensing.txt
index 2802c4202e..d4b3051f98 100644
--- a/docs/docsite/rst/dev_guide/shared_snippets/licensing.txt
+++ b/docs/docsite/rst/dev_guide/shared_snippets/licensing.txt
@@ -7,3 +7,6 @@
       * All other ``module_utils`` must be licensed under BSD, so GPL-licensed third-party and Galaxy modules can use them.
       * If there's doubt about the appropriate license for a file in ``module_utils``, the Ansible Core Team will decide during an Ansible Core Community Meeting.
    * All other files shipped with Ansible, including all modules, must be licensed under the GPL license (GPLv3 or later).
+   * Existing license requirements still apply to content in ansible/ansible (ansible-core).
+   * Content that was previously in ansible/ansible or a collection and has moved to a new collection must retain the license it had in its prior repository.
+   * Copyright entries by previous committers must also be kept in any moved files.
diff --git a/docs/docsite/rst/plugins/inventory.rst b/docs/docsite/rst/plugins/inventory.rst
index 8e2ade376a..3328af62e4 100644
--- a/docs/docsite/rst/plugins/inventory.rst
+++ b/docs/docsite/rst/plugins/inventory.rst
@@ -23,13 +23,20 @@ In some circumstances, for example, if the inventory plugin does not use a YAML
    [inventory]
    enable_plugins = host_list, script, auto, yaml, ini, toml
 
-If the plugin is in a collection, use the fully qualified name:
+If the plugin is in a collection and is not being picked up by the `auto` statement, you can append the fully qualified name:
 
 .. code-block:: ini
 
    [inventory]
-   enable_plugins = namespace.collection_name.inventory_plugin_name
+   enable_plugins = host_list, script, auto, yaml, ini, toml, namespace.collection_name.inventory_plugin_name
 
+Or, if it is a local plugin, perhaps stored in the path set by :ref:`DEFAULT_INVENTORY_PLUGIN_PATH`, you could reference it as follows:
+
+.. code-block:: ini
+
+   [inventory]
+   enable_plugins = host_list, script, auto, yaml, ini, toml, my_plugin
+   
 If you use a plugin that supports a YAML configuration source, make sure that the name matches the name provided in the ``plugin`` entry of the inventory source file.
 
 .. _using_inventory:
@@ -80,12 +87,24 @@ You can create dynamic groups using host variables with the constructed ``keyed_
       - key: tags.Name
         prefix: tag_Name_
         separator: ""
+      # If you have a tag called "Role" which has the value "Webserver", this will add the group
+      # role_Webserver and add any hosts that have that tag assigned to it.
+      - key: tags.Role
+        prefix: role
     groups:
       # add hosts to the group development if any of the dictionary's keys or values is the word 'devel'
       development: "'devel' in (tags|list)"
+      # add hosts to the "private_only" group if the host doesn't have a public IP associated to it
+      private_only: "public_ip_address is not defined"
     compose:
-      # set the ansible_host variable to connect with the private IP address without changing the hostname
-      ansible_host: private_ip_address
+      # use a private address where a public one isn't assigned
+      ansible_host: public_ip_address|default(private_ip_address)
+      # alternatively, set the ansible_host variable to connect with the private IP address without changing the hostname
+      # ansible_host: private_ip_address
+      # if you *must* set a string here (perhaps to identify the inventory source if you have multiple
+      # accounts you want to use as sources), you need to wrap this in two sets of quotes, either ' then "
+      # or " then '
+      some_inventory_wide_string: '"Yes, you need both types of quotes here"'
 
 Now the output of ``ansible-inventory -i demo.aws_ec2.yml --graph``:
 
@@ -99,6 +118,8 @@ Now the output of ``ansible-inventory -i demo.aws_ec2.yml --graph``:
       |--@development:
       |  |--ec2-12-345-678-901.compute-1.amazonaws.com
       |  |--ec2-98-765-432-10.compute-1.amazonaws.com
+      |--@role_Webserver
+      |  |--ec2-12-345-678-901.compute-1.amazonaws.com
       |--@tag_Name_ECS_Instance:
       |  |--ec2-98-765-432-10.compute-1.amazonaws.com
       |--@tag_Name_Test_Server:
diff --git a/docs/docsite/rst/reference_appendices/python_3_support.rst b/docs/docsite/rst/reference_appendices/python_3_support.rst
index da06023c1a..4471c64714 100644
--- a/docs/docsite/rst/reference_appendices/python_3_support.rst
+++ b/docs/docsite/rst/reference_appendices/python_3_support.rst
@@ -52,11 +52,11 @@ Using Python 3 on the managed machines with commands and playbooks
     localhost-py3 ansible_host=localhost ansible_connection=local ansible_python_interpreter=/usr/bin/python3
 
     # Example of setting a group of hosts to use Python3
-    [py3-hosts]
+    [py3_hosts]
     ubuntu16
     fedora27
 
-    [py3-hosts:vars]
+    [py3_hosts:vars]
     ansible_python_interpreter=/usr/bin/python3
 
 .. seealso:: :ref:`intro_inventory` for more information.
diff --git a/docs/docsite/rst/reference_appendices/release_and_maintenance.rst b/docs/docsite/rst/reference_appendices/release_and_maintenance.rst
index 649f938b19..8fa16d21d3 100644
--- a/docs/docsite/rst/reference_appendices/release_and_maintenance.rst
+++ b/docs/docsite/rst/reference_appendices/release_and_maintenance.rst
@@ -82,7 +82,7 @@ Ansible Community Package Release       Status                          Core ver
 ==================================      ============================    =========================
 7.0.0                                   In development (unreleased)     2.14
 `6.x Changelogs`_                       Current                         2.13
-`5.x Changelogs`_                       Unmaintained/EOL after 5.10     2.12
+`5.x Changelogs`_                       Unmaintained (end of life)      2.12
 `4.x Changelogs`_                       Unmaintained (end of life)      2.11
 `3.x Changelogs`_                       Unmaintained (end of life)      2.10
 `2.10 Changelogs`_                      Unmaintained (end of life)      2.10
diff --git a/lib/ansible/modules/apt_key.py b/lib/ansible/modules/apt_key.py
index 29de275de2..884b859542 100644
--- a/lib/ansible/modules/apt_key.py
+++ b/lib/ansible/modules/apt_key.py
@@ -81,6 +81,18 @@ options:
 '''
 
 EXAMPLES = '''
+- name: One way to avoid apt_key once it is removed from your distro
+  block:
+    - name: somerepo |no apt key
+      ansible.builtin.get_url:
+        url: https://download.example.com/linux/ubuntu/gpg
+        dest: /etc/apt/trusted.gpg.d/somerepo.asc
+
+    - name: somerepo | apt source
+      ansible.builtin.apt_repository:
+      repo: "deb [arch=amd64 signed-by=/etc/apt/trusted.gpg.d/somerepo.asc] https://download.example.com/linux/ubuntu {{ ansible_distribution_release }} stable"
+      state: present
+
 - name: Add an apt key by id from a keyserver
   ansible.builtin.apt_key:
     keyserver: keyserver.ubuntu.com
diff --git a/lib/ansible/modules/apt_repository.py b/lib/ansible/modules/apt_repository.py
index a4b5023af7..ec5a52739f 100644
--- a/lib/ansible/modules/apt_repository.py
+++ b/lib/ansible/modules/apt_repository.py
@@ -131,6 +131,18 @@ EXAMPLES = '''
   ansible.builtin.apt_repository:
     repo: 'ppa:nginx/stable'
     codename: trusty
+
+- name: One way to avoid apt_key once it is removed from your distro
+  block:
+    - name: somerepo |no apt key
+      ansible.builtin.get_url:
+        url: https://download.example.com/linux/ubuntu/gpg
+        dest: /etc/apt/trusted.gpg.d/somerepo.asc
+
+    - name: somerepo | apt source
+      ansible.builtin.apt_repository:
+      repo: "deb [arch=amd64 signed-by=/etc/apt/trusted.gpg.d/somerepo.asc] https://download.example.com/linux/ubuntu {{ ansible_distribution_release }} stable"
+      state: present
 '''
 
 RETURN = '''#'''
diff --git a/lib/ansible/modules/dpkg_selections.py b/lib/ansible/modules/dpkg_selections.py
index 6d0a1ec855..87cad529b5 100644
--- a/lib/ansible/modules/dpkg_selections.py
+++ b/lib/ansible/modules/dpkg_selections.py
@@ -46,6 +46,11 @@ EXAMPLES = '''
   ansible.builtin.dpkg_selections:
     name: python
     selection: hold
+
+- name: Allow python to be upgraded
+  ansible.builtin.dpkg_selections:
+    name: python
+    selection: install
 '''
 
 from ansible.module_utils.basic import AnsibleModule
diff --git a/lib/ansible/modules/stat.py b/lib/ansible/modules/stat.py
index 8c8d5d31b7..ff0f6712a9 100644
--- a/lib/ansible/modules/stat.py
+++ b/lib/ansible/modules/stat.py
@@ -322,12 +322,12 @@ stat:
             sample: 50ba294cdf28c0d5bcde25708df53346825a429f
         pw_name:
             description: User name of owner
-            returned: success, path exists and user can read stats and installed python supports it
+            returned: success, path exists, user can read stats, owner name can be looked up and installed python supports it
             type: str
             sample: httpd
         gr_name:
             description: Group name of owner
-            returned: success, path exists and user can read stats and installed python supports it
+            returned: success, path exists, user can read stats, owner group can be looked up and installed python supports it
             type: str
             sample: www-data
         mimetype:
diff --git a/lib/ansible/plugins/become/runas.py b/lib/ansible/plugins/become/runas.py
index 1913824faa..0b7d466133 100644
--- a/lib/ansible/plugins/become/runas.py
+++ b/lib/ansible/plugins/become/runas.py
@@ -8,7 +8,7 @@ DOCUMENTATION = """
     name: runas
     short_description: Run As user
     description:
-        - This become plugins allows your remote/login user to execute commands as another user via the windows runas facility.
+        - This become plugin allows your remote/login user to execute commands as another user via the windows runas facility.
     author: ansible (@core)
     version_added: "2.8"
     options:
diff --git a/lib/ansible/plugins/become/su.py b/lib/ansible/plugins/become/su.py
index 6e54bc336e..3a6fdea23b 100644
--- a/lib/ansible/plugins/become/su.py
+++ b/lib/ansible/plugins/become/su.py
@@ -8,7 +8,7 @@ DOCUMENTATION = """
     name: su
     short_description: Substitute User
     description:
-        - This become plugins allows your remote/login user to execute commands as another user via the su utility.
+        - This become plugin allows your remote/login user to execute commands as another user via the su utility.
     author: ansible (@core)
     version_added: "2.8"
     options:
diff --git a/lib/ansible/plugins/become/sudo.py b/lib/ansible/plugins/become/sudo.py
index 778e7afeab..fb285f0027 100644
--- a/lib/ansible/plugins/become/sudo.py
+++ b/lib/ansible/plugins/become/sudo.py
@@ -8,7 +8,7 @@ DOCUMENTATION = """
     name: sudo
     short_description: Substitute User DO
     description:
-        - This become plugins allows your remote/login user to execute commands as another user via the sudo utility.
+        - This become plugin allows your remote/login user to execute commands as another user via the sudo utility.
     author: ansible (@core)
     version_added: "2.8"
     options: