From 3729cc57d0fbcac27492b579aedcc7d3b600a455 Mon Sep 17 00:00:00 2001
From: Matt Martz <matt@sivel.net>
Date: Tue, 30 Jan 2018 09:09:41 -0600
Subject: [PATCH] Add porting guide note about include inheritance change
 (#35199)

* Add porting guide note about include inheritance change. Fixes #35096

* Also make note of using import_* when possible

* Edited for clarity.
---
 docs/docsite/rst/porting_guide_2.5.rst | 46 +++++++++++++++++++++++++-
 1 file changed, 45 insertions(+), 1 deletion(-)

diff --git a/docs/docsite/rst/porting_guide_2.5.rst b/docs/docsite/rst/porting_guide_2.5.rst
index 109d7634d3c..36c94e5b24b 100644
--- a/docs/docsite/rst/porting_guide_2.5.rst
+++ b/docs/docsite/rst/porting_guide_2.5.rst
@@ -17,7 +17,51 @@ This document is part of a collection on porting. The complete list of porting g
 Playbook
 ========
 
-No notable changes.
+Dynamic includes and attribute inheritance
+------------------------------------------
+
+In Ansible version 2.4, the concept of dynamic includes (``include_tasks``) versus static imports (``import_tasks``) was introduced to clearly define the differences in how ``include`` works between dynamic and static includes. 
+
+All attributes applied to a dynamic ``include_*`` would only apply to the include itself, while attributes applied to a
+static ``import_*`` would be inherited by the tasks within.
+
+This separation was only partially implemented in Ansible version 2.4. As of Ansible version 2.5, this work is complete and the separation now behaves as designed; attributes applied to an ``include_*`` task will not be inherited by the tasks within. 
+
+To achieve an outcome similar to how Ansible worked prior to version 2.5, playbooks
+should use an explicit application of the attribute on the needed tasks, or use blocks to apply the attribute to many tasks. Another option is to use a static ``import_*`` when possible instead of a dynamic task.
+
+**OLD** In Ansible 2.4:
+
+.. code-block:: yaml
+
+    - include_tasks: "{{ ansible_distribution }}.yml"
+      tags:
+        - distro_include
+
+
+**NEW** In Ansible 2.5:
+
+Including task:
+
+.. code-block:: yaml
+
+    - include_tasks: "{{ ansible_distribution }}.yml"
+      tags:
+        - distro_include
+
+Included file:
+
+.. code-block:: yaml
+
+    - block:
+        - debug:
+            msg: "In included file"
+
+        - apt:
+            name: nginx
+            state: latest
+      tags:
+        - distro_include
 
 Deprecated
 ==========