Backportapalooza 03 16 (#80246)

* improve doc dependency install steps (#80120)

(cherry picked from commit 352010f9c322f5cfd1f61d5e66cd8eb7fa0b49b6)

* docs: automatic `always` tag in gather_facts (#80052)

(cherry picked from commit 3216e071c7024084045ae1528bad8d66faf2512a)

* docsite requirements path (#80134)

(cherry picked from commit 1055803c3a812189a1133297f7f5468579283f86)

* Adjust release schedule docs to four weeks (#80166)

(cherry picked from commit 7ce951ff48baaf53feab1ca09930281706813c70)

* Fix spelling and grammar in subelements filter doc (#80137)

(cherry picked from commit 12c1891ce65ade57551560836d371c3c0af5c47a)

* Fixed typo (#80184)

`uvault` should be `unvault`

(cherry picked from commit cb2180e286eb20af32ae5df5c942f2ee989338e2)

* Document debugging conditionals (#80239)

##### SUMMARY
Add a section to the docs describing how to debug conditional statements - how to get Ansible to show you whether your `when:` clause evaluates to `true` or `false`.

I ran into trouble with this and couldn't find anything in the docs. Thought I'd add it.

##### ISSUE TYPE
- Docs Pull Request

+label: docsite_pr

(cherry picked from commit 507fd1bd60f529681c96fa526ffa7835e122ddcb)

* Update connection.rst (#80194)

(cherry picked from commit 0937cc486219663b6b6e6a178ef40798217864fa)

---------

Co-authored-by: Don Naro <dnaro@redhat.com>
Co-authored-by: Jairo Llopis <973709+yajo@users.noreply.github.com>
Co-authored-by: Kristian Heljas <11139388+kristianheljas@users.noreply.github.com>
Co-authored-by: Zachary Peschke <8718570+zpeschke@users.noreply.github.com>
Co-authored-by: Harmdhast <pandemonium.harmdhast@gmail.com>
Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com>
Co-authored-by: Esther Christopher <estheradamuchris@gmail.com>

7 files changed, 61 insertions, 18 deletions

diff --git a/docs/docsite/rst/community/documentation_contributions.rst b/docs/docsite/rst/community/documentation_contributions.rst
index 0f464f117e..082a7b25b0 100644
--- a/docs/docsite/rst/community/documentation_contributions.rst
+++ b/docs/docsite/rst/community/documentation_contributions.rst
@@ -93,21 +93,26 @@ To work with documentation on your local machine, you need to have python-3.9 or
 .. _Ansible dependencies: https://github.com/ansible/ansible/blob/devel/requirements.txt
 .. _documentation dependencies: https://github.com/ansible/ansible/blob/devel/docs/docsite/requirements.txt
 
-.. code-block:: bash
+Drop the ``--user`` option in the following commands if you use a virtual environment (venv/virtenv).
 
-    pip install --user -r requirements.txt
-    pip install --user -r docs/docsite/requirements.txt
+#. Upgrade pip before installing dependencies (recommended).
 
-The :file:`docs/docsite/requirements.txt` file allows a wide range of versions and may install new releases of required packages. New releases of these packages may cause problems with the Ansible docs build. If you want to install tested versions of these dependencies, use :file:`test/sanity/code-smell/docs-build.requirements.txt` instead, which matches the dependencies used by CI:
+   .. code-block:: bash
 
-.. code-block:: bash
+      pip install --user --upgrade pip
+
+#. Install Ansible dependencies.
+
+   .. code-block:: bash
 
-    pip install --user -r requirements.txt
-    pip install --user -r test/sanity/code-smell/docs-build.requirements.txt
+      pip install --user -r requirements.txt
 
+#. Install either the unpinned or tested documentation dependencies.
 
+   .. code-block:: bash
 
-You can drop ``--user`` if you have set up a virtual environment (venv/virtenv). 
+    pip install --user -r docs/docsite/requirements.txt # This file installs unpinned versions that can cause problems with the Ansible docs build.
+    pip install --user -r test/sanity/code-smell/docs-build.requirements.txt # This file installs tested dependency versions that are used by CI.
 
 .. note::
 
diff --git a/docs/docsite/rst/playbook_guide/playbooks_conditionals.rst b/docs/docsite/rst/playbook_guide/playbooks_conditionals.rst
index e1bf42d5cb..1de9ec39c7 100644
--- a/docs/docsite/rst/playbook_guide/playbooks_conditionals.rst
+++ b/docs/docsite/rst/playbook_guide/playbooks_conditionals.rst
@@ -464,6 +464,44 @@ For example, you can template out a configuration file that is very different be
           -  default.conf
         mypaths: ['search_location_one/somedir/', '/opt/other_location/somedir/']
 
+.. _debugging_conditionals:
+
+Debugging conditionals
+======================
+
+If your conditional ``when`` statement is not behaving as you intended, you can add a ``debug`` statement to determine if the condition evaluates to ``true`` or ``false``. A common cause of unexpected behavior in conditionals is testing an integer as a string or a string as an integer. To debug a conditional statement, add the entire statement as the ``var:`` value in a ``debug`` task. Ansible then shows the test and how the statement evaluates. For example, here is a set of tasks and sample output: 
+
+.. code-block:: yaml
+
+   - name: check value of return code
+     ansible.builtin.debug:
+       var: bar_status.rc
+       
+   - name: check test for rc value as string
+     ansible.builtin.debug:
+       var: bar_status.rc == "127"
+
+   - name: check test for rc value as integer
+     ansible.builtin.debug:
+       var: bar_status.rc == 127
+
+.. code-block:: ansible-output
+
+   TASK [check value of return code] *********************************************************************************
+   ok: [foo-1] => {
+       "bar_status.rc": "127"
+   }
+
+   TASK [check test for rc value as string] **************************************************************************
+   ok: [foo-1] => {
+       "bar_status.rc == \"127\"": false
+   }
+
+   TASK [check test for rc value as integer] *************************************************************************
+   ok: [foo-1] => {
+       "bar_status.rc == 127": true
+   }
+
 .. _commonly_used_facts:
 
 Commonly-used facts
diff --git a/docs/docsite/rst/playbook_guide/playbooks_tags.rst b/docs/docsite/rst/playbook_guide/playbooks_tags.rst
index bf01458f0d..deff48bd90 100644
--- a/docs/docsite/rst/playbook_guide/playbooks_tags.rst
+++ b/docs/docsite/rst/playbook_guide/playbooks_tags.rst
@@ -301,7 +301,7 @@ For example:
 
 .. warning::
    * Fact gathering is tagged with 'always' by default. It is only skipped if
-     you apply a tag and then use a different tag in ``--tags`` or the same
+     you apply a tag to the play and then use a different tag in ``--tags`` or the same
      tag in ``--skip-tags``.
 
 .. warning::
diff --git a/docs/docsite/rst/plugins/connection.rst b/docs/docsite/rst/plugins/connection.rst
index e29842b682..3652ffe178 100644
--- a/docs/docsite/rst/plugins/connection.rst
+++ b/docs/docsite/rst/plugins/connection.rst
@@ -9,7 +9,7 @@ Connection plugins
 
 Connection plugins allow Ansible to connect to the target hosts so it can execute tasks on them. Ansible ships with many connection plugins, but only one can be used per host at a time.
 
-By default, Ansible ships with several connection plugins. The most commonly used are the :ref:`paramiko SSH<paramiko_ssh_connection>`, native ssh (just called :ref:`ssh<ssh_connection>`), and :ref:`local<local_connection>` connection types.  All of these can be used in playbooks and with :command:`/usr/bin/ansible` to decide how you want to talk to remote machines. If necessary, you can :ref:`create custom connection plugins <developing_connection_plugins>`.
+By default, Ansible ships with several connection plugins. The most commonly used are the :ref:`paramiko SSH<paramiko_connection>`, native ssh (just called :ref:`ssh<ssh_connection>`), and :ref:`local<local_connection>` connection types.  All of these can be used in playbooks and with :command:`/usr/bin/ansible` to decide how you want to talk to remote machines. If necessary, you can :ref:`create custom connection plugins <developing_connection_plugins>`.
 
 The basics of these connection types are covered in the :ref:`getting started<intro_getting_started>` section.
 
@@ -43,7 +43,7 @@ Plugins are self-documenting. Each plugin should document its configuration opti
 :ref:`ansible_host<magic_variables_and_hostvars>`
     The name of the host to connect to, if different from the :ref:`inventory <intro_inventory>` hostname.
 :ref:`ansible_port<faq_setting_users_and_ports>`
-    The ssh port number, for :ref:`ssh <ssh_connection>` and :ref:`paramiko_ssh <paramiko_ssh_connection>` it defaults to 22.
+    The ssh port number, for :ref:`ssh <ssh_connection>` and :ref:`paramiko_ssh <paramiko_connection>` it defaults to 22.
 :ref:`ansible_user<faq_setting_users_and_ports>`
     The default user name to use for log in. Most plugins default to the 'current user running Ansible'.
 
diff --git a/docs/docsite/rst/reference_appendices/release_and_maintenance.rst b/docs/docsite/rst/reference_appendices/release_and_maintenance.rst
index cf523778b9..551ff25fd3 100644
--- a/docs/docsite/rst/reference_appendices/release_and_maintenance.rst
+++ b/docs/docsite/rst/reference_appendices/release_and_maintenance.rst
@@ -41,8 +41,8 @@ The two community releases are related - the release cycle follows this pattern:
    * Work on new features continues in Collections
    * Individual Collections can make multiple minor and major releases
 
-#. Minor releases of three maintained ansible-core versions every three weeks (2.11.1)
-#. Minor releases of the single maintained Ansible community package version every three weeks (4.1.0)
+#. Minor releases of three maintained ansible-core versions every four weeks (2.11.1)
+#. Minor releases of the single maintained Ansible community package version every four weeks (4.1.0)
 #. Feature freeze on ansible-core
 #. Release candidate for ansible-core, testing, additional release candidates as necessary
 #. Release of the next ansible-core major version, cycle begins again
@@ -50,7 +50,7 @@ The two community releases are related - the release cycle follows this pattern:
 Ansible community package release cycle
 ---------------------------------------
 
-The Ansible community team typically releases two major versions of the community package per year, on a flexible release cycle that trails the release of ``ansible-core``. This cycle can be extended to allow for larger changes to be properly implemented and tested before a new release is made available. See :ref:`ansible_roadmaps` for upcoming release details. Between major versions, we release a new minor version of the Ansible community package every three weeks. Minor releases include new backwards-compatible features, modules and plugins, as well as bug fixes.
+The Ansible community team typically releases two major versions of the community package per year, on a flexible release cycle that trails the release of ``ansible-core``. This cycle can be extended to allow for larger changes to be properly implemented and tested before a new release is made available. See :ref:`ansible_roadmaps` for upcoming release details. Between major versions, we release a new minor version of the Ansible community package every four weeks. Minor releases include new backwards-compatible features, modules and plugins, as well as bug fixes.
 
 Starting with version 2.10, the Ansible community team guarantees maintenance for only one major community package release at a time. For example, when Ansible 4.0.0 gets released, the team will stop making new 3.x releases. Community members may maintain older versions if desired.
 
@@ -331,7 +331,7 @@ The Ansible community develops and maintains the features and functionality incl
 
  * Developers add new features and bug fixes to the individual Collections, following each Collection's rules on contributing.
  * Each new feature and each bug fix includes a changelog fragment describing the work.
- * Release engineers create a minor release for the current version every three weeks to ensure that the latest bug fixes are available to users.
+ * Release engineers create a minor release for the current version every four weeks to ensure that the latest bug fixes are available to users.
  * At the end of the development period, the release engineers announce which Collections, and which major version of each included Collection,  will be included in the next release of the Ansible community package. New Collections and new major versions may not be added after this, and the work of creating a new release begins.
 
 We generally do not provide fixes for unmaintained releases of the Ansible community package, however, there can sometimes be exceptions for critical issues.
@@ -346,7 +346,7 @@ The Ansible community develops and maintains ``ansible-core`` on GitHub_, with a
  * Developers add new features and bug fixes to the ``devel`` branch.
  * Each new feature and each bug fix includes a changelog fragment describing the work.
  * The development team backports bug fixes to one, two, or three stable branches, depending on the severity of the bug. They do not backport new features.
- * Release engineers create a minor release for each maintained version every three weeks to ensure that the latest bug fixes are available to users.
+ * Release engineers create a minor release for each maintained version every four weeks to ensure that the latest bug fixes are available to users.
  * At the end of the development period, the release engineers impose a feature freeze and the work of creating a new release begins.
 
 We generally do not provide fixes for unmaintained releases of ``ansible-core``, however, there can sometimes be exceptions for critical issues.
diff --git a/lib/ansible/plugins/filter/subelements.yml b/lib/ansible/plugins/filter/subelements.yml
index a2d1a9402e..818237e932 100644
--- a/lib/ansible/plugins/filter/subelements.yml
+++ b/lib/ansible/plugins/filter/subelements.yml
@@ -1,7 +1,7 @@
 DOCUMENTATION:
   name: subelements
   version_added: "2.7"
-  short_description: retuns a product of a list and it's elements
+  short_description: returns a product of a list and its elements
   positional: _input, _subelement, skip_missing
   description:
     - This produces a product of an object and the subelement values of that object, similar to the subelements lookup. This lets you specify individual subelements to use in a template I(_input).
diff --git a/lib/ansible/plugins/filter/unvault.yml b/lib/ansible/plugins/filter/unvault.yml
index 96a82ca8f7..7f91180aa3 100644
--- a/lib/ansible/plugins/filter/unvault.yml
+++ b/lib/ansible/plugins/filter/unvault.yml
@@ -28,7 +28,7 @@ EXAMPLES: |
   - name: save templated unvaulted data
     template: src=dump_template_data.j2 dest=/some/key/clear.txt
     vars:
-      template_data: '{{ secretdata|uvault(vaultsecret) }}'
+      template_data: '{{ secretdata|unvault(vaultsecret) }}'
 
 RETURN:
   _value: