From db9744d29ebd224a3a9abb24f4ac6eb73544e09b Mon Sep 17 00:00:00 2001
From: Matt Martz <matt@sivel.net>
Date: Tue, 3 Sep 2019 11:36:58 -0500
Subject: [PATCH] [stable-2.8] Add porting guide entry for gathering facts tag
 change (#61180) (#61555)

* Add porting guide entry for gathering facts tag change

(cherry picked from commit 0175620)

Co-authored-by: Matt Martz <matt@sivel.net>
---
 .../rst/porting_guides/porting_guide_2.8.rst  | 52 +++++++++++++++++++
 1 file changed, 52 insertions(+)

diff --git a/docs/docsite/rst/porting_guides/porting_guide_2.8.rst b/docs/docsite/rst/porting_guides/porting_guide_2.8.rst
index 5e81d029a83..e478f3f539b 100644
--- a/docs/docsite/rst/porting_guides/porting_guide_2.8.rst
+++ b/docs/docsite/rst/porting_guides/porting_guide_2.8.rst
@@ -69,6 +69,58 @@ Command line facts
 ``cmdline`` facts returned in system will be deprecated in favor of ``proc_cmdline``. This change handles special case where Kernel command line parameter contains multiple values with the same key.
 
 
+Gathering Facts
+---------------
+
+In Ansible 2.8 the implicit "Gathering Facts" task in a play was changed to
+obey play tags. Previous to 2.8, the "Gathering Facts" task would ignore play
+tags and tags supplied from the command line and always run in a task.
+
+The behavior change affects the following example play.
+
+.. code-block:: yaml
+
+    - name: Configure Webservers
+      hosts: webserver
+      tags:
+        - webserver
+      tasks:
+        - name: Install nginx
+          package:
+            name: nginx
+          tags:
+            - nginx
+
+In Ansible 2.8, if you supply ``--tags nginx``, the implicit
+"Gathering Facts" task will be skipped, as the task now inherits
+the tag of ``webserver`` instead of ``always``.
+
+If no play level tags are set, the "Gathering Facts" task will
+be given a tag of ``always`` and will effectively match prior
+behavior.
+
+You can achieve similar results to the pre-2.8 behavior, by
+using an explicit ``gather_facts`` task in your ``tasks`` list.
+
+.. code-block:: yaml
+
+    - name: Configure Webservers
+      hosts: webserver
+      gather_facts: false
+      tags:
+        - webserver
+      tasks:
+        - name: Gathering Facts
+          gather_facts:
+          tags:
+            - always
+
+        - name: Install nginx
+          package:
+            name: nginx
+          tags:
+            - nginx
+
 Python Interpreter Discovery
 ============================