Skip to content

"What's New" credit and referencing #3838

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
stephenworsley merged 17 commits into from
Sep 15, 2020
Merged

"What's New" credit and referencing #3838

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
18ad14a
Added names and PR refs to whatsnew.
trexfeathers Sep 10, 2020
d320565
More prescriptive instructions on whatsnew content.
trexfeathers Sep 10, 2020
596f31b
Reference GitHub names in whatsnew.
trexfeathers Sep 11, 2020
a042f20
Moved Internal to the bottom of the whatsnew categories.
trexfeathers Sep 11, 2020
b3ac712
Added missed whatsnew entries from pre-4761a10630b044aedb38f56f96ecff…
trexfeathers Sep 11, 2020
7dd6f0a
Fixed dependency position in whatsnew.
trexfeathers Sep 11, 2020
92b5b01
Moved Internal to the bottom of the whatsnew categories.
trexfeathers Sep 11, 2020
15ebb99
Update to what is expected of developers regarding whatsnews and pull…
trexfeathers Sep 11, 2020
5c8951b
Corrected latest.rst Dependencies heading.
trexfeathers Sep 11, 2020
47aff9e
Whatsnew entry.
trexfeathers Sep 11, 2020
2c35a39
Clearer emphasis for whats_new_contributions.rst.
trexfeathers Sep 11, 2020
88fb071
docstrings.rst sphinx pep inline markup.
trexfeathers Sep 11, 2020
08ee8ba
PR template consistent formatting with issue templates.
trexfeathers Sep 14, 2020
8158666
Improved the suggested whatsnew PR process.
trexfeathers Sep 14, 2020
3138a01
What's new guide typos.
trexfeathers Sep 14, 2020
d1038c4
latest.rst typos.
trexfeathers Sep 14, 2020
544d324
Improved linkcheck wording in whatsnew guide.
trexfeathers Sep 14, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 29 additions & 15 deletions docs/iris/src/developers_guide/documenting/whats_new_contributions.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ document are written by the developer most familiar with the change made.
The contribution should be included as part of the Iris Pull Request that
introduces the change.

The ``latest.rst`` and the past release notes are kept in
The ``latest.rst`` and the past release notes are kept in
``docs/iris/src/whatsnew/``.


Expand All @@ -23,27 +23,41 @@ contain multiple changes that are worth highlighting as contributions to the
what's new document.

Each contribution will ideally be written as a single concise bullet point
in a reStructuredText format with a trailing blank line. For example::
in a reStructuredText format. Where possible do not exceed **column 80** and
ensure that any subsequent lines of the same bullet point are aligned with the
first. The content should target an Iris user as the audience. The required
content, in order, is as follows:

* Fixed :issue:`9999`. Lorem ipsum dolor sit amet, consectetur adipiscing
elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
<blank line>
* Names of those who contributed the change e.g. ``Robert FitzRoy and Luke
Howard changed...``

Note that this example also cites the related issue, optionally you may also
include the pull request using the notation ``:pull:`9999```. Where possible
do not exceed **column 80** and ensure that any subsequent lines
of the same bullet point is aligned with the first.
* The new/changed behaviour

The content of the bullet point should highlight the change that has been made
to Iris, targeting an Iris user as the audience.
* Context to the change. Possible examples include: what this fixes, why
something was added, issue references (e.g. ``:issue:`9999```), more specific
detail on the change itself.

For inspiration that may include adding links to code please examine past
what's :ref:`iris_whatsnew` entries.
* Pull request references, bracketed, following the final period. E.g.
``(:pull:`1111`, :pull:`9999`)``

* A trailing blank line (standard reStructuredText bullet format)

For example::

* Robert FitzRoy and Luke Howard changed argument ``x`` to be optional in
:class:`~iris.module.class` and :meth:`iris.module.method`. This allows
greater flexibility as requested in :issue:`9999`. (:pull:`1111`,
:pull:`9999`)


The above example also demonstrates some of the possible syntax for including
links to code. For more inspiration on possible content and references please
examine past what's :ref:`iris_whatsnew` entries.

.. note:: The reStructuredText syntax will be checked as part of building
the documentation. Any warnings should be corrected.
the documentation. Any warnings should be corrected.
`travis-ci`_ will automatically build the documentation when
creating a pull request, however you can also manually
creating a pull request, however you can also manually
:ref:`build <contributing.documentation.building>` the documentation.

.. _travis-ci: https://travis-ci.org/github/SciTools/iris
Expand Down
230 changes: 129 additions & 101 deletions docs/iris/src/whatsnew/latest.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,90 +13,108 @@ This document explains the changes made to Iris for this release
Features
========

* The :mod:`~iris.fileformats.nimrod` module provides richer meta-data translation
when loading ``Nimrod`` data into cubes. This covers most known
operational use-cases.
* Stephen Moseley greatly enhanced the :mod:`~iris.fileformats.nimrod` module
to provide richer meta-data translation when loading ``Nimrod`` data into
cubes. This covers most known operational use-cases. (:pull:`3647`)

* Statistical operations :meth:`iris.cube.Cube.collapsed`,
:meth:`iris.cube.Cube.aggregated_by` and :meth:`iris.cube.Cube.rolling_window`
previously removed every :class:`iris.coord.CellMeasure` attached to the
cube. Now, a :class:`iris.coord.CellMeasure` will only be removed if it is
associated with an axis over which the statistic is being run.
* Stephen Worsley improved the handling of :class:`iris.coord.CellMeasure` in
the statistical operations :meth:`iris.cube.Cube.collapsed`,
:meth:`iris.cube.Cube.aggregated_by` and
:meth:`iris.cube.Cube.rolling_window`. These previously removed every
:class:`iris.coord.CellMeasure` attached to the cube. Now, a
:class:`iris.coord.CellMeasure` will only be removed if it is associated with
an axis over which the statistic is being run. (:pull:`3549`)

* Supporting ``Iris`` for both ``Python2`` and ``Python3`` resulted in pinning our
dependency on `Matplotlib`_ at ``v2.x``. Now that ``Python2`` support has
been dropped, ``Iris`` is free to use the latest version of `Matplotlib`_.
* Stephen Worsley, Patrick Peglar and Anna Booton added support for
`CF Ancillary Data`_ variables, which can be loaded from and saved to
NetCDF-CF files. Support for `Quality Flags`_ is also provided to ensure they
load and save with appropriate units. (:pull:`3800`)

* `CF Ancillary Data`_ variables are now supported, and can be loaded from and
saved to NetCDF-CF files. Support for `Quality Flags`_ is also provided to
ensure they load and save with appropriate units. See :pull:`3800`.

* Lazy regridding with the :class:`~iris.analysis.Linear`,
:class:`~iris.analysis.Nearest`, and
:class:`~iris.analysis.AreaWeighted` regridding schemes.
See :pull:`3701`.
* Bouwe Andela implemented lazy regridding for the
:class:`~iris.analysis.Linear`, :class:`~iris.analysis.Nearest`, and
:class:`~iris.analysis.AreaWeighted` regridding schemes. (:pull:`3701`)


Dependency Updates
==================

* Iris now supports the latest version of `Proj <https://github.com/OSGeo/PROJ>`_.
* Bill Little unpinned Iris to use the latest version of `Matplotlib`_.
Supporting ``Iris`` for both ``Python2`` and ``Python3`` had resulted in
pinning our dependency on `Matplotlib`_ at ``v2.x``. But this is no longer
necessary now that ``Python2`` support has been dropped. (:pull:`3468`)

* Stephen Worsley and Martin Yeo unpinned Iris to use the latest version of
`Proj <https://github.com/OSGeo/PROJ>`_. (:pull:`3762`)

* Iris now requires `Cartopy <https://github.com/SciTools/cartopy>`_ >= 0.18 in
* Stephen Worsley and Martin Yeo pinned Iris to require
`Cartopy <https://github.com/SciTools/cartopy>`_ >= 0.18, in
order to remain compatible with the latest version of `Matplotlib`_.
(:pull:`3762`)

* GDAL is removed from the extensions dependency group. We no longer consider it to
be an extension.
* Stephen Worsley and Martin Yeo removed GDAL from the extensions dependency
group. We no longer consider it to be an extension. (:pull:`3762`)

* Bill Little improved the developer set up process. Configuring Iris and
:ref:`installing_from_source` as a developer, with all the required package
dependencies is now easier with our curated conda environment YAML files.
(:pull:`3812`)

* Configuring Iris and :ref:`installing_from_source` as a developer, with all the
required package dependencies is now easier with our curated conda environment
YAML files. See :pull:`3812`.

Bugs Fixed
==========

* The method :meth:`~iris.Cube.cube.remove_coord` would fail to remove derived
coordinates, will now remove derived coordinates by removing aux_factories.
* Stephen Worsley fixed :meth:`~iris.Cube.cube.remove_coord` to now also remove
derived coordinates, by removing aux_factories. (:pull:`3641`)

* The ``__iter__()`` method in :class:`~iris.cube.Cube` was set to ``None``.
``TypeError`` is still raised if a :class:`~iris.cube.Cube` is iterated over
but ``isinstance(cube, collections.Iterable)`` now behaves as expected.
* Jon Seddon fixed ``isinstance(cube, collections.Iterable)`` to now behave as
expected if a :class:`~iris.cube.Cube` is iterated over, while also ensuring
that ``TypeError`` is still raised. (Fixed by setting the ``__iter__()``
method in :class:`~iris.cube.Cube` to ``None``). (:pull:`3656`)

* Concatenating cubes along an axis shared by cell measures would cause
concatenation to inappropriately fail. These cell measures are now
concatenated together in the resulting cube.
* Stephen Worsley enabled cube concatenation along an axis shared by cell
measures; these cell measures are now concatenated together in the resulting
cube. Such a scenario would previously cause concatenation to inappropriately
fail. (:pull:`3566`)

* Copying a cube would previously ignore any attached
:class:`~iris.coords.CellMeasure`. These are now copied over.
* Stephen Worsley newly included :class:`~iris.coords.CellMeasure`s in
:class:`~iris.cube.Cube` copy operations. Previously copying a
:class:`~iris.cube.Cube` would ignore any attached
:class:`~iris.coords.CellMeasure`. (:pull:`3546`)

* A :class:`~iris.coords.CellMeasure` requires a string ``measure`` attribute
to be defined, which can only have a value of ``area`` or ``volume``.
* Bill Little set a :class:`~iris.coords.CellMeasure`'s
``measure`` attribute to have a default value of ``area``.
Previously, the ``measure`` was provided as a keyword argument to
:class:`~iris.coords.CellMeasure` with an default value of ``None``, which
caused a ``TypeError`` when no ``measure`` was provided. The default value
of ``area`` is now used.
:class:`~iris.coords.CellMeasure` with a default value of ``None``, which
caused a ``TypeError`` when no ``measure`` was provided, since ``area`` or
``volume`` are the only accepted values. (:pull:`3533`)

* **All** plot types in `iris.plot` now use `matplotlib.dates.date2num
* Martin Yeo set **all** plot types in `iris.plot` to now use
`matplotlib.dates.date2num
<https://matplotlib.org/api/dates_api.html#matplotlib.dates.date2num>`_
to format date/time coordinates for use on a plot axis (previously
:meth:`~iris.plot.pcolor` and :meth:`~iris.plot.pcolormesh` did not include
this behaviour).
this behaviour). (:pull:`3762`)

* Date/time axis labels in `iris.quickplot` are now **always** based on the
``epoch`` used in `matplotlib.dates.date2num
* Martin Yeo changed date/time axis labels in `iris.quickplot` to now
**always** be based on the ``epoch`` used in `matplotlib.dates.date2num
<https://matplotlib.org/api/dates_api.html#matplotlib.dates.date2num>`_
(previously would take the unit from a time coordinate, if present, even
though the coordinate's value had been changed via ``date2num``).
(:pull:`3762`)

* Attributes of cell measures in NetCDF-CF files were being discarded during
loading. They are now available on the :class:`~iris.coords.CellMeasure` in
the loaded :class:`~iris.cube.Cube`. See :pull:`3800`.
* Patrick Peglar newly included attributes of cell measures in NETCDF-CF file
loading; they were previously being discarded. They are now available on the
:class:`~iris.coords.CellMeasure` in the loaded :class:`~iris.cube.Cube`.
(:pull:`3800`)


Incompatible Changes
====================

* The method :meth:`~iris.cube.CubeList.extract_strict`, and the ``strict``
* Patrick Peglar rationalised :class:`~iris.cube.CubeList` extraction
methods:

The method :meth:`~iris.cube.CubeList.extract_strict`, and the ``strict``
keyword to :meth:`~iris.cube.CubeList.extract` method have been removed, and
are replaced by the new routines :meth:`~iris.cube.CubeList.extract_cube` and
:meth:`~iris.cube.CubeList.extract_cubes`.
Expand All @@ -106,98 +124,108 @@ Incompatible Changes
consistent : :meth:`~iris.cube.CubeList.extract_cube` always returns a
:class:`~iris.cube.Cube`, and :meth:`~iris.cube.CubeList.extract_cubes`
always returns an :class:`iris.cube.CubeList` of a length equal to the
number of constraints.
number of constraints. (:pull:`3715`)

* The former function ``iris.analysis.coord_comparison`` has been removed.
* Patrick Peglar removed the former function ``iris.analysis.coord_comparison``.
(:pull:`3562`)

* The :func:`iris.experimental.equalise_cubes.equalise_attributes` function
has been moved from the :mod:`iris.experimental` module into the
* Bill Little moved the :func:`iris.experimental.equalise_cubes.equalise_attributes`
function from the :mod:`iris.experimental` module into the
:mod:`iris.util` module. Please use the :func:`iris.util.equalise_attributes`
function instead.
function instead. (:pull:`3527`)

* The :mod:`iris.experimental.concatenate` module has now been removed. In
* Bill Little removed the :mod:`iris.experimental.concatenate` module. In
``v1.6.0`` the experimental ``concatenate`` functionality was moved to the
:meth:`iris.cube.CubeList.concatenate` method. Since then, calling the
:func:`iris.experimental.concatenate.concatenate` function raised an
exception.
exception. (:pull:`3523`)

* When loading data from NetCDF-CF files, where a variable has no ``units``
property, the corresponding Iris object will have ``units='unknown'``.
Prior to Iris ``3.0.0``, these cases defaulted to ``units='1'``.
See :pull:`3795`.
* Stephen Worsley changed Iris objects loaded from NetCDF-CF files to have
``units='unknown'`` where the corresponding NetCDF variable has no ``units``
property. Previously these cases defaulted to ``units='1'``. (:pull:`3795`)


Internal
========

* Changed the numerical values in tests involving the Robinson projection due
to improvements made in `Proj <https://github.com/OSGeo/PROJ>`_ (see
* Stephen Worsley changed the numerical values in tests involving the Robinson
projection due to improvements made in `Proj <https://github.com/OSGeo/PROJ>`_.
(:pull:`3762`) (see also
`proj#1292 <https://github.com/OSGeo/PROJ/pull/1292>`_ and
`proj#2151 <https://github.com/OSGeo/PROJ/pull/2151>`_).
`proj#2151 <https://github.com/OSGeo/PROJ/pull/2151>`_)

* Change tests to account for more detailed descriptions of projections in
`GDAL <https://github.com/OSGeo/gdal>`_
(`see GDAL#1185 <https://github.com/OSGeo/gdal/pull/1185>`_).
* Stephen Worsley changed tests to account for more detailed descriptions of
projections in `GDAL <https://github.com/OSGeo/gdal>`_. (:pull:`3762`)
(`see also GDAL#1185 <https://github.com/OSGeo/gdal/pull/1185>`_)

* Change tests to account for `GDAL <https://github.com/OSGeo/gdal>`_ now
saving fill values for data without masked points.
* Stephen Worsley changed tests to account for
`GDAL <https://github.com/OSGeo/gdal>`_ now saving fill values for data
without masked points. (:pull:`3762`)

* Changed every graphics test that includes `Cartopy's coastlines
* Martin Yeo changed every graphics test that includes `Cartopy's coastlines
<https://scitools.org.uk/cartopy/docs/latest/matplotlib/
geoaxes.html?highlight=coastlines#cartopy.mpl.geoaxes.GeoAxes.coastlines>`_
to account for new adaptive coastline scaling (`see cartopy#1105
<https://github.com/SciTools/cartopy/pull/1105>`_).
to account for new adaptive coastline scaling. (:pull:`3762`) (`see also
cartopy#1105 <https://github.com/SciTools/cartopy/pull/1105>`_)

* Changed graphics tests to account for some new default grid-line spacing in
`Cartopy <https://github.com/SciTools/cartopy>`_ (`part of cartopy#1117
<https://github.com/SciTools/cartopy/pull/1117>`_).
* Martin Yeo changed graphics tests to account for some new default grid-line
spacing in `Cartopy <https://github.com/SciTools/cartopy>`_. (:pull:`3762`)
(`see also cartopy#1117 <https://github.com/SciTools/cartopy/pull/1117>`_)

* Additional acceptable graphics test targets to account for very minor changes
in `Matplotlib`_ version 3.3 (colormaps, fonts and axes borders).
* Martin Yeo added additional acceptable graphics test targets to account for
very minor changes in `Matplotlib`_ version 3.3 (colormaps, fonts and axes
borders). (:pull:`3762`)


Deprecations
============

* The deprecated :class:`iris.Future` flags ``cell_date_time_objects``,
``netcdf_promote``, ``netcdf_no_unlimited`` and ``clip_latitudes`` have
been removed.
* Stephen Worsley removed the deprecated :class:`iris.Future` flags
``cell_date_time_objects``, ``netcdf_promote``, ``netcdf_no_unlimited`` and
``clip_latitudes``. (:pull:`3459`)

* :attr:`iris.fileformats.pp.PPField.lbproc` is now an ``int``. The
deprecated attributes ``flag1``, ``flag2`` etc. have been removed from it.
* Stephen Worsley changed :attr:`iris.fileformats.pp.PPField.lbproc` is be an
``int``. The deprecated attributes ``flag1``, ``flag2`` etc. have been
removed from it. (:pull:`3461`).


Documentation
=============

* Moved the :ref:`sphx_glr_generated_gallery_oceanography_plot_orca_projection.py`
from the general part of the gallery to oceanography.
* Tremain Knight moved the
:ref:`sphx_glr_generated_gallery_oceanography_plot_orca_projection.py`
from the general part of the gallery to oceanography. (:pull:`3761`)

* Updated documentation to use a modern sphinx theme and be served from
https://scitools-iris.readthedocs.io/en/latest/.
* Tremain Knight updated documentation to use a modern sphinx theme and be
served from https://scitools-iris.readthedocs.io/en/latest/. (:pull:`3752`)

* Added support for the `black <https://black.readthedocs.io/en/stable/>`_ code
formatter. This is now automatically checked on GitHub PRs, replacing the
older, unittest-based "iris.tests.test_coding_standards.TestCodeFormat".
Black provides automatic code format correction for most IDEs. See the new
developer guide section on :ref:`iris_code_format`.
* Bill Little added support for the
`black <https://black.readthedocs.io/en/stable/>`_ code formatter. This is
now automatically checked on GitHub PRs, replacing the older, unittest-based
"iris.tests.test_coding_standards.TestCodeFormat". Black provides automatic
code format correction for most IDEs. See the new developer guide section on
:ref:`iris_code_format`. (:pull:`3518`)

* Refreshed the :ref:`whats_new_contributions` for the :ref:`iris_whatsnew`.
This includes always creating the ``latest`` what's new page so it appears
on the latest documentation at
https://scitools-iris.readthedocs.io/en/latest/whatsnew. This resolves
* Tremain Knight refreshed the :ref:`whats_new_contributions` for the
:ref:`iris_whatsnew`. This includes always creating the ``latest`` what's new
page so it appears on the latest documentation at
https://scitools-iris.readthedocs.io/en/latest/whatsnew. This resolves
:issue:`2104` and :issue:`3451`. Also updated the
:ref:`iris_development_releases_steps` to follow when making a release.
(:pull:`3769`)

* Enabled the PDF creation of the documentation on the `Read the Docs`_ service.
The PDF may be accessed by clicking on the version at the bottom of the side
bar, then selecting ``PDF`` from the ``Downloads`` section.
* Tremain Knight enabled the PDF creation of the documentation on the
`Read the Docs`_ service. The PDF may be accessed by clicking on the version
at the bottom of the side bar, then selecting ``PDF`` from the ``Downloads``
section. (:pull:`3765`)

* Added a warning to the :func:`iris.analysis.cartography.project` function
regarding its behaviour on projections with non-rectangular boundaries.
* Stephen Worsley added a warning to the
:func:`iris.analysis.cartography.project` function regarding its behaviour on
projections with non-rectangular boundaries. (:pull:`3762`)

* Added the :ref:`cube_maths_combining_units` section to the user guide to
clarify how ``Units`` are handled during cube arithmetic.
* Stephen Worsley added the :ref:`cube_maths_combining_units` section to the
user guide to clarify how ``Units`` are handled during cube arithmetic.
(:pull:`3803`)

.. _Read the Docs: https://scitools-iris.readthedocs.io/en/latest/
.. _Matplotlib: https://matplotlib.org/
Expand Down