[PR #1900/58659cf3 backport][stable-2.17] Tagging nuance

docs/docsite/rst/playbook_guide/playbooks_handlers.rst

@@ -211,4 +211,5 @@ Since Ansible 2.14 :ansplugin:`meta tasks <ansible.builtin.meta#module>` are all
 Limitations
 -----------
 
-A handler cannot run ``import_role`` or ``include_role``.
+A handler cannot run ``import_role`` nor ``include_role``.
+Handlers :ref:`ignore tags <tags_on_handlers>`.

docs/docsite/rst/playbook_guide/playbooks_tags.rst

@@ -9,9 +9,13 @@ If you have a large playbook, it may be useful to run only specific parts of it
    #. Add tags to your tasks, either individually or with tag inheritance from a block, play, role, or import.
    #. Select or skip tags when you run your playbook.
 
+.. note::
+    The ``tags`` keyword is part of 'pre processing' the playbook and has high precedence when deciding what tasks are available to consider for execution.
+
 .. contents::
    :local:
 
+
 Adding tags with the tags keyword
 =================================
 
@@ -81,6 +85,14 @@ You can apply the same tag to more than one individual task. This example tags s
 If you ran these four tasks in a playbook with ``--tags ntp``, Ansible would run the three tasks tagged ``ntp`` and skip the one task that does not have that tag.
 
 
+.. _tags_on_handlers:
+
+Adding tags to handlers
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Handlers are a special case of tasks that only execute when notified, as such they ignore all tags and cannot be selected for nor against.
+
+
 .. _tags_on_blocks:
 
 Adding tags to blocks
@@ -121,6 +133,23 @@ If you want to apply a tag to many, but not all, of the tasks in your play, use
      tags: filesharing
 
 
+Be mindful that ``tag`` selection supersedes most other logic, including ``block`` error handling. Setting a tag on a task in a ``block`` but not in the ``rescue`` or ``always`` section will prevent those from triggering if your tags selection does not cover the tasks in those sections.
+
+.. code-block:: yaml
+
+   - block:
+    - debug: msg=run with tag, but always fail
+      failed_when: true
+      tags: example
+
+    rescue:
+    - debug: msg=I always run because the block always fails, except if you select to only run 'example' tag
+
+    always:
+    - debug: msg=I always run, except if you select to only run 'example' tag
+
+This example runs all 3 tasks if called without specifying ``--tags`` but only runs the first task if you run with ``--tags example``.
+
 .. _tags_on_plays:
 
 Adding tags to plays
@@ -156,6 +185,8 @@ If all the tasks in a play should get the same tag, you can add the tag at the l
      tasks:
      ...
 
+.. note::
+    The tasks tagged will include all implicit tasks (like fact gathering) of the play, including those added via roles.
 
 .. _tags_on_roles:
 
@@ -192,6 +223,12 @@ or:
        # using YAML shorthand, this is equivalent to:
        # - { role: foo, tags: ["bar", "baz"] }
 
+
+.. note::
+    When adding a tag at the role level, not only are all tasks tagged, but the role's dependencies also have their tasks tagged.
+    See the tag inheritance section for details.
+
+
 .. _tags_on_includes:
 
 Adding tags to includes