deprecated include

added docs for new actions that take over include duties

(cherry picked from commit 8799038a895ed0ff230e2aa0629c4b83e8f15cf1)

7 files changed, 276 insertions, 7 deletions

diff --git a/lib/ansible/cli/doc.py b/lib/ansible/cli/doc.py
index 02ee8a534a..556a7551f8 100644
--- a/lib/ansible/cli/doc.py
+++ b/lib/ansible/cli/doc.py
@@ -417,7 +417,12 @@ class DocCLI(CLI):
         text.append("%s\n" % textwrap.fill(CLI.tty_ify(desc), limit, initial_indent=opt_indent, subsequent_indent=opt_indent))
 
         if 'deprecated' in doc and doc['deprecated'] is not None and len(doc['deprecated']) > 0:
-            text.append("DEPRECATED: \n%s\n" % doc.pop('deprecated'))
+            text.append("DEPRECATED: \n")
+            if isinstance(doc['deprecated'], dict):
+                text.append("\tReason: %(why)s\n\tScheduled removal: Ansible %(version)s\n\tAlternatives: %(alternative)s" % doc.pop('deprecated'))
+            else:
+                text.append("%s" % doc.pop('deprecated'))
+            text.append("\n")
 
         try:
             support_block = self.get_support_block(doc)
diff --git a/lib/ansible/modules/utilities/logic/include.py b/lib/ansible/modules/utilities/logic/_include.py
index ab3aef7898..65dd331490 100644
--- a/lib/ansible/modules/utilities/logic/include.py
+++ b/lib/ansible/modules/utilities/logic/_include.py
@@ -8,7 +8,7 @@ __metaclass__ = type
 
 
 ANSIBLE_METADATA = {'metadata_version': '1.1',
-                    'status': ['preview'],
+                    'status': ['deprecated'],
                     'supported_by': 'core'}
 
 
@@ -18,6 +18,8 @@ author:
     - "Ansible Core Team (@ansible)"
 module: include
 short_description: include a play or task list.
+deprecated:
+    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.  As alternatives use include_tasks, import_plays, 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 normally run (in play).
diff --git a/lib/ansible/modules/utilities/logic/import_plays.py b/lib/ansible/modules/utilities/logic/import_plays.py
new file mode 100644
index 0000000000..3ccab82b8d
--- /dev/null
+++ b/lib/ansible/modules/utilities/logic/import_plays.py
@@ -0,0 +1,55 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+# Copyright:  Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import absolute_import, division, print_function
+__metaclass__ = type
+
+
+ANSIBLE_METADATA = {'metadata_version': '1.1',
+                    'status': ['preview'],
+                    'supported_by': 'core'}
+
+
+DOCUMENTATION = '''
+---
+author:
+    - "Ansible Core Team (@ansible)"
+module: import_plays
+short_description: import a playbook.
+description:
+     - Includes a file with a list of plays to be executed.
+     - Files with a list of plays can only be included at the top level, you cannot use this action inside a Play.
+version_added: "2.4"
+options:
+  free-form:
+    description:
+        - This action allows you to specify the name of the file directly w/o any other options.
+notes:
+    - This is really not a module, this is a feature of the Ansible Engine, as such it cannot be overridden the same way a module can.
+'''
+
+EXAMPLES = """
+- name: include a play after another play
+  hosts: localhost
+  tasks:
+    - debug:
+        msg: "play1"
+
+- import_plays: otherplays.yml
+
+
+- name: This DOES NOT WORK
+  hosts: all
+  tasks:
+    - debug:
+        msg: task1
+
+    - name: This failes because I'm inside a play already
+      import_plays: stuff.yml
+"""
+
+RETURN = """
+# this module does not return anything except plays to execute
+"""
diff --git a/lib/ansible/modules/utilities/logic/import_role.py b/lib/ansible/modules/utilities/logic/import_role.py
new file mode 100644
index 0000000000..8a56872844
--- /dev/null
+++ b/lib/ansible/modules/utilities/logic/import_role.py
@@ -0,0 +1,93 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+# Copyright: Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import absolute_import, division, print_function
+__metaclass__ = type
+
+
+ANSIBLE_METADATA = {'metadata_version': '1.1',
+                    'status': ['preview'],
+                    'supported_by': 'core'}
+
+
+DOCUMENTATION = '''
+---
+author:
+    - "Ansible Core Team (@ansible)"
+module: import_role
+short_description: Import a role into a play
+description:
+     - Mostly like the `roles:` keyword this action loads a role, but it allows you to control when the tasks run in between other playbook tasks.
+     - Most keyworkds, loops and conditionals will not be applied to this action, but to the imported tasks instead.
+       If you want the opposite behaviour, use M(import_role) instead.
+version_added: "2.4"
+options:
+  name:
+    description:
+      - The name of the role to be executed.
+    required: True
+  tasks_from:
+    description:
+      - "File to load from a Role's tasks/ directory."
+    required: False
+    default: 'main'
+  vars_from:
+    description:
+      - "File to load from a Role's vars/ directory."
+    required: False
+    default: 'main'
+  defaults_from:
+    description:
+      - "File to load from a Role's defaults/ directory."
+    required: False
+    default: 'main'
+  allow_duplicates:
+    description:
+      - Overrides the role's metadata setting to allow using a role more than once with the same parameters.
+    required: False
+    default: True
+  private:
+    description:
+      - If True the variables from defaults/ and vars/ in a role will not be made available to the rest of the play.
+    default: None
+notes:
+    - Handlers are made available to the whole play.
+'''
+
+EXAMPLES = """
+- hosts: all
+  tasks:
+    - import_role:
+       name: myrole
+
+    - name: Run tasks/other.yml instead of 'main'
+      import_role:
+        name: myrole
+        tasks_from: other
+
+    - name: Pass variables to role
+      import_role:
+        name: myrole
+      vars:
+        rolevar1: 'value from task'
+
+    - name: Apply loop to each task in role
+      import_role:
+        name: myrole
+      with_items:
+        - '{{ roleinput1 }}'
+        - '{{ roleinput2 }}'
+      loop_control:
+        loop_var: roleinputvar
+
+    - name: Apply condition to each task in role
+      import_role:
+        name: myrole
+      when: not idontwanttorun
+"""
+
+RETURN = """
+# this module does not return anything except tasks to execute
+"""
diff --git a/lib/ansible/modules/utilities/logic/import_tasks.py b/lib/ansible/modules/utilities/logic/import_tasks.py
new file mode 100644
index 0000000000..d7770eb1fc
--- /dev/null
+++ b/lib/ansible/modules/utilities/logic/import_tasks.py
@@ -0,0 +1,58 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+# Copyright:  Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import absolute_import, division, print_function
+__metaclass__ = type
+
+
+ANSIBLE_METADATA = {'metadata_version': '1.1',
+                    'status': ['preview'],
+                    'supported_by': 'core'}
+
+
+DOCUMENTATION = '''
+---
+author:
+    - "Ansible Core Team (@ansible)"
+module: import_tasks
+short_description: import a task list.
+description:
+     - Imports a list of tasks to be added to the current playbook for subsequent execution.
+version_added: "2.4"
+options:
+  free-form:
+    description:
+        - This action allows you to specify the name of the file directly w/o any other options.
+        - Any loops, conditionals and most other keywords will be applied to the included tasks, not to this statement itself.
+        - If you need any of those to apply to this action, use M(include_tasks) instead.
+notes:
+    - This is really not a module, this is a feature of the Ansible Engine, as such it cannot be overridden the same way a module can.
+'''
+
+EXAMPLES = """
+# include task list in play
+- hosts: all
+  tasks:
+    - debug:
+        msg: task1
+
+    - import_tasks: stuff.yml
+
+    - debug:
+        msg: task10
+
+# apply conditional to all imported tasks
+- hosts: all
+  tasks:
+    - debug:
+        msg: task1
+
+    - include: stuff.yml"
+      when: hostvar is defined
+"""
+
+RETURN = """
+# this module does not return anything except tasks to execute
+"""
diff --git a/lib/ansible/modules/utilities/logic/include_role.py b/lib/ansible/modules/utilities/logic/include_role.py
index b56e8eb3b1..0ff592ac3c 100644
--- a/lib/ansible/modules/utilities/logic/include_role.py
+++ b/lib/ansible/modules/utilities/logic/include_role.py
@@ -53,11 +53,10 @@ options:
     default: None
 notes:
     - Handlers are made available to the whole play.
-    - simple dependencies seem to work fine.
-    - As with C(include) this task can be static or dynamic, If static it implies that it won't need templating nor loops nor conditionals and will
-      show included tasks in the --list options. Ansible will try to autodetect what is needed, but you can set `static` to `yes` or `no` at task
-      level to control this.
-    - This module is also supported for Windows targets.
+    - Before 2.4, as with C(include), this task could be static or dynamic, If static it implied that it won't need templating nor loops nor conditionals
+      and will show included tasks in the --list options.
+      Ansible would try to autodetect what is needed, but you can set `static` to `yes` or `no` at task level to control this.
+    - After 2.4, you can use M(import_role) for 'static' behaviour and this action for 'dynamic' one.
 '''
 
 EXAMPLES = """
diff --git a/lib/ansible/modules/utilities/logic/include_tasks.py b/lib/ansible/modules/utilities/logic/include_tasks.py
new file mode 100644
index 0000000000..2eaa9bdade
--- /dev/null
+++ b/lib/ansible/modules/utilities/logic/include_tasks.py
@@ -0,0 +1,57 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+# Copyright:  Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import absolute_import, division, print_function
+__metaclass__ = type
+
+
+ANSIBLE_METADATA = {'metadata_version': '1.1',
+                    'status': ['preview'],
+                    'supported_by': 'core'}
+
+
+DOCUMENTATION = '''
+---
+author:
+    - "Ansible Core Team (@ansible)"
+module: include_tasks
+short_description: dynamically include a task list.
+description:
+     - Includes a file with a list of tasks to be executed in the current playbook.
+version_added: "2.4"
+options:
+  free-form:
+    description:
+      - This action allows you to specify the name of the file directly w/o any other options.
+      - Unlike M(import_tasks) this action will be affected by most keywords, including loops and conditionals.
+notes:
+  - This is really not a module, this is a feature of the Ansible Engine, as such it cannot be overridden the same way a module can.
+'''
+
+EXAMPLES = """
+# include task list in play
+- hosts: all
+  tasks:
+    - debug:
+        msg: task1
+
+    - include_tasks: stuff.yml
+
+    - debug:
+        msg: task10
+
+# dyanmic include task list in play
+- hosts: all
+  tasks:
+    - debug:
+        msg: task1
+
+    - include_tasks: "{{ hostvar }}.yml"
+      when: hostvar is defined
+"""
+
+RETURN = """
+# this module does not return anything except tasks to execute
+"""