From 18ad14aa128680f8dfef6eb12a8312bb2684ba35 Mon Sep 17 00:00:00 2001 From: Martin Yeo Date: Thu, 10 Sep 2020 15:24:04 +0100 Subject: [PATCH 01/17] Added names and PR refs to whatsnew. --- docs/iris/src/whatsnew/latest.rst | 230 +++++++++++++++++------------- 1 file changed, 129 insertions(+), 101 deletions(-) diff --git a/docs/iris/src/whatsnew/latest.rst b/docs/iris/src/whatsnew/latest.rst index a994a994e9..cf6561a593 100644 --- a/docs/iris/src/whatsnew/latest.rst +++ b/docs/iris/src/whatsnew/latest.rst @@ -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 `_. +* 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 `_. (:pull:`3762`) -* Iris now requires `Cartopy `_ >= 0.18 in +* Stephen Worsley and Martin Yeo pinned Iris to require + `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 `_ 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 `_ (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`. @@ -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 `_ (see +* Stephen Worsley changed the numerical values in tests involving the Robinson + projection due to improvements made in `Proj `_. + (:pull:`3762`) (see also `proj#1292 `_ and - `proj#2151 `_). + `proj#2151 `_) -* Change tests to account for more detailed descriptions of projections in - `GDAL `_ - (`see GDAL#1185 `_). +* Stephen Worsley changed tests to account for more detailed descriptions of + projections in `GDAL `_. (:pull:`3762`) + (`see also GDAL#1185 `_) -* Change tests to account for `GDAL `_ now - saving fill values for data without masked points. +* Stephen Worsley changed tests to account for + `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 `_ - to account for new adaptive coastline scaling (`see cartopy#1105 - `_). + to account for new adaptive coastline scaling. (:pull:`3762`) (`see also + cartopy#1105 `_) -* Changed graphics tests to account for some new default grid-line spacing in - `Cartopy `_ (`part of cartopy#1117 - `_). +* Martin Yeo changed graphics tests to account for some new default grid-line + spacing in `Cartopy `_. (:pull:`3762`) + (`see also cartopy#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 `_ 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 `_ 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/ From d320565c002cd949c333d295ac3daf6bc428ce26 Mon Sep 17 00:00:00 2001 From: Martin Yeo Date: Thu, 10 Sep 2020 15:58:11 +0100 Subject: [PATCH 02/17] More prescriptive instructions on whatsnew content. --- .../documenting/whats_new_contributions.rst | 44 ++++++++++++------- 1 file changed, 29 insertions(+), 15 deletions(-) diff --git a/docs/iris/src/developers_guide/documenting/whats_new_contributions.rst b/docs/iris/src/developers_guide/documenting/whats_new_contributions.rst index b4ca483075..6cd39eac8a 100644 --- a/docs/iris/src/developers_guide/documenting/whats_new_contributions.rst +++ b/docs/iris/src/developers_guide/documenting/whats_new_contributions.rst @@ -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/``. @@ -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. - +* 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 ` the documentation. .. _travis-ci: https://travis-ci.org/github/SciTools/iris From 596f31b7aa678cecb4903b0898cbbeef73aba594 Mon Sep 17 00:00:00 2001 From: Martin Yeo Date: Fri, 11 Sep 2020 10:56:05 +0100 Subject: [PATCH 03/17] Reference GitHub names in whatsnew. --- .../documenting/whats_new_contributions.rst | 16 ++- docs/iris/src/whatsnew/latest.rst | 126 ++++++++++-------- 2 files changed, 79 insertions(+), 63 deletions(-) diff --git a/docs/iris/src/developers_guide/documenting/whats_new_contributions.rst b/docs/iris/src/developers_guide/documenting/whats_new_contributions.rst index 6cd39eac8a..94b2373032 100644 --- a/docs/iris/src/developers_guide/documenting/whats_new_contributions.rst +++ b/docs/iris/src/developers_guide/documenting/whats_new_contributions.rst @@ -28,8 +28,11 @@ 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: -* Names of those who contributed the change e.g. ``Robert FitzRoy and Luke - Howard changed...`` +* Names of those who contributed the change. These should be their GitHub + display name, or if that is not available use their GitHub user name. Link + the name to their GitHub profile. E.g. + ```Bill Little `_ and + `tkknight `_ changed...`` * The new/changed behaviour @@ -44,10 +47,11 @@ content, in order, is as follows: 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`) + * `Bill Little `_ and + `tkknight `_ changed 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 diff --git a/docs/iris/src/whatsnew/latest.rst b/docs/iris/src/whatsnew/latest.rst index cf6561a593..e845819203 100644 --- a/docs/iris/src/whatsnew/latest.rst +++ b/docs/iris/src/whatsnew/latest.rst @@ -13,11 +13,11 @@ This document explains the changes made to Iris for this release Features ======== -* 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`) +* `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`) -* Stephen Worsley improved the handling of :class:`iris.coord.CellMeasure` in +* `stephenworsley`_ 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 @@ -25,12 +25,12 @@ Features :class:`iris.coord.CellMeasure` will only be removed if it is associated with an axis over which the statistic is being run. (:pull:`3549`) -* Stephen Worsley, Patrick Peglar and Anna Booton added support for +* `stephenworsley`_, `Patrick Peglar`_ and `abooton`_ 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`) -* Bouwe Andela implemented lazy regridding for the +* `Bouwe Andela`_ implemented lazy regridding for the :class:`~iris.analysis.Linear`, :class:`~iris.analysis.Nearest`, and :class:`~iris.analysis.AreaWeighted` regridding schemes. (:pull:`3701`) @@ -38,23 +38,23 @@ Features Dependency Updates ================== -* Bill Little unpinned Iris to use the latest version of `Matplotlib`_. +* `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 `_. (:pull:`3762`) +* `stephenworsley`_ and `Martin Yeo`_ unpinned Iris to use the latest version + of `Proj `_. (:pull:`3762`) -* Stephen Worsley and Martin Yeo pinned Iris to require +* `stephenworsley`_ and `Martin Yeo`_ pinned Iris to require `Cartopy `_ >= 0.18, in order to remain compatible with the latest version of `Matplotlib`_. (:pull:`3762`) -* Stephen Worsley and Martin Yeo removed GDAL from the extensions dependency - group. We no longer consider it to be an extension. (:pull:`3762`) +* `stephenworsley`_ 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 +* `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`) @@ -63,55 +63,56 @@ Dependency Updates Bugs Fixed ========== -* Stephen Worsley fixed :meth:`~iris.Cube.cube.remove_coord` to now also remove - derived coordinates, by removing aux_factories. (:pull:`3641`) +* `stephenworsley`_ fixed :meth:`~iris.Cube.cube.remove_coord` to now also + remove derived coordinates, by removing aux_factories. (:pull:`3641`) -* 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`) +* `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`) -* Stephen Worsley enabled cube concatenation along an axis shared by cell +* `stephenworsley`_ 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`) -* Stephen Worsley newly included :class:`~iris.coords.CellMeasure`s in +* `stephenworsley`_ 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`) -* Bill Little set a :class:`~iris.coords.CellMeasure`'s +* `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 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`) -* Martin Yeo set **all** plot types in `iris.plot` to now use +* `Martin Yeo`_ set **all** plot types in `iris.plot` to now use `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). (:pull:`3762`) -* Martin Yeo changed date/time axis labels in `iris.quickplot` to now +* `Martin Yeo`_ changed date/time axis labels in `iris.quickplot` to now **always** be based on the ``epoch`` used in `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`) -* 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`. +* `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 ==================== -* Patrick Peglar rationalised :class:`~iris.cube.CubeList` extraction +* `Patrick Peglar`_ rationalised :class:`~iris.cube.CubeList` extraction methods: The method :meth:`~iris.cube.CubeList.extract_strict`, and the ``strict`` @@ -119,28 +120,29 @@ Incompatible Changes are replaced by the new routines :meth:`~iris.cube.CubeList.extract_cube` and :meth:`~iris.cube.CubeList.extract_cubes`. The new routines perform the same operation, but in a style more like other - ``Iris`` functions such as :meth:`~iris.load_cube` and :meth:`~iris.load_cubes`. + ``Iris`` functions such as :meth:`~iris.load_cube` and:meth:`~iris.load_cubes`. Unlike ``strict`` extraction, the type of return value is now completely 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. (:pull:`3715`) -* Patrick Peglar removed the former function ``iris.analysis.coord_comparison``. - (:pull:`3562`) +* `Patrick Peglar`_ removed the former function + ``iris.analysis.coord_comparison``. (:pull:`3562`) -* 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. (:pull:`3527`) +* `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. + (:pull:`3527`) -* Bill Little removed the :mod:`iris.experimental.concatenate` module. 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. (:pull:`3523`) -* Stephen Worsley changed Iris objects loaded from NetCDF-CF files to have +* `stephenworsley`_ 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`) @@ -148,43 +150,44 @@ Incompatible Changes Internal ======== -* Stephen Worsley changed the numerical values in tests involving the Robinson - projection due to improvements made in `Proj `_. - (:pull:`3762`) (see also +* `stephenworsley`_ changed the numerical values in tests involving the + Robinson projection due to improvements made in + `Proj `_. (:pull:`3762`) (see also `proj#1292 `_ and `proj#2151 `_) -* Stephen Worsley changed tests to account for more detailed descriptions of +* `stephenworsley`_ changed tests to account for more detailed descriptions of projections in `GDAL `_. (:pull:`3762`) (`see also GDAL#1185 `_) -* Stephen Worsley changed tests to account for +* `stephenworsley`_ changed tests to account for `GDAL `_ now saving fill values for data without masked points. (:pull:`3762`) -* Martin Yeo changed every graphics test that includes `Cartopy's coastlines +* `Martin Yeo`_ changed every graphics test that includes `Cartopy's coastlines `_ to account for new adaptive coastline scaling. (:pull:`3762`) (`see also cartopy#1105 `_) -* Martin Yeo changed graphics tests to account for some new default grid-line - spacing in `Cartopy `_. (:pull:`3762`) +* `Martin Yeo`_ changed graphics tests to account for some new default + grid-line spacing in `Cartopy `_. + (:pull:`3762`) (`see also cartopy#1117 `_) -* 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`) +* `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 ============ -* Stephen Worsley removed the deprecated :class:`iris.Future` flags +* `stephenworsley`_ removed the deprecated :class:`iris.Future` flags ``cell_date_time_objects``, ``netcdf_promote``, ``netcdf_no_unlimited`` and ``clip_latitudes``. (:pull:`3459`) -* Stephen Worsley changed :attr:`iris.fileformats.pp.PPField.lbproc` is be an +* `stephenworsley`_ changed :attr:`iris.fileformats.pp.PPField.lbproc` is be an ``int``. The deprecated attributes ``flag1``, ``flag2`` etc. have been removed from it. (:pull:`3461`). @@ -192,21 +195,21 @@ Deprecations Documentation ============= -* Tremain Knight moved the +* `tkknight`_ moved the :ref:`sphx_glr_generated_gallery_oceanography_plot_orca_projection.py` from the general part of the gallery to oceanography. (:pull:`3761`) -* Tremain Knight updated documentation to use a modern sphinx theme and be +* `tkknight`_ updated documentation to use a modern sphinx theme and be served from https://scitools-iris.readthedocs.io/en/latest/. (:pull:`3752`) -* Bill Little added support for the +* `Bill Little`_ added support for the `black `_ 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`) -* Tremain Knight refreshed the :ref:`whats_new_contributions` for the +* `tkknight`_ 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 @@ -214,16 +217,16 @@ Documentation :ref:`iris_development_releases_steps` to follow when making a release. (:pull:`3769`) -* Tremain Knight enabled the PDF creation of the documentation on the +* `tkknight`_ 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`) -* Stephen Worsley added a warning to the +* `stephenworsley`_ added a warning to the :func:`iris.analysis.cartography.project` function regarding its behaviour on projections with non-rectangular boundaries. (:pull:`3762`) -* Stephen Worsley added the :ref:`cube_maths_combining_units` section to the +* `stephenworsley`_ added the :ref:`cube_maths_combining_units` section to the user guide to clarify how ``Units`` are handled during cube arithmetic. (:pull:`3803`) @@ -231,3 +234,12 @@ Documentation .. _Matplotlib: https://matplotlib.org/ .. _CF Ancillary Data: https://cfconventions.org/Data/cf-conventions/cf-conventions-1.8/cf-conventions.html#ancillary-data .. _Quality Flags: https://cfconventions.org/Data/cf-conventions/cf-conventions-1.8/cf-conventions.html#flags +.. _Stephen Moseley: https://github.com/MoseleyS +.. _stephenworsley: https://github.com/stephenworsley +.. _Patrick Peglar: https://github.com/pp-mo +.. _abooton: https://github.com/abooton +.. _Bouwe Andela: https://github.com/bouweandela +.. _Bill Little: https://github.com/bjlittle +.. _Martin Yeo: https://github.com/trexfeathers +.. _Jon Seddon: https://github.com/jonseddon +.. _tkknight: https://github.com/tkknight From a042f20799da00d1af943ecc6490139a3cdcc10e Mon Sep 17 00:00:00 2001 From: Martin Yeo Date: Fri, 11 Sep 2020 11:22:41 +0100 Subject: [PATCH 04/17] Moved Internal to the bottom of the whatsnew categories. --- .../documenting/whats_new_contributions.rst | 8 +-- docs/iris/src/whatsnew/latest.rst | 67 ++++++++++--------- 2 files changed, 38 insertions(+), 37 deletions(-) diff --git a/docs/iris/src/developers_guide/documenting/whats_new_contributions.rst b/docs/iris/src/developers_guide/documenting/whats_new_contributions.rst index 94b2373032..448bfa42ab 100644 --- a/docs/iris/src/developers_guide/documenting/whats_new_contributions.rst +++ b/docs/iris/src/developers_guide/documenting/whats_new_contributions.rst @@ -82,12 +82,12 @@ users. To achieve this several categories may be used. *Incompatible Changes* A change that causes an incompatibility with prior versions of Iris. -*Internal* - Changes to any internal or development related topics, such as testing, - environment dependencies etc - *Deprecations* Deprecations of functionality. *Documentation* Changes to documentation. + +*Internal* + Changes to any internal or development related topics, such as testing, + environment dependencies etc diff --git a/docs/iris/src/whatsnew/latest.rst b/docs/iris/src/whatsnew/latest.rst index e845819203..28304a5ed0 100644 --- a/docs/iris/src/whatsnew/latest.rst +++ b/docs/iris/src/whatsnew/latest.rst @@ -147,39 +147,6 @@ Incompatible Changes property. Previously these cases defaulted to ``units='1'``. (:pull:`3795`) -Internal -======== - -* `stephenworsley`_ changed the numerical values in tests involving the - Robinson projection due to improvements made in - `Proj `_. (:pull:`3762`) (see also - `proj#1292 `_ and - `proj#2151 `_) - -* `stephenworsley`_ changed tests to account for more detailed descriptions of - projections in `GDAL `_. (:pull:`3762`) - (`see also GDAL#1185 `_) - -* `stephenworsley`_ changed tests to account for - `GDAL `_ now saving fill values for data - without masked points. (:pull:`3762`) - -* `Martin Yeo`_ changed every graphics test that includes `Cartopy's coastlines - `_ - to account for new adaptive coastline scaling. (:pull:`3762`) (`see also - cartopy#1105 `_) - -* `Martin Yeo`_ changed graphics tests to account for some new default - grid-line spacing in `Cartopy `_. - (:pull:`3762`) - (`see also cartopy#1117 `_) - -* `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 ============ @@ -230,6 +197,40 @@ Documentation user guide to clarify how ``Units`` are handled during cube arithmetic. (:pull:`3803`) + +Internal +======== + +* `stephenworsley`_ changed the numerical values in tests involving the + Robinson projection due to improvements made in + `Proj `_. (:pull:`3762`) (see also + `proj#1292 `_ and + `proj#2151 `_) + +* `stephenworsley`_ changed tests to account for more detailed descriptions of + projections in `GDAL `_. (:pull:`3762`) + (`see also GDAL#1185 `_) + +* `stephenworsley`_ changed tests to account for + `GDAL `_ now saving fill values for data + without masked points. (:pull:`3762`) + +* `Martin Yeo`_ changed every graphics test that includes `Cartopy's coastlines + `_ + to account for new adaptive coastline scaling. (:pull:`3762`) (`see also + cartopy#1105 `_) + +* `Martin Yeo`_ changed graphics tests to account for some new default + grid-line spacing in `Cartopy `_. + (:pull:`3762`) + (`see also cartopy#1117 `_) + +* `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`) + + .. _Read the Docs: https://scitools-iris.readthedocs.io/en/latest/ .. _Matplotlib: https://matplotlib.org/ .. _CF Ancillary Data: https://cfconventions.org/Data/cf-conventions/cf-conventions-1.8/cf-conventions.html#ancillary-data From b3ac7125b5edd2f6d81e6289322f9a28fc1f139c Mon Sep 17 00:00:00 2001 From: Martin Yeo Date: Fri, 11 Sep 2020 12:34:01 +0100 Subject: [PATCH 05/17] Added missed whatsnew entries from pre-4761a10630b044aedb38f56f96ecff3f52085ca4. --- docs/iris/src/whatsnew/latest.rst | 41 +++++++++++++++++++++++-------- 1 file changed, 31 insertions(+), 10 deletions(-) diff --git a/docs/iris/src/whatsnew/latest.rst b/docs/iris/src/whatsnew/latest.rst index 28304a5ed0..fa94503426 100644 --- a/docs/iris/src/whatsnew/latest.rst +++ b/docs/iris/src/whatsnew/latest.rst @@ -38,6 +38,23 @@ Features Dependency Updates ================== + +* `stephenworsley`_, `Martin Yeo`_ and `Bill Little`_ removed ``Python2`` + support, modernising the codebase by switching to exclusive ``Python3`` + support. (:pull:`3513`) + +* `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`) + +* `stephenworsley`_ pinned Iris to require Dask >= 2.0. (:pull:`3460`) + +* `stephenworsley`_ and `Martin Yeo`_ pinned Iris to require + `Cartopy `_ >= 0.18, in + order to remain compatible with the latest version of `Matplotlib`_. + (:pull:`3762`) + * `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 @@ -46,19 +63,9 @@ Dependency Updates * `stephenworsley`_ and `Martin Yeo`_ unpinned Iris to use the latest version of `Proj `_. (:pull:`3762`) -* `stephenworsley`_ and `Martin Yeo`_ pinned Iris to require - `Cartopy `_ >= 0.18, in - order to remain compatible with the latest version of `Matplotlib`_. - (:pull:`3762`) - * `stephenworsley`_ 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`) - Bugs Fixed ========== @@ -201,6 +208,19 @@ Documentation Internal ======== +* `Patrick Peglar`_ and `lbdreyer`_ removed all test dependencies on + `SciTools/iris-grib `_ by transferring + all relevant content to the iris-grib repository. (:pull:`3662`, + :pull:`3663`, :pull:`3664`, :pull:`3665`, :pull:`3666`, :pull:`3669`, + :pull:`3670`, :pull:`3671`, :pull:`3672`, :pull:`3742`, :pull:`3746`) + +* `lbdreyer`_ and `Patrick Peglar`_ overhauled the handling of dimensional + metadata to remove duplication. (:pull:`3422`, :pull:`3551`) + +* `Martin Yeo`_ simplified the standard license header for all files, which + removes the need to repeatedly update year numbers in the header. + (:pull:`3489`) + * `stephenworsley`_ changed the numerical values in tests involving the Robinson projection due to improvements made in `Proj `_. (:pull:`3762`) (see also @@ -244,3 +264,4 @@ Internal .. _Martin Yeo: https://github.com/trexfeathers .. _Jon Seddon: https://github.com/jonseddon .. _tkknight: https://github.com/tkknight +.. _lbdreyer: https://github.com/lbdreyer From 7dd6f0aa845b686fa284bae67878028a5c66a739 Mon Sep 17 00:00:00 2001 From: Martin Yeo Date: Fri, 11 Sep 2020 12:35:29 +0100 Subject: [PATCH 06/17] Fixed dependency position in whatsnew. --- .../documenting/whats_new_contributions.rst | 3 + docs/iris/src/whatsnew/latest.rst | 64 +++++++++---------- docs/iris/src/whatsnew/latest.rst.template | 2 +- 3 files changed, 36 insertions(+), 33 deletions(-) diff --git a/docs/iris/src/developers_guide/documenting/whats_new_contributions.rst b/docs/iris/src/developers_guide/documenting/whats_new_contributions.rst index 448bfa42ab..17c9fc6fee 100644 --- a/docs/iris/src/developers_guide/documenting/whats_new_contributions.rst +++ b/docs/iris/src/developers_guide/documenting/whats_new_contributions.rst @@ -85,6 +85,9 @@ users. To achieve this several categories may be used. *Deprecations* Deprecations of functionality. +*Dependencies* + Additions, removals and version changes in Iris' package dependencies. + *Documentation* Changes to documentation. diff --git a/docs/iris/src/whatsnew/latest.rst b/docs/iris/src/whatsnew/latest.rst index fa94503426..04e53370fe 100644 --- a/docs/iris/src/whatsnew/latest.rst +++ b/docs/iris/src/whatsnew/latest.rst @@ -35,38 +35,6 @@ Features :class:`~iris.analysis.AreaWeighted` regridding schemes. (:pull:`3701`) -Dependency Updates -================== - - -* `stephenworsley`_, `Martin Yeo`_ and `Bill Little`_ removed ``Python2`` - support, modernising the codebase by switching to exclusive ``Python3`` - support. (:pull:`3513`) - -* `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`) - -* `stephenworsley`_ pinned Iris to require Dask >= 2.0. (:pull:`3460`) - -* `stephenworsley`_ and `Martin Yeo`_ pinned Iris to require - `Cartopy `_ >= 0.18, in - order to remain compatible with the latest version of `Matplotlib`_. - (:pull:`3762`) - -* `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`) - -* `stephenworsley`_ and `Martin Yeo`_ unpinned Iris to use the latest version - of `Proj `_. (:pull:`3762`) - -* `stephenworsley`_ and `Martin Yeo`_ removed GDAL from the extensions - dependency group. We no longer consider it to be an extension. (:pull:`3762`) - - Bugs Fixed ========== @@ -166,6 +134,38 @@ Deprecations removed from it. (:pull:`3461`). +Dependency Updates +================== + + +* `stephenworsley`_, `Martin Yeo`_ and `Bill Little`_ removed ``Python2`` + support, modernising the codebase by switching to exclusive ``Python3`` + support. (:pull:`3513`) + +* `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`) + +* `stephenworsley`_ pinned Iris to require Dask >= 2.0. (:pull:`3460`) + +* `stephenworsley`_ and `Martin Yeo`_ pinned Iris to require + `Cartopy `_ >= 0.18, in + order to remain compatible with the latest version of `Matplotlib`_. + (:pull:`3762`) + +* `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`) + +* `stephenworsley`_ and `Martin Yeo`_ unpinned Iris to use the latest version + of `Proj `_. (:pull:`3762`) + +* `stephenworsley`_ and `Martin Yeo`_ removed GDAL from the extensions + dependency group. We no longer consider it to be an extension. (:pull:`3762`) + + Documentation ============= diff --git a/docs/iris/src/whatsnew/latest.rst.template b/docs/iris/src/whatsnew/latest.rst.template index 82f87d9e5a..841941d9bf 100644 --- a/docs/iris/src/whatsnew/latest.rst.template +++ b/docs/iris/src/whatsnew/latest.rst.template @@ -43,4 +43,4 @@ Internal Documentation ============= -* N/A \ No newline at end of file +* N/A From 92b5b010372831e4a2ab5b352dd4d28020d1a971 Mon Sep 17 00:00:00 2001 From: Martin Yeo Date: Fri, 11 Sep 2020 13:01:14 +0100 Subject: [PATCH 07/17] Moved Internal to the bottom of the whatsnew categories. --- docs/iris/src/whatsnew/latest.rst.template | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/iris/src/whatsnew/latest.rst.template b/docs/iris/src/whatsnew/latest.rst.template index 841941d9bf..5a7ec9c1da 100644 --- a/docs/iris/src/whatsnew/latest.rst.template +++ b/docs/iris/src/whatsnew/latest.rst.template @@ -34,13 +34,13 @@ Dependencies * N/A -Internal -======== +Documentation +============= * N/A -Documentation -============= +Internal +======== * N/A From 15ebb9965d6552900b7fd881bfcb3b729681dd5e Mon Sep 17 00:00:00 2001 From: Martin Yeo Date: Fri, 11 Sep 2020 16:59:00 +0100 Subject: [PATCH 08/17] Update to what is expected of developers regarding whatsnews and pull requests in general. --- .github/pull_request_template.md | 5 +++ .../documenting/docstrings.rst | 6 ++-- .../documenting/whats_new_contributions.rst | 31 ++++++++++++++++- docs/iris/src/developers_guide/pulls.rst | 34 +++++++------------ 4 files changed, 51 insertions(+), 25 deletions(-) create mode 100644 .github/pull_request_template.md diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000000..578bc354b8 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,5 @@ +**Authors and Reviewers:** please make sure this pull request complies as much +as possible with the +[Iris pull request check list]( https://scitools-iris.readthedocs.io/en/latest/developers_guide/pulls.html#the-iris-check-list). + +--- diff --git a/docs/iris/src/developers_guide/documenting/docstrings.rst b/docs/iris/src/developers_guide/documenting/docstrings.rst index 641bf7717e..07d0496e33 100644 --- a/docs/iris/src/developers_guide/documenting/docstrings.rst +++ b/docs/iris/src/developers_guide/documenting/docstrings.rst @@ -1,3 +1,5 @@ +.. _docstrings: + ========== Docstrings ========== @@ -7,7 +9,7 @@ appropriate docstring. This document has been influenced by the following PEP's, - * Attribute Docstrings `PEP-224 `_ + * Attribute Docstrings `PEP-224 `_ * Docstring Conventions `PEP-257 `_ @@ -42,7 +44,7 @@ Here is a simple example of a standard docstring: This would be rendered as: .. currentmodule:: documenting.docstrings_sample_routine - + .. automodule:: documenting.docstrings_sample_routine :members: :undoc-members: diff --git a/docs/iris/src/developers_guide/documenting/whats_new_contributions.rst b/docs/iris/src/developers_guide/documenting/whats_new_contributions.rst index 17c9fc6fee..94e3ce045a 100644 --- a/docs/iris/src/developers_guide/documenting/whats_new_contributions.rst +++ b/docs/iris/src/developers_guide/documenting/whats_new_contributions.rst @@ -11,7 +11,33 @@ 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 -``docs/iris/src/whatsnew/``. +``docs/iris/src/whatsnew/``. If you are writing the first contribution after +an Iris release: newly create ``latest.rst`` by copying the content in +``latest.rst.template`` in the same directory. + +Since the `Contribution categories`_ include Internal changes, **all** Iris +Pull Requests should be accompanied by a "What's New" contribution. + + +Git Conflicts +============= + +If changes to ``latest.rst`` are being suggested in several simultaneous +Iris Pull Requests, Git will likely encounter merge conflicts. In you think +this situation is likely (large PR, high repo activity etc.): wait until your +code is ready for review, then create a new pull request specifically for the +"What's New" entry, referencing the main pull request and titled +(e.g. for PR#9999): + + What's New for #9999 + +If the entry references something new introduced by the main pull request then +such links will not be valid yet. The reviewer should merge the main pull +request first, followed by the "What's New" pull request. + +These measures should mean the suggested ``latest.rst`` changes are outstanding +for the minimum time, minimising conflicts and minimising the need to rebase or +merge from trunk. Writing a contribution @@ -22,6 +48,9 @@ which improved Iris in some way. As such, a single Iris Pull Request may contain multiple changes that are worth highlighting as contributions to the what's new document. +The appropriate contribution for a pull request might in fact be an addition or +change to an existing "What's New" entry. + Each contribution will ideally be written as a single concise bullet point 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 diff --git a/docs/iris/src/developers_guide/pulls.rst b/docs/iris/src/developers_guide/pulls.rst index 366cedd159..26b55d693a 100644 --- a/docs/iris/src/developers_guide/pulls.rst +++ b/docs/iris/src/developers_guide/pulls.rst @@ -1,7 +1,7 @@ .. _pr_check: -Pull request check List +Pull request check list *********************** A pull request to a SciTools project master should be ready to merge into the @@ -10,7 +10,7 @@ master branch. All pull request will be reviewed by a core developer who will manage the process of merging. It is the responsibility of a developer submitting a pull request to do their best to deliver a pull request which meets the -requirements of the project it is submitted to. +requirements of the project it is submitted to. The check list summarises criteria which will be checked before a pull request is merged. Before submitting a pull request please consider this list. @@ -24,33 +24,26 @@ The Iris check list * the aim of the change ; the problem addressed ; a link to the issue. * how the change has been delivered. - * a "What's New" entry, submitted as a new file added in the pull request. - See `Contributing a "What's New" entry`_. + * a "What's New" entry - see :ref:`whats_new_contributions`. * Do all the tests pass locally? - * The Iris tests may be run with ``python setup.py test`` which has a command + * The Iris tests may be run with ``python setup.py test`` which has a command line utility included. * Have new tests been provided for all additional functionality? -* Do all modified and new source files pass PEP8? +* Do all modified and new source files conform to the required + :ref:`iris_code_format`? - * PEP8_ is the Python source code style guide. - * There is a python module for checking pep8 compliance: python-pep8_ - * a standard Iris test checks that all source files meet PEP8 compliance - (see "iris.tests.test_coding_standards.TestCodeFormat"). - -* Do all modified and new source files have a correct, up-to-date copyright - header? +* Do all modified and new source files have a correct copyright header? * a standard Iris test checks that all source files include a copyright - message, including the correct year of the latest change - (see "iris.tests.test_coding_standards.TestLicenseHeaders"). + message (see "iris.tests.test_coding_standards.TestLicenseHeaders"). * Has the documentation been updated to explain all new or changed features? - * refer to the developer guide on docstrings_ + * refer to the developer guide on :ref:`docstrings` * Have code examples been provided inside docstrings, where relevant? @@ -67,8 +60,7 @@ The Iris check list * Have you provided a "what's new" contribution? - * this should be done for all changes that affect API or behaviour. - See :ref:`whats_new_contributions` + * this should be done for **all** changes - see :ref:`whats_new_contributions` * Does the documentation build without errors? @@ -98,7 +90,7 @@ The Iris check list tests. * iris-sample-data_ is a github project containing all the data to support the gallery and examples. - * test-images-scitools_ is a github project containing reference plot images + * test-iris-imagehash_ is a github project containing reference plot images to support iris graphics tests : see :ref:`developer_graphics_tests`. * If new files are required by tests or code examples, they must be added to @@ -112,6 +104,4 @@ The Iris check list .. _conda: https://docs.conda.io/en/latest/ .. _iris-test-data: https://github.com/SciTools/iris-test-data .. _iris-sample-data: https://github.com/SciTools/iris-sample-data -.. _test-images-scitools: https://github.com/SciTools/test-images-scitools -.. _docstrings: http://scitools.org.uk/iris/docs/latest/developers_guide/documenting/docstrings.html -.. _Contributing a "What's New" entry: http://scitools.org.uk/iris/docs/latest/developers_guide/documenting/whats_new_contributions.html +.. _test-iris-imagehash: https://github.com/SciTools/test-iris-imagehash From 5c8951b80884e1c3e1295f197fc0cedaf49b760a Mon Sep 17 00:00:00 2001 From: Martin Yeo Date: Fri, 11 Sep 2020 17:16:03 +0100 Subject: [PATCH 09/17] Corrected latest.rst Dependencies heading. --- docs/iris/src/whatsnew/latest.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/iris/src/whatsnew/latest.rst b/docs/iris/src/whatsnew/latest.rst index 04e53370fe..a36bc61858 100644 --- a/docs/iris/src/whatsnew/latest.rst +++ b/docs/iris/src/whatsnew/latest.rst @@ -134,8 +134,8 @@ Deprecations removed from it. (:pull:`3461`). -Dependency Updates -================== +Dependencies +============ * `stephenworsley`_, `Martin Yeo`_ and `Bill Little`_ removed ``Python2`` From 47aff9eeef29bd0f019cabf810885c15e16c861b Mon Sep 17 00:00:00 2001 From: Martin Yeo Date: Fri, 11 Sep 2020 17:22:01 +0100 Subject: [PATCH 10/17] Whatsnew entry. --- docs/iris/src/whatsnew/latest.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/iris/src/whatsnew/latest.rst b/docs/iris/src/whatsnew/latest.rst index a36bc61858..c3a93126ec 100644 --- a/docs/iris/src/whatsnew/latest.rst +++ b/docs/iris/src/whatsnew/latest.rst @@ -183,13 +183,13 @@ Documentation code format correction for most IDEs. See the new developer guide section on :ref:`iris_code_format`. (:pull:`3518`) -* `tkknight`_ 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 +* `tkknight`_ and `Martin Yeo`_ 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 + :issue:`2104`, :issue:`3451`, :issue:`3818`, :issue:`3837`. Also updated the :ref:`iris_development_releases_steps` to follow when making a release. - (:pull:`3769`) + (:pull:`3769`, :pull:`3838`, :pull:`3843`) * `tkknight`_ enabled the PDF creation of the documentation on the `Read the Docs`_ service. The PDF may be accessed by clicking on the version From 2c35a398cc6f9bdda36685b68bd5a1f64c6f2677 Mon Sep 17 00:00:00 2001 From: Martin Yeo Date: Fri, 11 Sep 2020 18:03:24 +0100 Subject: [PATCH 11/17] Clearer emphasis for whats_new_contributions.rst. --- .../documenting/whats_new_contributions.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/iris/src/developers_guide/documenting/whats_new_contributions.rst b/docs/iris/src/developers_guide/documenting/whats_new_contributions.rst index 94e3ce045a..57d072ce3e 100644 --- a/docs/iris/src/developers_guide/documenting/whats_new_contributions.rst +++ b/docs/iris/src/developers_guide/documenting/whats_new_contributions.rst @@ -12,7 +12,7 @@ introduces the change. The ``latest.rst`` and the past release notes are kept in ``docs/iris/src/whatsnew/``. If you are writing the first contribution after -an Iris release: newly create ``latest.rst`` by copying the content in +an Iris release: **create the new** ``latest.rst`` by copying the content from ``latest.rst.template`` in the same directory. Since the `Contribution categories`_ include Internal changes, **all** Iris @@ -25,15 +25,15 @@ Git Conflicts If changes to ``latest.rst`` are being suggested in several simultaneous Iris Pull Requests, Git will likely encounter merge conflicts. In you think this situation is likely (large PR, high repo activity etc.): wait until your -code is ready for review, then create a new pull request specifically for the -"What's New" entry, referencing the main pull request and titled +code is ready for review, then create a **new pull request** specifically for +the "What's New" entry, referencing the main pull request and titled (e.g. for PR#9999): What's New for #9999 If the entry references something new introduced by the main pull request then -such links will not be valid yet. The reviewer should merge the main pull -request first, followed by the "What's New" pull request. +such links will not be valid yet. The reviewer should **merge the main pull +request first**, followed by the "What's New" pull request. These measures should mean the suggested ``latest.rst`` changes are outstanding for the minimum time, minimising conflicts and minimising the need to rebase or From 88fb0710564dc4b69496cbd5da5e76d40ae21024 Mon Sep 17 00:00:00 2001 From: Martin Yeo Date: Fri, 11 Sep 2020 18:43:49 +0100 Subject: [PATCH 12/17] docstrings.rst sphinx pep inline markup. --- docs/iris/src/developers_guide/documenting/docstrings.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/iris/src/developers_guide/documenting/docstrings.rst b/docs/iris/src/developers_guide/documenting/docstrings.rst index 07d0496e33..323d753a52 100644 --- a/docs/iris/src/developers_guide/documenting/docstrings.rst +++ b/docs/iris/src/developers_guide/documenting/docstrings.rst @@ -9,8 +9,8 @@ appropriate docstring. This document has been influenced by the following PEP's, - * Attribute Docstrings `PEP-224 `_ - * Docstring Conventions `PEP-257 `_ + * Attribute Docstrings :pep:`224` + * Docstring Conventions :pep:`257` For consistency, always use ``"""triple double quotes"""`` around docstrings. Use ``r"""raw triple double quotes"""`` if you use any backslashes in your docstrings. For Unicode docstrings, use ``u"""Unicode triple-quoted string"""``. From 08ee8ba8fb32244e7c566138dfae0b7beb4f801d Mon Sep 17 00:00:00 2001 From: Martin Yeo Date: Mon, 14 Sep 2020 12:56:18 +0100 Subject: [PATCH 13/17] PR template consistent formatting with issue templates. --- .github/pull_request_template.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 578bc354b8..c3e3c386a5 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,5 +1,9 @@ -**Authors and Reviewers:** please make sure this pull request complies as much -as possible with the -[Iris pull request check list]( https://scitools-iris.readthedocs.io/en/latest/developers_guide/pulls.html#the-iris-check-list). +## 🚀 Pull Request + +### Description + + + --- +[Consult Iris pull request check list]( https://scitools-iris.readthedocs.io/en/latest/developers_guide/pulls.html#the-iris-check-list) From 8158666c0a8432af262e9141c7167975501a61b4 Mon Sep 17 00:00:00 2001 From: Martin Yeo Date: Mon, 14 Sep 2020 13:17:22 +0100 Subject: [PATCH 14/17] Improved the suggested whatsnew PR process. --- .../documenting/whats_new_contributions.rst | 26 ++++++++++++------- 1 file changed, 17 insertions(+), 9 deletions(-) diff --git a/docs/iris/src/developers_guide/documenting/whats_new_contributions.rst b/docs/iris/src/developers_guide/documenting/whats_new_contributions.rst index 57d072ce3e..bc41ea39d7 100644 --- a/docs/iris/src/developers_guide/documenting/whats_new_contributions.rst +++ b/docs/iris/src/developers_guide/documenting/whats_new_contributions.rst @@ -23,17 +23,25 @@ Git Conflicts ============= If changes to ``latest.rst`` are being suggested in several simultaneous -Iris Pull Requests, Git will likely encounter merge conflicts. In you think -this situation is likely (large PR, high repo activity etc.): wait until your -code is ready for review, then create a **new pull request** specifically for -the "What's New" entry, referencing the main pull request and titled -(e.g. for PR#9999): +Iris Pull Requests, Git will likely encounter merge conflicts. In this +situation is thought likely (large PR, high repo activity etc.): - What's New for #9999 +* PR author: Do not include a "What's New" entry. Mention in the PR text that a + "What's New" entry is pending -If the entry references something new introduced by the main pull request then -such links will not be valid yet. The reviewer should **merge the main pull -request first**, followed by the "What's New" pull request. +* PR reviewer: Review the PR as normal. Once the PR is acceptable, ask that + a **new pull request** be created specifically for the "What's New" entry, + which references the main pull request and titled (e.g. for PR#9999): + + What's New for #9999 + +* PR author: create the "What's New" pull request + +* PR reviewer: once the "What's New" PR is created, **merge the main PR**. + (If any links in the "What's New" PR referenced new features, these should + now be working). + +* PR reviewer: review the "What's New" PR, merge once acceptable These measures should mean the suggested ``latest.rst`` changes are outstanding for the minimum time, minimising conflicts and minimising the need to rebase or From 3138a01bbee3e9e2c67644ff9b4eae4eddde73aa Mon Sep 17 00:00:00 2001 From: Martin Yeo Date: Mon, 14 Sep 2020 15:04:29 +0100 Subject: [PATCH 15/17] What's new guide typos. --- .../documenting/whats_new_contributions.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/iris/src/developers_guide/documenting/whats_new_contributions.rst b/docs/iris/src/developers_guide/documenting/whats_new_contributions.rst index bc41ea39d7..22608a45c1 100644 --- a/docs/iris/src/developers_guide/documenting/whats_new_contributions.rst +++ b/docs/iris/src/developers_guide/documenting/whats_new_contributions.rst @@ -23,7 +23,7 @@ Git Conflicts ============= If changes to ``latest.rst`` are being suggested in several simultaneous -Iris Pull Requests, Git will likely encounter merge conflicts. In this +Iris Pull Requests, Git will likely encounter merge conflicts. If this situation is thought likely (large PR, high repo activity etc.): * PR author: Do not include a "What's New" entry. Mention in the PR text that a @@ -92,7 +92,7 @@ For example:: The above example also demonstrates some of the possible syntax for including -links to code. For more inspiration on possible content and references please +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 @@ -130,4 +130,4 @@ users. To achieve this several categories may be used. *Internal* Changes to any internal or development related topics, such as testing, - environment dependencies etc + environment dependencies etc. From d1038c403d23de9e461e3fe5e3a94cb7def73778 Mon Sep 17 00:00:00 2001 From: Martin Yeo Date: Mon, 14 Sep 2020 15:06:33 +0100 Subject: [PATCH 16/17] latest.rst typos. --- docs/iris/src/whatsnew/latest.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/iris/src/whatsnew/latest.rst b/docs/iris/src/whatsnew/latest.rst index c3a93126ec..abe347e173 100644 --- a/docs/iris/src/whatsnew/latest.rst +++ b/docs/iris/src/whatsnew/latest.rst @@ -39,7 +39,7 @@ Bugs Fixed ========== * `stephenworsley`_ fixed :meth:`~iris.Cube.cube.remove_coord` to now also - remove derived coordinates, by removing aux_factories. (:pull:`3641`) + remove derived coordinates by removing aux_factories. (:pull:`3641`) * `Jon Seddon`_ fixed ``isinstance(cube, collections.Iterable)`` to now behave as expected if a :class:`~iris.cube.Cube` is iterated over, while also @@ -95,7 +95,7 @@ Incompatible Changes are replaced by the new routines :meth:`~iris.cube.CubeList.extract_cube` and :meth:`~iris.cube.CubeList.extract_cubes`. The new routines perform the same operation, but in a style more like other - ``Iris`` functions such as :meth:`~iris.load_cube` and:meth:`~iris.load_cubes`. + ``Iris`` functions such as :meth:`~iris.load_cube` and :meth:`~iris.load_cubes`. Unlike ``strict`` extraction, the type of return value is now completely consistent : :meth:`~iris.cube.CubeList.extract_cube` always returns a :class:`~iris.cube.Cube`, and :meth:`~iris.cube.CubeList.extract_cubes` @@ -129,7 +129,7 @@ Deprecations ``cell_date_time_objects``, ``netcdf_promote``, ``netcdf_no_unlimited`` and ``clip_latitudes``. (:pull:`3459`) -* `stephenworsley`_ changed :attr:`iris.fileformats.pp.PPField.lbproc` is be an +* `stephenworsley`_ changed :attr:`iris.fileformats.pp.PPField.lbproc` to be an ``int``. The deprecated attributes ``flag1``, ``flag2`` etc. have been removed from it. (:pull:`3461`). @@ -143,7 +143,7 @@ Dependencies support. (:pull:`3513`) * `Bill Little`_ improved the developer set up process. Configuring Iris and - :ref:`installing_from_source` as a developer, with all the required package + :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`) From 544d324c4cc638fbccc06cbcde9e05a170a1a205 Mon Sep 17 00:00:00 2001 From: Martin Yeo Date: Mon, 14 Sep 2020 15:12:11 +0100 Subject: [PATCH 17/17] Improved linkcheck wording in whatsnew guide. --- .../developers_guide/documenting/whats_new_contributions.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/iris/src/developers_guide/documenting/whats_new_contributions.rst b/docs/iris/src/developers_guide/documenting/whats_new_contributions.rst index 22608a45c1..b18a89ca66 100644 --- a/docs/iris/src/developers_guide/documenting/whats_new_contributions.rst +++ b/docs/iris/src/developers_guide/documenting/whats_new_contributions.rst @@ -38,8 +38,8 @@ situation is thought likely (large PR, high repo activity etc.): * PR author: create the "What's New" pull request * PR reviewer: once the "What's New" PR is created, **merge the main PR**. - (If any links in the "What's New" PR referenced new features, these should - now be working). + (this will fix any `travis-ci`_ linkcheck errors where the links in the + "What's New" PR reference new features introduced in the main PR) * PR reviewer: review the "What's New" PR, merge once acceptable