Backportapalooza 03 16 (#80246)

* improve doc dependency install steps (#80120)

(cherry picked from commit 352010f9c3)

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

(cherry picked from commit 3216e071c7)

* docsite requirements path (#80134)

(cherry picked from commit 1055803c3a)

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

(cherry picked from commit 7ce951ff48)

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

(cherry picked from commit 12c1891ce6)

* Fixed typo (#80184)

`uvault` should be `unvault`

(cherry picked from commit cb2180e286)

* 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 507fd1bd60)

* Update connection.rst (#80194)

(cherry picked from commit 0937cc4862)

---------

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>

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
 
+Drop the ``--user`` option in the following commands if you use a virtual environment (venv/virtenv).
+
+#. Upgrade pip before installing dependencies (recommended).
+
    .. code-block:: bash
 
-    pip install --user -r requirements.txt
+      pip install --user --upgrade pip
-    pip install --user -r docs/docsite/requirements.txt
 
-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:
+#. Install Ansible dependencies.
 
    .. code-block:: bash
 
       pip install --user -r requirements.txt
-    pip install --user -r test/sanity/code-smell/docs-build.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::
 

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

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::

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'.
 

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 three maintained ansible-core versions every four weeks (2.11.1)
-#. Minor releases of the single maintained Ansible community package version every three weeks (4.1.0)
+#. 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.

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).

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: