DOC: reorganize whats-new for 0.12.2 (#3060)

Author: shoyer

HOW_TO_RELEASE

@@ -5,8 +5,15 @@ Time required: about an hour.
  1. Ensure your master branch is synced to upstream:
        git pull upstream master
  2. Look over whats-new.rst and the docs. Make sure "What's New" is complete
-    (check the date!) and add a brief summary note describing the release at the
-    top.
+    (check the date!) and consider adding a brief summary note describing the
+    release at the top.
+    Things to watch out for:
+    - Important new features should be highlighted towards the top.
+    - Function/method references should include links to the API docs.
+    - Sometimes notes get added in the wrong section of whats-new, typically
+      due to a bad merge. Check for these before a release by using git diff,
+      e.g., ``git diff v0.X.Y whats-new.rst`` where 0.X.Y is the previous
+      release.
  3. If you have any doubts, run the full test suite one final time!
       py.test
  4. On the master branch, commit the release in git:

doc/whats-new.rst

@@ -15,84 +15,117 @@ What's New
 
 .. _whats-new.0.12.2:
 
-v0.12.2 (unreleased)
---------------------
+v0.12.2 (29 June 2019)
+----------------------
 
-Enhancements
-~~~~~~~~~~~~
+New functions/methods
+~~~~~~~~~~~~~~~~~~~~~
+
+- Two new functions, :py:func:`~xarray.combine_nested` and
+  :py:func:`~xarray.combine_by_coords`, allow for combining datasets along any
+  number of dimensions, instead of the one-dimensional list of datasets
+  supported by :py:func:`~xarray.concat`.
+
+  The new ``combine_nested`` will accept the datasets as a nested
+  list-of-lists, and combine by applying a series of concat and merge
+  operations. The new ``combine_by_coords`` instead uses the dimension
+  coordinates of datasets to order them.
+
+  :py:func:`~xarray.open_mfdataset` can use either ``combine_nested`` or
+  ``combine_by_coords`` to combine datasets along multiple dimensions, by
+  specifying the argument ``combine='nested'`` or ``combine='by_coords'``.
+
+  The older function :py:func:`~xarray.auto_combine` has been deprecated,
+  because its functionality has been subsumed by the new functions.
+  To avoid FutureWarnings switch to using ``combine_nested`` or
+  ``combine_by_coords``, (or set the ``combine`` argument in
+  ``open_mfdataset``). (:issue:`2159`)
+  By `Tom Nicholas <http://github.com/TomNicholas>`_.
+
+- :py:meth:`~xarray.DataArray.rolling_exp` and
+  :py:meth:`~xarray.Dataset.rolling_exp` added, similar to pandas'
+  ``pd.DataFrame.ewm`` method. Calling ``.mean`` on the resulting object
+  will return an exponentially weighted moving average.
+  By `Maximilian Roos <https://github.com/max-sixty>`_.
+
+- New :py:func:`DataArray.str <core.accessor_str.StringAccessor>` for string
+  related manipulations, based on ``pandas.Series.str``.
+  By `0x0L <https://github.com/0x0L>`_.
+
+- Added ``strftime`` method to ``.dt`` accessor, making it simpler to hand a
+  datetime ``DataArray`` to other code expecting formatted dates and times.
+  (:issue:`2090`). :py:meth:`~xarray.CFTimeIndex.strftime` is also now
+  available on :py:class:`CFTimeIndex`.
+  By `Alan Brammer <https://github.com/abrammer>`_ and
+  `Ryan May <https://github.com/dopplershift>`_.
 
-- New :py:meth:`~xarray.GroupBy.quantile` method. (:issue:`3018`)
+- :py:meth:`~xarray.core.GroupBy.quantile` is now a method of ``GroupBy``
+  objects  (:issue:`3018`).
   By `David Huard <https://github.com/huard>`_.
+
+- Argument and return types are added to most methods on ``DataArray`` and
+  ``Dataset``, allowing static type checking both within xarray and external
+  libraries. Type checking with `mypy <http://mypy-lang.org/>`_ is enabled in
+  CI (though not required yet).
+  By `Guido Imperiale <https://github.com/crusaderky>`_
+  and `Maximilian Roos <https://github.com/max-sixty>`_.
+
+Enhancements to existing functionality
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 - Add ``keepdims`` argument for reduce operations (:issue:`2170`)
   By `Scott Wales <https://github.com/ScottWales>`_.
-- netCDF chunksizes are now only dropped when original_shape is different,
-  not when it isn't found. (:issue:`2207`)
-  By `Karel van de Plassche <https://github.com/Karel-van-de-Plassche>`_.
-- Enable `@` operator for DataArray. This is equivalent to :py:meth:`DataArray.dot`
+- Enable ``@`` operator for DataArray. This is equivalent to :py:meth:`DataArray.dot`
   By `Maximilian Roos <https://github.com/max-sixty>`_.
 - Add ``fill_value`` argument for reindex, align, and merge operations
   to enable custom fill values. (:issue:`2876`)
   By `Zach Griffith <https://github.com/zdgriffith>`_.
-- :py:meth:`~xarray.DataArray.rolling_exp` and
-  :py:meth:`~xarray.Dataset.rolling_exp` added, similar to pandas' 
-  ``pd.DataFrame.ewm`` method. Calling ``.mean`` on the resulting object 
-  will return an exponentially weighted moving average.
-  By `Maximilian Roos <https://github.com/max-sixty>`_.
-- Character arrays' character dimension name decoding and encoding handled by
-  ``var.encoding['char_dim_name']`` (:issue:`2895`)
-  By `James McCreight <https://github.com/jmccreight>`_.
 - :py:meth:`DataArray.transpose` now accepts a keyword argument
   ``transpose_coords`` which enables transposition of coordinates in the
   same way as :py:meth:`Dataset.transpose`. :py:meth:`DataArray.groupby`
   :py:meth:`DataArray.groupby_bins`, and :py:meth:`DataArray.resample` now
   accept a keyword argument ``restore_coord_dims`` which keeps the order
   of the dimensions of multi-dimensional coordinates intact (:issue:`1856`).
   By `Peter Hausamann <http://github.com/phausamann>`_.
-- Clean up Python 2 compatibility in code (:issue:`2950`)
-  By `Guido Imperiale <https://github.com/crusaderky>`_.
-- Implement ``load_dataset()`` and ``load_dataarray()`` as alternatives to
-  ``open_dataset()`` and ``open_dataarray()`` to open, load into memory,
-  and close files, returning the Dataset or DataArray. These functions are
-  helpful for avoiding file-lock errors when trying to write to files opened
-  using ``open_dataset()`` or ``open_dataarray()``. (:issue:`2887`)
-  By `Dan Nowacki <https://github.com/dnowacki-usgs>`_.
-- Combining datasets along N dimensions:
-  Datasets can now be combined along any number of dimensions,
-  instead of just a one-dimensional list of datasets.
-
-  The new ``combine_nested`` will accept the datasets as a nested
-  list-of-lists, and combine by applying a series of concat and merge
-  operations. The new ``combine_by_coords`` will instead use the dimension
-  coordinates of the datasets to order them.
-
-  ``open_mfdataset`` can use either ``combine_nested`` or ``combine_by_coords`` to
-  combine datasets along multiple dimensions, by specifying the argument
-  `combine='nested'` or `combine='by_coords'`.
-
-  This means that the original function ``auto_combine`` is being deprecated.
-  To avoid FutureWarnings switch to using `combine_nested` or `combine_by_coords`,
-  (or set the `combine` argument in `open_mfdataset`). (:issue:`2159`)
-  By `Tom Nicholas <http://github.com/TomNicholas>`_.
 - Better warning message when supplying invalid objects to ``xr.merge``
   (:issue:`2948`).  By `Mathias Hauser <https://github.com/mathause>`_.
-- Added ``strftime`` method to ``.dt`` accessor, making it simpler to hand a
-  datetime ``DataArray`` to other code expecting formatted dates and times.
-  (:issue:`2090`). By `Alan Brammer <https://github.com/abrammer>`_ and
-  `Ryan May <https://github.com/dopplershift>`_.
-- Like :py:class:`pandas.DatetimeIndex`, :py:class:`CFTimeIndex` now supports a
-  :py:meth:`~xarray.CFTimeIndex.strftime` method to return an index of string
-  formatted datetimes. By `Alan Brammer <https://github.com/abrammer>`_.
-- Add ``.str`` accessor to DataArrays for string related manipulations.
-  By `0x0L <https://github.com/0x0L>`_.
 - Add ``errors`` keyword argument to :py:meth:`Dataset.drop` and :py:meth:`Dataset.drop_dims`
   that allows ignoring errors if a passed label or dimension is not in the dataset
   (:issue:`2994`).
   By `Andrew Ross <https://github.com/andrew-c-ross>`_.
-- Argument and return types are added to most methods on ``DataArray`` and ``Dataset``,
-  allowing static type checking both within xarray and external libraries.
-  Type checking with ``mypy`` is enabled in CI (though not required yet).
-  By `Guido Imperiale <https://github.com/crusaderky>`_ and `Maximilian Roos <https://github.com/max-sixty>`_. 
 
+IO related enhancements
+~~~~~~~~~~~~~~~~~~~~~~~
+
+- Implement :py:func:`~xarray.load_dataset` and
+  :py:func:`~xarray.load_dataarray` as alternatives to
+  :py:func:`~xarray.open_dataset` and :py:func:`~xarray.open_dataarray` to
+  open, load into memory, and close files, returning the Dataset or DataArray.
+  These functions are helpful for avoiding file-lock errors when trying to
+  write to files opened using ``open_dataset()`` or ``open_dataarray()``.
+  (:issue:`2887`)
+  By `Dan Nowacki <https://github.com/dnowacki-usgs>`_.
+- It is now possible to extend existing :ref:`io.zarr` datasets, by using
+  ``mode='a'`` and the new ``append_dim`` argument in
+  :py:meth:`~xarray.Dataset.to_zarr`.
+  By `Jendrik Jördening <https://github.com/jendrikjoe>`_,
+  `David Brochart <https://github.com/davidbrochart>`_,
+  `Ryan Abernathey <https://github.com/rabernat>`_ and
+  `Shikhar Goenka <https://github.com/shikharsg>`_.
+- ``xr.open_zarr`` now accepts manually specified chunks with the ``chunks=``
+  parameter. ``auto_chunk=True`` is equivalent to ``chunks='auto'`` for
+  backwards compatibility. The ``overwrite_encoded_chunks`` parameter is
+  added to remove the original zarr chunk encoding.
+  By `Lily Wang <https://github.com/lilyminium>`_.
+- netCDF chunksizes are now only dropped when original_shape is different,
+  not when it isn't found. (:issue:`2207`)
+  By `Karel van de Plassche <https://github.com/Karel-van-de-Plassche>`_.
+- Character arrays' character dimension name decoding and encoding handled by
+  ``var.encoding['char_dim_name']`` (:issue:`2895`)
+  By `James McCreight <https://github.com/jmccreight>`_.
+- open_rasterio() now supports rasterio.vrt.WarpedVRT with custom transform,
+  width and height (:issue:`2864`).
+  By `Julien Michel <https://github.com/jmichel-otb>`_.
 
 Bug fixes
 ~~~~~~~~~
@@ -145,8 +178,6 @@ Bug fixes
   (e.g., ``swap_dims``, ``isel``, ``reindex``, ``[]``) (:issue:`2842`,
   :issue:`2856`).
   By `Stephan Hoyer <https://github.com/shoyer>`_.
-- open_rasterio() now supports rasterio.vrt.WarpedVRT with custom transform, width and height (:issue:`2864`).
-  By `Julien Michel <https://github.com/jmichel-otb>`_.
 
 .. _whats-new.0.12.0:
 
@@ -220,21 +251,11 @@ Other enhancements
 - Upsampling an array via interpolation with resample is now dask-compatible,
   as long as the array is not chunked along the resampling dimension.
   By `Spencer Clark <https://github.com/spencerkclark>`_.
-  
 - :py:func:`xarray.testing.assert_equal` and
   :py:func:`xarray.testing.assert_identical` now provide a more detailed
   report showing what exactly differs between the two objects (dimensions /
   coordinates / variables / attributes)  (:issue:`1507`).
   By `Benoit Bovy <https://github.com/benbovy>`_.
-- Added append capability to the zarr store.
-  By `Jendrik Jördening <https://github.com/jendrikjoe>`_,
-  `David Brochart <https://github.com/davidbrochart>`_,
-  `Ryan Abernathey <https://github.com/rabernat>`_ and
-  `Shikhar Goenka<https://github.com/shikharsg>`_.
-- Resampling of standard and non-standard calendars indexed by
-  :py:class:`~xarray.CFTimeIndex` is now possible. (:issue:`2191`).
-  By `Jwen Fai Low <https://github.com/jwenfai>`_ and
-  `Spencer Clark <https://github.com/spencerkclark>`_.
 - Add ``tolerance`` option to ``resample()`` methods ``bfill``, ``pad``,
   ``nearest``. (:issue:`2695`)
   By `Hauke Schulz <https://github.com/observingClouds>`_.
@@ -245,11 +266,6 @@ Other enhancements
   By `Keisuke Fujii <https://github.com/fujiisoup>`_.
 - Added :py:meth:`~xarray.Dataset.drop_dims` (:issue:`1949`).
   By `Kevin Squire <https://github.com/kmsquire>`_.
-- ``xr.open_zarr`` now accepts manually specified chunks with the ``chunks=``
-  parameter. ``auto_chunk=True`` is equivalent to ``chunks='auto'`` for
-  backwards compatibility. The ``overwrite_encoded_chunks`` parameter is
-  added to remove the original zarr chunk encoding.
-  By `Lily Wang <https://github.com/lilyminium>`_.
 
 Bug fixes
 ~~~~~~~~~