From a290e187cc343c00b8b0f988a5b92dd884389b17 Mon Sep 17 00:00:00 2001
From: Sandra McCann <samccann@redhat.com>
Date: Sat, 30 Jul 2022 16:18:43 -0400
Subject: Docs Backportapalooza (#78379)

* Add missing colon to a snippet in complex data doc (#78349)

(cherry picked from commit e4087baa835df6046950a6579d2d2b56df75d12b)

* update the out-of-date ansible-test sanity ignores (#78342)

(cherry picked from commit 0f688f07af8d84cff71726eb855ee6ae5e6e352d)

* Update information on the Intro_patterns.rst (#78192)

(cherry picked from commit 85bc2bcfcdd233acf1f5d4309b8ecfcb997ff06c)

* add note about permission change (#78128)

(cherry picked from commit b6ec06ab2513770941eb7776ba2d5c6942065814)

Co-authored-by: Sviatoslav Sydorenko <wk@sydorenko.org.ua>
Co-authored-by: Muhammad Rafly Andrianza <luphieanza@gmail.com>
Co-authored-by: Tabah Baridule <dulemartins07@gmail.com>
---
 docs/docsite/rst/dev_guide/testing/sanity/ignores.rst |  4 +++-
 .../rst/user_guide/complex_data_manipulation.rst      |  2 +-
 docs/docsite/rst/user_guide/intro_patterns.rst        | 19 +++++++++++++++++++
 lib/ansible/plugins/doc_fragments/files.py            |  4 ++++
 4 files changed, 27 insertions(+), 2 deletions(-)

diff --git a/docs/docsite/rst/dev_guide/testing/sanity/ignores.rst b/docs/docsite/rst/dev_guide/testing/sanity/ignores.rst
index ea1d665b33..942b48f82e 100644
--- a/docs/docsite/rst/dev_guide/testing/sanity/ignores.rst
+++ b/docs/docsite/rst/dev_guide/testing/sanity/ignores.rst
@@ -74,7 +74,7 @@ If the named test uses error codes then the error code to ignore must be appende
 Below are some example ignore entries for an Ansible collection::
 
     roles/my_role/files/my_script.sh shellcheck:SC2154 # ignore undefined variable
-    plugins/modules/my_module.py validate-modules:E105 # ignore license check
+    plugins/modules/my_module.py validate-modules:missing-gplv3-license # ignore license check
     plugins/modules/my_module.py import-3.8 # needs update to support collections.abc on Python 3.8+
 
 It is also possible to skip a sanity test for a specific file.
@@ -86,6 +86,8 @@ Below are some example skip entries for an Ansible collection::
     plugins/module_utils/my_util.py validate-modules!skip # waiting for bug fix in module validator
     plugins/lookup/my_plugin.py compile-2.6!skip # Python 2.6 is not supported on the controller
 
+See the full list of :ref:`sanity tests <all_sanity_tests>`, which details the various tests and details how to fix identified issues.
+
 Ignore File Errors
 ------------------
 
diff --git a/docs/docsite/rst/user_guide/complex_data_manipulation.rst b/docs/docsite/rst/user_guide/complex_data_manipulation.rst
index 5bfce0c5b2..933fbf91d1 100644
--- a/docs/docsite/rst/user_guide/complex_data_manipulation.rst
+++ b/docs/docsite/rst/user_guide/complex_data_manipulation.rst
@@ -193,7 +193,7 @@ This example uses `Python argument list unpacking <https://docs.python.org/3/tut
 
     - hosts: all
       vars:
-        mygroups
+        mygroups:
           - prod
           - web
       tasks:
diff --git a/docs/docsite/rst/user_guide/intro_patterns.rst b/docs/docsite/rst/user_guide/intro_patterns.rst
index e163950184..3d0686da50 100644
--- a/docs/docsite/rst/user_guide/intro_patterns.rst
+++ b/docs/docsite/rst/user_guide/intro_patterns.rst
@@ -117,6 +117,25 @@ you must use the alias in your pattern. In the example above, you must use ``hos
 .. code-block:: console
 
    [WARNING]: Could not match supplied host pattern, ignoring: 127.0.0.2
+   
+Pattern processing order
+------------------------
+
+The processing is a bit special and happens in the following order: 
+1.  ``:`` and ``,``  
+2. `` &``
+3.  ``!``  
+
+This positioning only accounts for processing order inside each operation:
+``a:b:&c:!d:!e == &c:a:!d:b:!e == !d:a:!e:&c:b``
+
+All of these result in the following:
+
+Host in/is (a or b) AND host in/is all(c) AND host NOT in/is all(d, e).
+
+Now ``a:b:!e:!d:&c`` is a slight change as the ``!e`` gets processed before the ``!d``, though  this doesn't make much of a difference:
+
+Host in/is (a or b) AND host in/is all(c) AND host NOT in/is all(e, d).
 
 Advanced pattern options
 ------------------------
diff --git a/lib/ansible/plugins/doc_fragments/files.py b/lib/ansible/plugins/doc_fragments/files.py
index cf953b6171..2356bd72ce 100644
--- a/lib/ansible/plugins/doc_fragments/files.py
+++ b/lib/ansible/plugins/doc_fragments/files.py
@@ -34,10 +34,14 @@ options:
   owner:
     description:
     - Name of the user that should own the filesystem object, as would be fed to I(chown).
+    - When left unspecified, it uses the current user unless you are root, in which
+      case it can preserve the previous ownership.
     type: str
   group:
     description:
     - Name of the group that should own the filesystem object, as would be fed to I(chown).
+    - When left unspecified, it uses the current group of the current user unless you are root,
+      in which case it can preserve the previous ownership.
     type: str
   seuser:
     description:
-- 
cgit v1.2.1