Clarify how tagged roles work

This is a confusing part of roles and tags. Most people assume that tagging a role means that the tagged tasks inside the role will run based on the tags specified. But in reality, it tags the whole role with those tags.

1 files changed, 1 insertions, 0 deletions

diff --git a/docsite/rst/playbooks_roles.rst b/docsite/rst/playbooks_roles.rst
index 2cc98117a4..516403ac80 100644
--- a/docsite/rst/playbooks_roles.rst
+++ b/docsite/rst/playbooks_roles.rst
@@ -238,6 +238,7 @@ Finally, you may wish to assign tags to the roles you specify. You can do so inl
       roles:
         - { role: foo, tags: ["bar", "baz"] }
 
+Note that this *tags all of the tasks in that role with the tags specified*, overriding any tags that are specified inside the role. If you find yourself building a role with lots of tags and you want to call subsets of the role at different times, you should consider just splitting that role into multiple roles.
 
 If the play still has a 'tasks' section, those tasks are executed after roles are applied.