.. include:: ../common_links.inc

v3.6 (18 May 2023)
******************

This document explains the changes made to Iris for this release
(:doc:`View all changes <index>`.)


.. dropdown:: v3.6 Release Highlights
    :color: primary
    :icon: info
    :animate: fade-in
    :open:

    We're so excited about our recent support for **delayed saving of lazy data
    to netCDF** (:pull:`5191`) that we're celebrating this important step change
    in behavour with its very own dedicated release 🥳

    By using ``iris.save(..., compute=False)`` you can now save to multiple NetCDF files
    in parallel.  See the new ``compute`` keyword in :func:`iris.fileformats.netcdf.save`.
    This can share and re-use any common (lazy) result computations, and it makes much
    better use of resources during any file-system waiting (i.e., it can use such periods
    to progress the *other* saves).

    Usage example::

       # Create output files with delayed data saving.
       delayeds = [
           iris.save(cubes, filepath, compute=False)
           for cubes, filepath in zip(output_cubesets, output_filepaths)
       ]
       # Complete saves in parallel.
       dask.compute(*delayeds)

    This advance also includes **another substantial benefit**, because NetCDF saves can
    now use a
    `Dask.distributed scheduler <https://docs.dask.org/en/stable/scheduling.html>`_.
    With `Distributed <https://distributed.dask.org/en/stable/>`_ you can parallelise the
    saves across a whole cluster.  Whereas previously, the NetCDF saving *only* worked with
    a "threaded" scheduler, limiting it to a single CPU.

    We're so super keen for the community to leverage the benefit of this new
    feature within Iris that we've brought this release forward several months.
    As a result, this minor release of Iris is intentionally light in content.
    However, there are some other goodies available for you to enjoy, such as:

    * Performing lazy arithmetic with an Iris :class:`~iris.cube.Cube` and a
      :class:`dask.array.Array`, and
    * Various improvements to our documentation resulting from adoption of
      `sphinx-design`_ and `sphinx-apidoc`_.

    As always, get in touch with us on :issue:`GitHub<new/choose>`, particularly
    if you have any feedback with regards to delayed saving, or have any issues
    or feature requests for improving Iris. Enjoy!


v3.6.1 (26 June 2023)
=====================

.. dropdown:: v3.6.1 Patches
   :color: primary
   :icon: alert
   :animate: fade-in

   📢 **Announcements**

   Welcome and congratulations to `@sloosvel`_ who made their first contribution to
   Iris! 🎉

   The patches in this release of Iris include:

   ✨ **Features**

   #. `@rcomer`_ rewrote :func:`~iris.util.broadcast_to_shape` so it now handles
      lazy data. This pull-request has been included to support :pull:`5341`.
      (:pull:`5307`) [``pre-v3.7.0``]

   🐛 **Bugs Fixed**

   #. `@stephenworsley`_ fixed :meth:`~iris.cube.Cube.convert_units` to allow unit
      conversion of lazy data when using a `Distributed`_ scheduler.
      (:issue:`5347`, :pull:`5349`)

   #. `@schlunma`_ fixed a bug in the concatenation of cubes with aux factories
      which could lead to a `KeyError` due to dependencies that have not been
      properly updated.
      (:issue:`5339`, :pull:`5340`)

   #. `@schlunma`_ fixed a bug which realized all weights during weighted
      aggregation. Now weighted aggregation is fully lazy again.
      (:issue:`5338`, :pull:`5341`)

   🚀 **Performance Enhancements**

   #. `@sloosvel`_ improved :meth:`~iris.cube.CubeList.concatenate_cube` and
      :meth:`~iris.cube.CubeList.concatenate` to ensure that lazy auxiliary coordinate
      points and bounds are not realized. This change now allows cubes with
      high-resolution auxiliary coordinates to concatenate successfully whilst using a
      minimal in-core memory footprint.
      (:issue:`5115`, :pull:`5142`)

   Note that, the above contribution labelled with ``pre-v3.7.0`` is part of the
   forthcoming Iris ``v3.7.0`` release, but requires to be included in this patch
   release.


📢 Announcements
================

#. `@bjlittle`_ added the community `Contributor Covenant`_ code of conduct.
   (:pull:`5291`)


✨ Features
===========

#. `@pp-mo`_ and  `@lbdreyer`_ supported delayed saving of lazy data, when writing to
   the netCDF file format.  See :ref:`delayed netCDF saves <delayed_netcdf_save>`.
   Also with significant input from `@fnattino`_.
   (:pull:`5191`)

#. `@rcomer`_ tweaked binary operations so that dask arrays may safely be passed
   to arithmetic operations and :func:`~iris.util.mask_cube`. (:pull:`4929`)


🐛 Bugs Fixed
=============

#. `@rcomer`_ enabled automatic replacement of a Matplotlib
   :class:`~matplotlib.axes.Axes` with a Cartopy
   :class:`~cartopy.mpl.geoaxes.GeoAxes` when the ``Axes`` is on a
   :class:`~matplotlib.figure.SubFigure`. (:issue:`5282`, :pull:`5288`)


💣 Incompatible Changes
=======================

#. N/A


🚀 Performance Enhancements
===========================

#. N/A


🔥 Deprecations
===============

#. N/A


🔗 Dependencies
===============

#. `@rcomer`_ and `@bjlittle`_ (reviewer) added testing support for python
   3.11. (:pull:`5226`)

#. `@rcomer`_ dropped support for python 3.8, in accordance with the NEP29_
   recommendations (:pull:`5226`)

#. `@trexfeathers`_ introduced the ``libnetcdf !=4.9.1`` and ``numpy !=1.24.3``
   pins (:pull:`5274`)


📚 Documentation
================

#. `@tkknight`_ migrated to `sphinx-design`_ over the legacy `sphinx-panels`_.
   (:pull:`5127`)

#. `@tkknight`_ updated the ``make`` target for ``help`` and added
   ``livehtml`` to auto generate the documentation when changes are detected
   during development. (:pull:`5258`)

#. `@tkknight`_ updated the :ref:`installing_from_source` instructions to use
   ``pip``.  (:pull:`5273`)

#. `@tkknight`_ removed the legacy custom sphinx extensions that generate the
   API documentation.  Instead use a less complex approach via
   `sphinx-apidoc`_. (:pull:`5264`)

#. `@trexfeathers`_ re-wrote the :ref:`iris_development_releases` documentation
   for clarity, and wrote a step-by-step
   :doc:`/developers_guide/release_do_nothing` for the release process.
   (:pull:`5134`)

#. `@trexfeathers`_ and `@tkknight`_ added a dark-mode friendly logo.
   (:pull:`5278`)


💼 Internal
===========

#. `@bjlittle`_ added the `codespell`_ `pre-commit`_ ``git-hook`` to automate
   spell checking within the code-base. (:pull:`5186`)

#. `@bjlittle`_ and `@trexfeathers`_ (reviewer) added a `check-manifest`_
   GitHub Action and `pre-commit`_ ``git-hook`` to automate verification
   of assets bundled within a ``sdist`` and binary ``wheel`` of our
   `scitools-iris`_ PyPI package. (:pull:`5259`)

#. `@rcomer`_ removed a now redundant copying workaround from Resolve testing.
   (:pull:`5267`)

#. `@bjlittle`_ and `@trexfeathers`_ (reviewer) migrated ``setup.cfg`` to
   ``pyproject.toml``, as motivated by `PEP-0621`_. (:pull:`5262`)

#. `@bjlittle`_ adopted `pypa/build`_ recommended best practice to build a
   binary ``wheel`` from the ``sdist``. (:pull:`5266`)

#. `@trexfeathers`_ enabled on-demand benchmarking of Pull Requests; see
   :ref:`here <on_demand_pr_benchmark>`. (:pull:`5286`)


.. comment
    Whatsnew author names (@github name) in alphabetical order. Note that,
    core dev names are automatically included by the common_links.inc:

.. _@fnattino: https://github.com/fnattino
.. _@sloosvel: https://github.com/sloosvel


.. comment
    Whatsnew resources in alphabetical order:

.. _sphinx-panels: https://github.com/executablebooks/sphinx-panels
.. _sphinx-design: https://github.com/executablebooks/sphinx-design
.. _check-manifest: https://github.com/mgedmin/check-manifest
.. _PEP-0621: https://peps.python.org/pep-0621/
.. _pypa/build: https://pypa-build.readthedocs.io/en/stable/
.. _NEP29: https://numpy.org/neps/nep-0029-deprecation_policy.html
.. _Contributor Covenant: https://www.contributor-covenant.org/version/2/1/code_of_conduct/
.. _Distributed: https://distributed.dask.org/en/stable/