Backportapalooza 03 29 (#80350)

* Update special_variables.rst (#80210)

The usage of a glossary on this page will allow linking to a specific special variable, like on the glossary page, e.g.: https://docs.ansible.com/ansible/latest/reference_appendices/glossary.html#term-Idempotency

(cherry picked from commit 1491ec8019b064374145dace41b1320e04fb494b)

* uri: improve force_basic_auth documentation (#80211)

Add more details about what "true" and "false" mean for the
force_basic_auth setting. Give example scenarios when clients may want
to use this setting.

(cherry picked from commit fc8203168e964b26478a0f28b0e34d9b34331fde)

* Improve dirname and basename filter doc (#80054)

(cherry picked from commit 93beef053eabdb6ff2a9823bc8d0d1037671b1e3)

* Move Collection requirements to ansible/ansible (#80234)

(cherry picked from commit cba395243454b0a959edea20425618fe7b9be775)

* Add Ansible community 7.4.0 porting guide (#80338)

(cherry picked from commit 29e0a68af251981b97b6c594e52051652ef472d3)

* Add antsibull-changelog and antsibull-docs to other tools and programs page. (#80340)

(cherry picked from commit cf44c84396ee2afdd0258aed1d09d5eecde94d17)

---------

Co-authored-by: Benoît Geeraerts <10222438+b-enoit-be@users.noreply.github.com>
Co-authored-by: Ken Dreyer <kdreyer@redhat.com>
Co-authored-by: Daniel Ziegenberg <daniel@ziegenberg.at>
Co-authored-by: Anwesha Das <anwesha@das.community>
Co-authored-by: Felix Fontein <felix@fontein.de>

3 files changed, 16 insertions, 5 deletions

diff --git a/lib/ansible/modules/uri.py b/lib/ansible/modules/uri.py
index f68b86a530..7919b9b2f5 100644
--- a/lib/ansible/modules/uri.py
+++ b/lib/ansible/modules/uri.py
@@ -94,9 +94,16 @@ options:
   force_basic_auth:
     description:
       - Force the sending of the Basic authentication header upon initial request.
-      - The library used by the uri module only sends authentication information when a webservice
-        responds to an initial request with a 401 status. Since some basic auth services do not properly
-        send a 401, logins will fail.
+      - When this setting is C(false), this module will first try an unauthenticated request, and when the server replies
+        with an C(HTTP 401) error, it will submit the Basic authentication header.
+      - When this setting is C(true), this module will immediately send a Basic authentication header on the first
+        request.
+      - "Use this setting in any of the following scenarios:"
+      - You know the webservice endpoint always requires HTTP Basic authentication, and you want to speed up your
+        requests by eliminating the first roundtrip.
+      - The web service does not properly send an HTTP 401 error to your client, so Ansible's HTTP library will not
+        properly respond with HTTP credentials, and logins will fail.
+      - The webservice bans or rate-limits clients that cause any HTTP 401 errors.
     type: bool
     default: no
   follow_redirects:
diff --git a/lib/ansible/plugins/filter/basename.yml b/lib/ansible/plugins/filter/basename.yml
index 4e868df804..b6e31d232d 100644
--- a/lib/ansible/plugins/filter/basename.yml
+++ b/lib/ansible/plugins/filter/basename.yml
@@ -5,6 +5,8 @@ DOCUMENTATION:
   short_description: get a path's base name
   description:
     - Returns the last name component of a path, what is left in the string that is not 'dirname'.
+  notes:
+    - The result of this filter is different from the Unix basename program; where basename for C(/foo/bar/) returns C(bar), the basename filter returns an empty string (C('')).
   options:
     _input:
       description: A path.
@@ -15,7 +17,7 @@ DOCUMENTATION:
       plugin: ansible.builtin.dirname
 EXAMPLES: |
 
-  # To get the last name of a file path, like 'foo.txt' out of '/etc/asdf/foo.txt'
+  # To get the last name of a file path, like 'foo.txt' out of '/etc/asdf/foo.txt'.
   {{ mypath | basename }}
 
 RETURN:
diff --git a/lib/ansible/plugins/filter/dirname.yml b/lib/ansible/plugins/filter/dirname.yml
index 52f7d5d42e..4b8b0f7b29 100644
--- a/lib/ansible/plugins/filter/dirname.yml
+++ b/lib/ansible/plugins/filter/dirname.yml
@@ -5,6 +5,8 @@ DOCUMENTATION:
   short_description: get a path's directory name
   description:
     - Returns the 'head' component of a path, basically everything that is not the 'basename'.
+  notes:
+    - The result of this filter is different from the Unix dirname program; where dirname for C(/foo/bar/) returns C(/foo), the dirname filter returns the full path (C(/foo/bar/)).
   options:
     _input:
       description: A path.
@@ -15,7 +17,7 @@ DOCUMENTATION:
       plugin_type: filter
 EXAMPLES: |
 
-  # To get the dir name of a file path, like '/etc/asdf' out of '/etc/asdf/foo.txt'
+  # To get the dir name of a file path, like '/etc/asdf' out of '/etc/asdf/foo.txt'.
   {{ mypath | dirname }}
 
 RETURN: