Docs Backportapalooza 01 26 (#79828)

* fix filename for sidecar docs (#79779)

(cherry picked from commit f2707d1fbc3be863983ee2d829303eece6116d2d)

* correct examples to use removed_from_collection not collection_name (#79803)

(cherry picked from commit 7ab3de7ee8e44a53591334997955512239f7ccf8)

* Fix: documentation for per-task timeout (#79715)

(cherry picked from commit 48e6bf8d27694b21922c7293f892e690ae44a9e1)

* [Docs] maintainers_guidelines: add WG and real-time chat request info (#79750)

(cherry picked from commit 6cb6d655b3eba09b9d3b96c681af37c03282469a)

* doc fix for platform content #79794 (#79801)

(cherry picked from commit d7a4152851458d04ed97b10446ddfc096ec8ec6f)

* Expand docs for the import sanity test. (#79768)

* Expand docs for the import sanity test.

* Remove note about Python 2.7 compat.

It should not be needed since there is a sanity test to enforce use of `__metaclass__ = type`.

* Improve introductory paragraph.

* Fix link typo.

(cherry picked from commit 2164d5699cde6a6f76985d0742d38f4bc76e8cbf)

* docs: Extend password entry of ansible.builtin.user (#79694)

* docs: Extend password entry of ansible.builtin.user

Clarify that `password` sets the password hash.
Not the actual password.
Fixes part of  #79684

(cherry picked from commit 6cd1a1404a5179aa99aa7f9182fcce068b297cf9)

* Update dev_guide.rst (#79625)

(cherry picked from commit 65eb5c0a9f4ecf0f358c5c81f9c9e3202a0fde41)

* Improve documentation on requirements.yml (#76140)

Makes it clear that user can use range identifiers with collection
versions inside requirements.yml files.

(cherry picked from commit 44dcfde9b84177e7dfede11ab287789c577b82b5)

---------

Co-authored-by: Evgeni Golov <evgeni@golov.de>
Co-authored-by: Jo <jo@swagspace.org>
Co-authored-by: Andrew Klychkov <aaklychkov@mail.ru>
Co-authored-by: prasadpatil49 <51715670+prasadpatil49@users.noreply.github.com>
Co-authored-by: Matt Clay <matt@mystile.com>
Co-authored-by: Hofer-Julian <30049909+Hofer-Julian@users.noreply.github.com>
Co-authored-by: Jens Timmerman <github@caret.be>
Co-authored-by: Sorin Sbarnea <ssbarnea@redhat.com>

10 files changed, 130 insertions, 77 deletions

diff --git a/docs/docsite/rst/community/maintainers_guidelines.rst b/docs/docsite/rst/community/maintainers_guidelines.rst
index 8e1769627b..7228f8c83d 100644
--- a/docs/docsite/rst/community/maintainers_guidelines.rst
+++ b/docs/docsite/rst/community/maintainers_guidelines.rst
@@ -52,6 +52,22 @@ Collection contributors and maintainers should also communicate through:
 
 See :ref:`communication` for more details on these communication channels.
 
+.. _wg_and_real_time_chat:
+
+Establishing working group communication
+----------------------------------------------------------------
+
+Working groups depend on efficient, real-time communication.
+Project maintainers can use the following techniques to establish communication for working groups:
+
+* Find an existing :ref:`working_group_list` that is similar to your project and join the conversation.
+* `Request <https://github.com/ansible/community/blob/main/WORKING-GROUPS.md>`_ a new working group for your project.
+* `Create <https://hackmd.io/@ansible-community/community-matrix-faq#How-do-I-create-a-public-community-room>`_ a public chat for your working group or `ask <https://github.com/ansible/community/issues/new>`_ the community team.
+* Provide working group details and links to chat rooms in the contributor section of your project ``README.md``.
+* Encourage contributors to join the chats and add themselves to the working group.
+
+See the :ref:`Communication guide <communication_irc>` to learn more about real-time chat.
+
 Community Topics
 ----------------
 
@@ -64,13 +80,12 @@ Share your opinion and vote on the topics to help the community make the best de
 Contributor Summits
 -------------------
 
-
 The quarterly Ansible Contributor Summit is a global event that provides our contributors a great opportunity to meet each other, communicate, share ideas, and see that there are other real people behind the messages on Matrix or Libera Chat IRC, or GitHub. This gives a sense of community. Watch the `Bullhorn newsletter <https://github.com/ansible/community/wiki/News#the-bullhorn>`_ for information when the next contributor summit, invite contributors you know, and take part in the event together.
 
 Weekly community Matrix/IRC meetings
 ------------------------------------
 
-The Community and the Steering Committee come together at weekly meetings in the ``#ansible-community`` :ref:`Matrix/Libera.Chat <communication_irc>` channel to discuss important project-scale questions. See the `schedule <https://github.com/ansible/community/blob/main/meetings/README.md#schedule>`_ and join.
+The Community and the Steering Committee come together at weekly meetings in the ``#ansible-community`` `Libera.Chat IRC <https://docs.ansible.com/ansible/devel/community/communication.html#ansible-community-on-irc>`_ channel or in the bridged `#community:ansible.com <https://matrix.to/#/#community:ansible.com>`_ room on `Matrix <https://docs.ansible.com/ansible/devel/community/communication.html#ansible-community-on-matrix>`_ to discuss important project questions. Join us! Here is our `schedule <https://github.com/ansible/community/blob/main/meetings/README.md#schedule>`_.
 
 Expanding the collection community
 ===================================
@@ -82,6 +97,7 @@ Expanding the collection community
 Here are some ways you can expand the community around your collection:
 
   * Give :ref:`newcomers a positive first experience <collection_new_contributors>`.
+  * Invite contributors to join :ref:`real-time chats <wg_and_real_time_chat>` related to your project.
   * Have :ref:`good documentation <maintainer_documentation>` with guidelines for new contributors.
   * Make people feel welcome personally and individually.
   * Use labels to show easy fixes and leave non-critical easy fixes to newcomers and offer to mentor them.
diff --git a/docs/docsite/rst/dev_guide/ansible_index.rst b/docs/docsite/rst/dev_guide/ansible_index.rst
index 0736df153b..5e79df4514 100644
--- a/docs/docsite/rst/dev_guide/ansible_index.rst
+++ b/docs/docsite/rst/dev_guide/ansible_index.rst
@@ -75,7 +75,7 @@ If you prefer to read the entire guide, here's a list of the pages in order.
    developing_python_3
    debugging
    developing_modules_documenting
-   adjacent_yaml_doc
+   sidecar
    developing_modules_general_windows
    developing_modules_general_aci
    platforms/aws_guidelines
diff --git a/docs/docsite/rst/dev_guide/developing_program_flow_modules.rst b/docs/docsite/rst/dev_guide/developing_program_flow_modules.rst
index d896c544f2..a3cc99a166 100644
--- a/docs/docsite/rst/dev_guide/developing_program_flow_modules.rst
+++ b/docs/docsite/rst/dev_guide/developing_program_flow_modules.rst
@@ -689,7 +689,7 @@ This section will discuss the behavioral attributes for arguments:
       option = {
         'type': 'str',
         'removed_in_version': '2.0.0',
-        'collection_name': 'testns.testcol',
+        'removed_from_collection': 'testns.testcol',
       },
 
 :removed_at_date:
@@ -703,7 +703,7 @@ This section will discuss the behavioral attributes for arguments:
       option = {
         'type': 'str',
         'removed_at_date': '2020-12-31',
-        'collection_name': 'testns.testcol',
+        'removed_from_collection': 'testns.testcol',
       },
 
 :removed_from_collection:
diff --git a/docs/docsite/rst/dev_guide/testing/sanity/import.rst b/docs/docsite/rst/dev_guide/testing/sanity/import.rst
index 49994092c7..118b3d97ed 100644
--- a/docs/docsite/rst/dev_guide/testing/sanity/import.rst
+++ b/docs/docsite/rst/dev_guide/testing/sanity/import.rst
@@ -1,59 +1,110 @@
 import
 ======
 
-Ansible allows unchecked imports of some libraries from specific directories, listed at the bottom of this section. Import all other Python libraries in a try/except ImportError block to support sanity tests such as ``validate-modules`` and to allow Ansible to give better error messages to the user. To import a library in a try/except ImportError block:
+Ansible :ref:`allows unchecked imports<allowed_unchecked_imports>` of some libraries from specific directories.
+Importing any other Python library requires :ref:`handling import errors<handling_import_errors>`.
+This enables support for sanity tests such as :ref:`testing_validate-modules` and provides better error messages to the user.
 
-1. In modules:
+.. _handling_import_errors:
 
-   .. code-block:: python
+Handling import errors
+----------------------
 
-       # Instead of 'import another_library', do:
+In modules
+^^^^^^^^^^
 
-       import traceback
+Instead of using ``import another_library``:
 
-       try:
-           import another_library
-       except ImportError:
-           HAS_ANOTHER_LIBRARY = False
-           ANOTHER_LIBRARY_IMPORT_ERROR = traceback.format_exc()
-       else:
-           HAS_ANOTHER_LIBRARY = True
+.. code-block:: python
 
+   import traceback
 
-       # Later in module code:
+   from ansible.module_utils.basic import missing_required_lib
 
-       module = AnsibleModule(...)
+   try:
+       import another_library
+   except ImportError:
+       HAS_ANOTHER_LIBRARY = False
+       ANOTHER_LIBRARY_IMPORT_ERROR = traceback.format_exc()
+   else:
+       HAS_ANOTHER_LIBRARY = True
 
-       if not HAS_ANOTHER_LIBRARY:
-           # Needs: from ansible.module_utils.basic import missing_required_lib
-           module.fail_json(
-               msg=missing_required_lib('another_library'),
-               exception=ANOTHER_LIBRARY_IMPORT_ERROR)
+.. note::
 
-2. In plugins:
+   The ``missing_required_lib`` import above will be used below.
 
-   .. code-block:: python
+Then in the module code:
 
-       # Instead of 'import another_library', do:
+.. code-block:: python
 
-       from ansible.module_utils.six import raise_from
+   module = AnsibleModule(...)
 
-       try:
-           import another_library
-       except ImportError as imp_exc:
-           ANOTHER_LIBRARY_IMPORT_ERROR = imp_exc
-       else:
-           ANOTHER_LIBRARY_IMPORT_ERROR = None
+   if not HAS_ANOTHER_LIBRARY:
+       module.fail_json(
+           msg=missing_required_lib('another_library'),
+           exception=ANOTHER_LIBRARY_IMPORT_ERROR)
 
+In plugins
+^^^^^^^^^^
 
-       # Later in plugin code, for example in __init__ of the plugin:
+Instead of using ``import another_library``:
 
-       if ANOTHER_LIBRARY_IMPORT_ERROR:
-           raise_from(
-               AnsibleError('another_library must be installed to use this plugin'),
-               ANOTHER_LIBRARY_IMPORT_ERROR)
-           # If you target only newer Python 3 versions, you can also use the
-           # 'raise ... from ...' syntax.
+.. code-block:: python
+
+   try:
+       import another_library
+   except ImportError as imp_exc:
+       ANOTHER_LIBRARY_IMPORT_ERROR = imp_exc
+   else:
+       ANOTHER_LIBRARY_IMPORT_ERROR = None
+
+Then in the plugin code, for example in ``__init__`` of the plugin:
+
+.. code-block:: python
+
+   if ANOTHER_LIBRARY_IMPORT_ERROR:
+       raise AnsibleError('another_library must be installed to use this plugin') from ANOTHER_LIBRARY_IMPORT_ERROR
+
+When used as base classes
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. important::
+
+   This solution builds on the previous two examples.
+   Make sure to pick the appropriate one before continuing with this solution.
+
+Sometimes an import is used in a base class, for example:
+
+.. code-block:: python
+
+   from another_library import UsefulThing
+
+   class CustomThing(UsefulThing):
+       pass
+
+One option is make the entire class definition conditional:
+
+.. code-block:: python
+
+   if not ANOTHER_LIBRARY_IMPORT_ERROR:
+       class CustomThing(UsefulThing):
+           pass
+
+Another option is to define a substitute base class by modifying the exception handler:
+
+.. code-block:: python
+
+   try:
+       from another_library import UsefulThing
+   except ImportError:
+       class UsefulThing:
+           pass
+       ...
+
+.. _allowed_unchecked_imports:
+
+Allowed unchecked imports
+-------------------------
 
 Ansible allows the following unchecked imports from these specific directories:
 
diff --git a/docs/docsite/rst/galaxy/dev_guide.rst b/docs/docsite/rst/galaxy/dev_guide.rst
index 094ef532a3..01a92d0290 100644
--- a/docs/docsite/rst/galaxy/dev_guide.rst
+++ b/docs/docsite/rst/galaxy/dev_guide.rst
@@ -95,32 +95,12 @@ Alternatively, the role_skeleton and ignoring of files can be configured via ans
 Authenticate with Galaxy
 ------------------------
 
-Using the ``import``, ``delete`` and ``setup`` commands to manage your roles on the Galaxy website requires authentication, and the ``login`` command
-can be used to do just that. Before you can use the ``login`` command, you must create an account on the Galaxy website.
+Using the ``import``, ``delete`` and ``setup`` commands to manage your roles on the Galaxy website requires authentication in the form of an API key, you must create an account on the Galaxy website.
 
-The ``login`` command requires using your GitHub credentials. You can use your username and password, or you can create a `personal access token <https://help.github.com/articles/creating-an-access-token-for-command-line-use/>`_. If you choose to create a token, grant minimal access to the token, as it is used just to verify identify.
+#. Log in to the Galaxy website and open the `Preferences <https://galaxy.ansible.com/me/preferences>`_ view.
+#. Select **Show API key** and then copy it.
 
-The following shows authenticating with the Galaxy website using a GitHub username and password:
-
-.. code-block:: text
-
-   $ ansible-galaxy login
-
-   We need your GitHub login to identify you.
-   This information will not be sent to Galaxy, only to api.github.com.
-   The password will not be displayed.
-
-   Use --github-token if you do not want to enter your password.
-
-   GitHub Username: dsmith
-   Password for dsmith:
-   Successfully logged into Galaxy as dsmith
-
-When you choose to use your username and password, your password is not sent to Galaxy. It is used to authenticates with GitHub and create a personal access token.
-It then sends the token to Galaxy, which in turn verifies that your identity and returns a Galaxy access token. After authentication completes the GitHub token is
-destroyed.
-
-If you do not want to use your GitHub password, or if you have two-factor authentication enabled with GitHub, use the ``--github-token`` option to pass a personal access token that you create.
+#. Save your token in the path set in the :ref:`GALAXY_TOKEN_PATH`.
 
 
 Import a role
diff --git a/docs/docsite/rst/galaxy/user_guide.rst b/docs/docsite/rst/galaxy/user_guide.rst
index e4beb7ef82..c5a1e19e8f 100644
--- a/docs/docsite/rst/galaxy/user_guide.rst
+++ b/docs/docsite/rst/galaxy/user_guide.rst
@@ -330,12 +330,12 @@ You can install roles and collections from the same requirements files
     roles:
       # Install a role from Ansible Galaxy.
       - name: geerlingguy.java
-        version: 1.9.6
+        version: "1.9.6" # note that ranges are not supported for roles
 
     collections:
       # Install a collection from Ansible Galaxy.
       - name: geerlingguy.php_roles
-        version: 0.9.3
+        version: ">=0.9.3"
         source: https://galaxy.ansible.com
 
 Installing multiple roles from multiple files
diff --git a/docs/docsite/rst/network/user_guide/network_debug_troubleshooting.rst b/docs/docsite/rst/network/user_guide/network_debug_troubleshooting.rst
index 202814b304..d0fbcd6383 100644
--- a/docs/docsite/rst/network/user_guide/network_debug_troubleshooting.rst
+++ b/docs/docsite/rst/network/user_guide/network_debug_troubleshooting.rst
@@ -509,6 +509,8 @@ Suggestions to resolve:
 
   Suggestions to resolve:
 
+  Some modules support a ``timeout`` option, which is different to the ``timeout`` keyword for tasks.
+  
   .. code-block:: yaml
 
       - name: save running-config
@@ -519,6 +521,8 @@ Suggestions to resolve:
 
 
   Suggestions to resolve:
+  
+  If the module does not support the ``timeout`` option directly, most networking connection plugins can enable similar functionality with the ``ansible_command_timeout``  variable.
 
   .. code-block:: yaml
 
diff --git a/docs/docsite/rst/reference_appendices/tower.rst b/docs/docsite/rst/reference_appendices/tower.rst
index 62c6afa349..3537d606b1 100644
--- a/docs/docsite/rst/reference_appendices/tower.rst
+++ b/docs/docsite/rst/reference_appendices/tower.rst
@@ -5,7 +5,7 @@ Red Hat Ansible Automation Platform
 
 .. important::
 
-  Red Hat Ansible Automation Platform will soon be available on Microsoft Azure. `Sign up to preview the experience <https://www.redhat.com/en/engage/ansible-microsoft-azure-e-202110220735>`_.
+  Red Hat Ansible Automation Platform is available on multiple cloud platforms. See `Ansible on Clouds <https://access.redhat.com/documentation/en-us/ansible_on_clouds/2.x>`_ for details.
   
 `Red Hat Ansible Automation Platform <https://www.ansible.com/products/automation-platform>`_ (RHAAP) is an integrated solution for operationalizing Ansible across your team, organization, and enterprise. The platform includes a controller with a web console and REST API, analytics, execution environments, and much more.
 
diff --git a/docs/docsite/rst/shared_snippets/installing_multiple_collections.txt b/docs/docsite/rst/shared_snippets/installing_multiple_collections.txt
index c8cca8b48b..a1b18b5937 100644
--- a/docs/docsite/rst/shared_snippets/installing_multiple_collections.txt
+++ b/docs/docsite/rst/shared_snippets/installing_multiple_collections.txt
@@ -10,8 +10,8 @@ You can set up a ``requirements.yml`` file to install multiple collections in on
 
    # With the collection name, version, and source options
    - name: my_namespace.my_other_collection
-     version: 'version range identifiers (default: ``*``)'
-     source: 'The Galaxy URL to pull the collection from (default: ``--api-server`` from cmdline)'
+     version: ">=1.2.0" # Version range identifiers (default: ``*``)
+     source: ... # The Galaxy URL to pull the collection from (default: ``--api-server`` from cmdline)
 
 You can specify the following keys for each collection entry:
 
@@ -56,12 +56,13 @@ You can also add roles to a ``requirements.yml`` file, under the ``roles`` key.
     roles:
       # Install a role from Ansible Galaxy.
       - name: geerlingguy.java
-        version: 1.9.6
+        version: "1.9.6" # note that ranges are not supported for roles
+
 
     collections:
       # Install a collection from Ansible Galaxy.
       - name: geerlingguy.php_roles
-        version: 0.9.3
+        version: ">=0.9.3"
         source: https://galaxy.ansible.com
 
 To install both roles and collections at the same time with one command, run the following:
diff --git a/lib/ansible/modules/user.py b/lib/ansible/modules/user.py
index cb35e95002..2fc4e47397 100644
--- a/lib/ansible/modules/user.py
+++ b/lib/ansible/modules/user.py
@@ -86,12 +86,13 @@ options:
         version_added: "2.0"
     password:
         description:
-            - Optionally set the user's password to this crypted value.
-            - On macOS systems, this value has to be cleartext. Beware of security issues.
-            - To create a an account with a locked/disabled password on Linux systems, set this to C('!') or C('*').
-            - To create a an account with a locked/disabled password on OpenBSD, set this to C('*************').
+            - If provided, set the user's password to the provided encrypted hash (Linux) or plain text password (macOS).
+            - B(Linux/Unix/POSIX:) Enter the hashed password as the value.
             - See L(FAQ entry,https://docs.ansible.com/ansible/latest/reference_appendices/faq.html#how-do-i-generate-encrypted-passwords-for-the-user-module)
-              for details on various ways to generate these password values.
+              for details on various ways to generate the hash of a password.
+            - To create an account with a locked/disabled password on Linux systems, set this to C('!') or C('*').
+            - To create an account with a locked/disabled password on OpenBSD, set this to C('*************').
+            - B(OS X/macOS:) Enter the cleartext password as the value. Be sure to take relevant security precautions.
         type: str
     state:
         description: