Deprecate squeeze in GroupBy.

doc/user-guide/groupby.rst

@@ -177,28 +177,18 @@ This last line is roughly equivalent to the following::
         results.append(group - alt.sel(letters=label))
     xr.concat(results, dim='x')
 
-Squeezing
-~~~~~~~~~
+Iterating and Squeezing
+~~~~~~~~~~~~~~~~~~~~~~~
 
-When grouping over a dimension, you can control whether the dimension is
-squeezed out or if it should remain with length one on each group by using
-the ``squeeze`` parameter:
-
-.. ipython:: python
-
-    next(iter(arr.groupby("x")))
+Previously, Xarray defaulted to squeezing out dimensions of size one when iterating over
+a GroupBy object. This behaviour is being removed.
+You can always squeeze explicitly later with the Dataset or DataArray
+:py:meth:`~xarray.DataArray.squeeze` methods.
 
 .. ipython:: python
 
     next(iter(arr.groupby("x", squeeze=False)))
 
-Although xarray will attempt to automatically
-:py:attr:`~xarray.DataArray.transpose` dimensions back into their original order
-when you use apply, it is sometimes useful to set ``squeeze=False`` to
-guarantee that all original dimensions remain unchanged.
-
-You can always squeeze explicitly later with the Dataset or DataArray
-:py:meth:`~xarray.DataArray.squeeze` methods.
 
 .. _groupby.multidim:
 

doc/whats-new.rst

@@ -57,7 +57,8 @@ Breaking changes
 
 Deprecations
 ~~~~~~~~~~~~
-
+- The `squeeze` kwarg to GroupBy is now deprecated. (:issue:`2157`, :pull:`8507`)
+  By `Deepak Cherian <https://github.com/dcherian>`_.
 
 Bug fixes
 ~~~~~~~~~
@@ -141,7 +142,6 @@ Breaking changes
 
 Deprecations
 ~~~~~~~~~~~~
-
 - As part of an effort to standardize the API, we're renaming the ``dims``
   keyword arg to ``dim`` for the minority of functions which current use
   ``dims``. This started with :py:func:`xarray.dot` & :py:meth:`DataArray.dot`