never tags docs and test (#35964)

* fufilling the promise

* moved changes

* Copy edit

(cherry picked from commit 0cf70a8970)

docs/docsite/rst/user_guide/playbooks_tags.rst

@@ -129,11 +129,23 @@ Example::
           tags:
             - tag1
 
-There are another 3 special keywords for tags, ``tagged``, ``untagged`` and ``all``, which run only tagged, only untagged
-and all tasks respectively.
+.. versionadded:: 2.5
+
+Another special tag is ``never``, which will prevent a task from running unless a tag is specifically requested.
 
-By default ansible runs as if ``--tags all`` had been specified.
+Example::
+
+    tasks:
+      - debug: msg='{{ showmevar}}'
+        tags: [ 'never', 'debug' ]
+
+In this example, the task will only run when the ``debug`` or ``never`` tag is explicitly requested.
+
+
+There are another 3 special keywords for tags: ``tagged``, ``untagged`` and ``all``, which run only tagged, only untagged
+and all tasks respectively.
 
+By default, Ansible runs as if ``--tags all`` had been specified.
 
 .. seealso::
 

test/integration/targets/tags/runme.sh

@@ -35,3 +35,7 @@ export LC_ALL=en_US.UTF-8
 # Run a tag from a list of tags and always
 [ "$("${COMMAND[@]}" --tags café | grep -F Task_with | xargs)" = \
 "Task_with_always_tag TAGS: [always] Task_with_list_of_tags TAGS: [café, press]" ]
+
+# Run tag with never
+[ "$("${COMMAND[@]}" --tags donever | grep -F Task_with | xargs)" = \
+"Task_with_always_tag TAGS: [always] Task_with_never_tag TAGS: [donever, never]" ]

test/integration/targets/tags/test_tags.yml

@@ -20,3 +20,6 @@
       - press
     - name: Task_without_tag
       debug: msg=
+    - name: Task_with_never_tag
+      debug: msg=NEVER
+      tags: ['never', 'donever']