Repository: ansible/ansible

Issue:
include is deprecated but import_* and include_* still flagged as preview
##### ISSUE TYPE
 Documentation Report

##### COMPONENT NAME
- include
- import_*
- include_*

##### ANSIBLE VERSION
 ```
ansible 2.4.2.0
  config file = /etc/ansible/ansible.cfg
  configured module search path = [u'/home/mchappel/.ansible/plugins/modules', u'/usr/share/ansible/plugins/modules']
  ansible python module location = /usr/lib/python2.7/site-packages/ansible
  executable location = /usr/bin/ansible
  python version = 2.7.5 (default, May  3 2017, 07:55:04) [GCC 4.8.5 20150623 (Red Hat 4.8.5-14)]
```

##### SUMMARY
When running playbooks with an "include" statement, Ansible spits out a deprecation warning.

Currently import_* and include_* are still flagged as "preview" in the documentation, implying that people should avoid using them.  This is a very inconsistent message to send.  Either people should be using them and expect them to be stable, or include shouldn't be deprecated yet.


Discussion:
Files identified in the description:
* [lib/ansible/modules/utilities/logic/_include.py](https://github.com/ansible/ansible/blob/devel/lib/ansible/modules/utilities/logic/_include.py)

If these files are inaccurate, please update the `component name` section of the description or use the `!component` bot command.

[click here for bot help](https://github.com/ansible/ansibullbot/blob/master/ISSUE_HELP.md)
<!--- boilerplate: components_banner --->
@tremble Greetings! Thanks for taking the time to open this issue. In order for the community to handle your issue effectively, we need a bit more information. 

Here are the items we could not find in your description:
- ansible version

Please set the description of this issue with this template:
https://raw.githubusercontent.com/ansible/ansible/devel/.github/ISSUE_TEMPLATE.md

[click here for bot help](https://github.com/ansible/ansibullbot/blob/master/ISSUE_HELP.md)
<!--- boilerplate: issue_missing_data --->
!component +lib/ansible/modules/utilities/logic/import_playbook.py
!component +lib/ansible/modules/utilities/logic/import_role.py
!component +lib/ansible/modules/utilities/logic/import_tasks.py
!component +lib/ansible/modules/utilities/logic/include_role.py
!component +lib/ansible/modules/utilities/logic/include_tasks.py
Files identified in the description:
* [lib/ansible/modules/utilities/logic/_include.py](https://github.com/ansible/ansible/blob/devel/lib/ansible/modules/utilities/logic/_include.py)
* [lib/ansible/modules/utilities/logic/import_playbook.py](https://github.com/ansible/ansible/blob/devel/lib/ansible/modules/utilities/logic/import_playbook.py)
* [lib/ansible/modules/utilities/logic/import_role.py](https://github.com/ansible/ansible/blob/devel/lib/ansible/modules/utilities/logic/import_role.py)
* [lib/ansible/modules/utilities/logic/import_tasks.py](https://github.com/ansible/ansible/blob/devel/lib/ansible/modules/utilities/logic/import_tasks.py)
* [lib/ansible/modules/utilities/logic/include_role.py](https://github.com/ansible/ansible/blob/devel/lib/ansible/modules/utilities/logic/include_role.py)
* [lib/ansible/modules/utilities/logic/include_tasks.py](https://github.com/ansible/ansible/blob/devel/lib/ansible/modules/utilities/logic/include_tasks.py)

If these files are inaccurate, please update the `component name` section of the description or use the `!component` bot command.

[click here for bot help](https://github.com/ansible/ansibullbot/blob/master/ISSUE_HELP.md)
<!--- boilerplate: components_banner --->

Resolving patch:
diff --git a/lib/ansible/modules/utilities/logic/_include.py b/lib/ansible/modules/utilities/logic/include.py
similarity index 83%
rename from lib/ansible/modules/utilities/logic/_include.py
rename to lib/ansible/modules/utilities/logic/include.py
--- a/lib/ansible/modules/utilities/logic/_include.py
+++ b/lib/ansible/modules/utilities/logic/include.py
@@ -19,10 +19,6 @@
 author: Ansible Core Team (@ansible)
 module: include
 short_description: Include a play or task list
-deprecated:
-  removed_in: "2.8"
-  why: The include action was too confusing, dealing with both plays and tasks, being both dynamic and static. This module will be removed in version 2.8.
-  alternative: Use M(include_tasks), M(import_playbook), M(import_tasks).
 description:
   - Includes a file with a list of plays or tasks to be executed in the current playbook.
   - Files with a list of plays can only be included at the top level. Lists of tasks can only be included where tasks
@@ -41,7 +37,10 @@
       - This module allows you to specify the name of the file directly without any other options.
 notes:
   - This is a core feature of Ansible, rather than a module, and cannot be overridden like a module.
-  - This module is also supported for Windows targets.
+  - Include has some unintuitive behaviours depending on if it is running in a static or dynamic in play or in playbook context,
+    in an effort to clarify behaviours we are moving to a new set modules (M(include_tasks), M(include_role), M(import_playbook), M(import_tasks))
+    that have well established and clear behaviours.
+    This module will still be supported for some time but we are looking at deprecating it in the near future.
 '''
 
 EXAMPLES = """
diff --git a/lib/ansible/playbook/helpers.py b/lib/ansible/playbook/helpers.py
--- a/lib/ansible/playbook/helpers.py
+++ b/lib/ansible/playbook/helpers.py
@@ -112,9 +112,6 @@ def load_list_of_tasks(ds, play, block=None, role=None, task_include=None, use_h
             task_list.append(t)
         else:
             if 'include' in task_ds or 'import_tasks' in task_ds or 'include_tasks' in task_ds:
-                if 'include' in task_ds:
-                    display.deprecated("The use of 'include' for tasks has been deprecated. "
-                                       "Use 'import_tasks' for static inclusions or 'include_tasks' for dynamic inclusions")
 
                 if use_handlers:
                     include_class = HandlerTaskInclude


Test patch: