From 005833ab44ac074abe7d4c55693d1a1718c4b18a Mon Sep 17 00:00:00 2001
From: Sloane Hertel <19572925+s-hertel@users.noreply.github.com>
Date: Thu, 29 Jul 2021 14:55:50 -0400
Subject: [PATCH] Improve 2.10 role dependency deduplication documentation
 (#75258)

---
 .../rst/user_guide/playbooks_reuse_roles.rst  | 23 ++++++++++++++++++-
 1 file changed, 22 insertions(+), 1 deletion(-)

diff --git a/docs/docsite/rst/user_guide/playbooks_reuse_roles.rst b/docs/docsite/rst/user_guide/playbooks_reuse_roles.rst
index 56093d3da10..f65cbed948a 100644
--- a/docs/docsite/rst/user_guide/playbooks_reuse_roles.rst
+++ b/docs/docsite/rst/user_guide/playbooks_reuse_roles.rst
@@ -353,7 +353,7 @@ Ansible always executes role dependencies before the role that includes them. An
 Running role dependencies multiple times in one playbook
 --------------------------------------------------------
 
-Ansible treats duplicate role dependencies like duplicate roles listed under ``roles:``: Ansible only executes role dependencies once, even if defined multiple times, unless the parameters, tags, or when clause defined on the role are different for each definition. If two roles in a playbook both list a third role as a dependency, Ansible only runs that role dependency once, unless you pass different parameters, tags, when clause, or use ``allow_duplicates: true`` in the dependent (third) role. See :ref:`Galaxy role dependencies <galaxy_dependencies>` for more details.
+The ``roles`` keyword deduplicates identical role dependencies and only executes role dependencies once, even if defined multiple times. If two roles in a playbook both list a third role as a dependency, Ansible only runs that role dependency once, unless you pass different parameters, tags, when clause, or use ``allow_duplicates: true`` in the dependent (third) role. See :ref:`Galaxy role dependencies <galaxy_dependencies>` for more details.
 
 For example, a role named ``car`` depends on a role named ``wheel`` as follows:
 
@@ -405,6 +405,27 @@ The resulting order of execution would be as follows:
 
 To use ``allow_duplicates: true`` with role dependencies, you must specify it for the dependent role, not for the parent role. In the example above, ``allow_duplicates: true`` appears in the ``meta/main.yml`` of the ``tire`` and ``brake`` roles. The ``wheel`` role does not require ``allow_duplicates: true``, because each instance defined by ``car`` uses different parameter values.
 
+Role deduplication also affects ``tasks`` and ``post_tasks``, which run after ``roles``, but not subsequent plays. For example, if role A and role B have the common dependency role C, in the following example role C will run only once:
+
+.. code-block:: yaml
+
+   ---
+   - hosts: all
+     roles:
+       - A
+     tasks:
+       - include_role: name=B
+
+Note that in ansible-core versions before 2.11, ``include_role`` and ``import_role`` do not deduplicate dependencies. In this example, the common dependency role C will run twice:
+
+.. code-block:: yaml
+
+   ---
+   - hosts: all
+     tasks:
+       - include_role: name=A
+       - include_role: name=B
+
 .. note::
    See :ref:`playbooks_variables` for details on how Ansible chooses among variable values defined in different places (variable inheritance and scope).