deprecated include

changelogs/fragments/deprecate_include.yml

@@ -0,0 +1,2 @@
+deprecated_features:
+  - include action is deprecated in favor of include_tasks, import_tasks and import_playbook.

lib/ansible/modules/include.py → lib/ansible/modules/_include.py

@@ -25,6 +25,12 @@
     directive (which was added in Ansible 2.1) to bypass autodetection.
   - This module is also supported for Windows targets.
 version_added: "0.6"
+deprecated:
+    why: it has too many conflicting behaviours depending on keyword combinations and it was unclear how it should behave in each case.
+        new actions were developed that were specific about each case and related behaviours.
+    alternative: include_tasks, import_tasks, import_playbook
+    removed_in: "2.16"
+    removed_from_collection: 'ansible.builtin'
 options:
   free-form:
     description:

lib/ansible/playbook/included_file.py

@@ -70,6 +70,9 @@ def process_include_results(results, iterator, loader, variable_manager):
             original_task = res._task
 
             if original_task.action in C._ACTION_ALL_INCLUDES:
+                if original_task.action in C._ACTION_INCLUDE:
+                    display.deprecated('"include" is deprecated, use include_tasks/import_tasks/import_playbook instead', "2.16")
+
                 if original_task.loop:
                     if 'results' not in res._result:
                         continue

test/lib/ansible_test/_data/sanity/validate-modules/validate_modules/main.py

@@ -1122,7 +1122,7 @@ def _validate_docs(self):
             if not (filename_deprecated_or_removed or removed or deprecated or doc_deprecated):
                 mismatched_deprecation = False
             else:
-                if (filename_deprecated_or_removed and deprecated and doc_deprecated):
+                if (filename_deprecated_or_removed and doc_deprecated):
                     mismatched_deprecation = False
                 if (filename_deprecated_or_removed and removed and not (documentation_exists or examples_exist or returns_exist)):
                     mismatched_deprecation = False

test/lib/ansible_test/_data/sanity/validate-modules/validate_modules/schema.py

@@ -450,8 +450,7 @@ def deprecation_schema(for_collection):
             # Deprecation cycle changed at 2.4 (though not retroactively)
             # 2.3 -> removed_in: "2.5" + n for docs stub
             # 2.4 -> removed_in: "2.8" + n for docs stub
-            Required('removed_in'): Any(
-                "2.2", "2.3", "2.4", "2.5", "2.6", "2.8", "2.9", "2.10", "2.11", "2.12", "2.13", "2.14"),
+            Required('removed_in'): Any("2.12", "2.13", "2.14", "2.15", "2.16"),
         }
     version_schema.update(main_fields)