Deprecate squash_actions (#35978)

* Deprecate squash_actions

* Wording update

* Update wording and version

* Update versions to reflect 2.7 deprecation

* Add 2.7 porting guide

docs/docsite/rst/porting_guides/porting_guide_2.7.rst

@@ -0,0 +1,89 @@
+.. _porting_2.7_guide:
+
+*************************
+Ansible 2.7 Porting Guide
+*************************
+
+This section discusses the behavioral changes between Ansible 2.6 and Ansible 2.7.
+
+It is intended to assist in updating your playbooks, plugins and other parts of your Ansible infrastructure so they will work with this version of Ansible.
+
+We suggest you read this page along with `Ansible Changelog <https://github.com/ansible/ansible/blob/devel/CHANGELOG.md#2.7>`_ to understand what updates you may need to make.
+
+This document is part of a collection on porting. The complete list of porting guides can be found at :ref:`porting guides <porting_guides>`.
+
+.. contents:: Topics
+
+Playbook
+========
+
+No notable changes.
+
+Deprecated
+==========
+
+Using a loop on a package module via squash_actions
+---------------------------------------------------
+
+The use of ``squash_actions`` to invoke a package module, such as "yum", to only invoke the module once is deprecated, and will be removed in Ansible 2.11.
+
+Instead of relying on implicit squashing, tasks should instead supply the list directly to the ``name``, ``pkg`` or ``package`` parameter of the module. This functionality has been supported in most modules since Ansible 2.3.
+
+**OLD** In Ansible 2.6 (and earlier) the following task would invoke the "yum" module only 1 time to install multiple packages
+
+.. code-block:: yaml
+
+    - name: Install packages
+      yum:
+        name: "{{ item }}"
+        state: present
+      with_items: "{{ packages }}"
+
+**NEW** In Ansible 2.7 it should be changed to look like this:
+
+.. code-block:: yaml
+
+    - name: Install packages
+      yum:
+        name: "{{ packages }}"
+        state: present
+
+
+Modules
+=======
+
+Major changes in popular modules are detailed here
+
+
+
+Modules removed
+---------------
+
+The following modules no longer exist:
+
+
+Deprecation notices
+-------------------
+
+The following modules will be removed in Ansible 2.10. Please update your playbooks accordingly.
+
+
+Noteworthy module changes
+-------------------------
+
+No notable changes.
+
+Plugins
+=======
+
+No notable changes.
+
+Porting custom scripts
+======================
+
+No notable changes.
+
+Networking
+==========
+
+No notable changes.

lib/ansible/config/base.yml

@@ -970,6 +970,10 @@ DEFAULT_SQUASH_ACTIONS:
   - {key: squash_actions, section: defaults}
   type: list
   version_added: "2.0"
+  deprecated:
+    why: Loop squashing is deprecated and this configuration will no longer be used
+    version: "2.11"
+    alternatives: a list directly with the module argument
 DEFAULT_SSH_TRANSFER_METHOD:
   # TODO: move to ssh plugin
   default:

lib/ansible/executor/task_executor.py

@@ -377,9 +377,11 @@ class TaskExecutor:
                 if all(isinstance(o, string_types) for o in items):
                     final_items = []
 
+                    found = None
                     for allowed in ['name', 'pkg', 'package']:
                         name = self._task.args.pop(allowed, None)
                         if name is not None:
+                            found = allowed
                             break
 
                     # This gets the information to check whether the name field
@@ -397,6 +399,12 @@ class TaskExecutor:
                         # name/pkg or the name/pkg field doesn't have any variables
                         # and thus the items can't be squashed
                         if template_no_item != template_with_item:
+                            display.deprecated(
+                                'Invoking "%s" only once while using a loop via squash_actions is deprecated. '
+                                'Instead of using a loop to supply multiple items and specifying `%s: %s`, '
+                                'please use `%s: %r` and remove the loop' % (self._task.action, found, name, found, self._task.loop),
+                                version='2.11'
+                            )
                             for item in items:
                                 variables[loop_var] = item
                                 if self._task.evaluate_conditional(templar, variables):