Release branch prepare for v3.0.2 (#4044)

* update intersphinx mapping and matplotlib urls (#4003) * update intersphinx mapping and matplotlib urls * use matplotlib intersphinx where possible * review actions * review actions * cirrus-ci compute credits (#4007) * cirrus-ci conditional tasks (#4019) * cirrus-ci conditional tasks * use bc for bash arithmetic * revert back to sed * use expr * reword * minor documentation changes * review actions * prepare v3.0.2 release * Fix test_incompatible_dimensions test (#3977) * test_incompatible_dimensions used a ragged array for the test, which has been deprecated in numpy, and now fails if dtype is anything other than object. This test appears to be checking that the addition of a [2x4] masked array to a [2x3] masked cube should raise a ValueError. This commit fixes the creation of `data3` object to be a [2x4] non-ragged array. * Added entry to what's new * Added name to core developer list :) * Update latest.rst Fixed space in PR macro call * update whatsnew v3.0.2 Co-authored-by: James Penn <[email protected]>
SciTools · Mar 2, 2021 · 2557426 · 2557426
1 parent f468da3
commit 2557426
Show file tree

Hide file tree

Showing 12 changed files with 1,332 additions and 715 deletions.
diff --git a/.cirrus.yml b/.cirrus.yml
@@ -1,5 +1,6 @@
 # Reference:
 #   - https://cirrus-ci.org/guide/writing-tasks/
+#   - https://cirrus-ci.org/guide/writing-tasks/#environment-variables
 #   - https://cirrus-ci.org/guide/tips-and-tricks/#sharing-configuration-between-tasks
 #   - https://cirrus-ci.org/guide/linux/
 #   - https://cirrus-ci.org/guide/macOS/
@@ -17,6 +18,16 @@ container:
 
 
 env:
+  # Skip specific tasks by name. Set to a non-empty string to skip.
+  SKIP_LINT_TASK: ""
+  SKIP_TEST_MINIMAL_TASK: ""
+  SKIP_TEST_FULL_TASK: ""
+  SKIP_GALLERY_TASK: ""
+  SKIP_DOCTEST_TASK: ""
+  SKIP_LINKCHECK_TASK: ""
+  # Skip task groups by type. Set to a non-empty string to skip.
+  SKIP_ALL_TEST_TASKS: ""
+  SKIP_ALL_DOC_TASKS: ""
   # Maximum cache period (in weeks) before forcing a new cache upload.
   CACHE_PERIOD: "2"
   # Increment the build number to force new cartopy cache upload.
@@ -35,25 +46,6 @@ env:
   IRIS_TEST_DATA_DIR: ${HOME}/iris-test-data
 
 
-#
-# Linting
-#
-lint_task:
-  auto_cancellation: true
-  name: "${CIRRUS_OS}: flake8 and black"
-  pip_cache:
-    folder: ~/.cache/pip
-    fingerprint_script:
-      - echo "${CIRRUS_TASK_NAME}"
-      - echo "$(date +%Y).$(($(date +%U) / ${CACHE_PERIOD})):${PIP_CACHE_BUILD} ${PIP_CACHE_PACKAGES}"
-  lint_script:
-    - pip list
-    - python -m pip install --retries 3 --upgrade ${PIP_CACHE_PACKAGES}
-    - pip list
-    - nox --session flake8
-    - nox --session black
-
-
 #
 # YAML alias for common linux test infra-structure.
 #
@@ -68,7 +60,7 @@ linux_task_template: &LINUX_TASK_TEMPLATE
     fingerprint_script:
       - wget --quiet https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh -O miniconda.sh
       - echo "${CIRRUS_OS} $(sha256sum miniconda.sh)"
-      - echo "$(date +%Y).$(($(date +%U) / ${CACHE_PERIOD})):${CONDA_CACHE_BUILD}"
+      - echo "$(date +%Y).$(expr $(date +%U) / ${CACHE_PERIOD}):${CONDA_CACHE_BUILD}"
     populate_script:
       - bash miniconda.sh -b -p ${HOME}/miniconda
       - conda config --set always_yes yes --set changeps1 no
@@ -80,19 +72,49 @@ linux_task_template: &LINUX_TASK_TEMPLATE
     folder: ${HOME}/.local/share/cartopy
     fingerprint_script:
       - echo "${CIRRUS_OS}"
-      - echo "$(date +%Y).$(($(date +%U) / ${CACHE_PERIOD})):${CARTOPY_CACHE_BUILD}"
+      - echo "$(date +%Y).$(expr $(date +%U) / ${CACHE_PERIOD}):${CARTOPY_CACHE_BUILD}"
   nox_cache:
     folder: ${CIRRUS_WORKING_DIR}/.nox
     fingerprint_script:
       - echo "${CIRRUS_TASK_NAME}"
-      - echo "$(date +%Y).$(($(date +%U) / ${CACHE_PERIOD})):${NOX_CACHE_BUILD}"
+      - echo "$(date +%Y).$(expr $(date +%U) / ${CACHE_PERIOD}):${NOX_CACHE_BUILD}"
       - sha256sum ${CIRRUS_WORKING_DIR}/requirements/ci/py$(echo ${PY_VER} | tr -d ".").yml
 
 
+#
+# YAML alias for compute credits
+#
+compute_credits_template: &CREDITS_TEMPLATE
+  # Only use credits for non-DRAFT pull-requests to SciTools/iris master branch by collaborators
+  use_compute_credits: $CIRRUS_REPO_FULL_NAME == 'SciTools/iris' && $CIRRUS_USER_COLLABORATOR == 'true' && $CIRRUS_PR_DRAFT == 'false' && $CIRRUS_BASE_BRANCH == 'master' && $CIRRUS_PR != ''
+
+#
+# Linting
+#
+lint_task:
+  only_if: $SKIP_LINT_TASK == ""
+  << : *CREDITS_TEMPLATE
+  auto_cancellation: true
+  name: "${CIRRUS_OS}: flake8 and black"
+  pip_cache:
+    folder: ~/.cache/pip
+    fingerprint_script:
+      - echo "${CIRRUS_TASK_NAME}"
+      - echo "$(date +%Y).$(expr $(date +%U) / ${CACHE_PERIOD}):${PIP_CACHE_BUILD} ${PIP_CACHE_PACKAGES}"
+  lint_script:
+    - pip list
+    - python -m pip install --retries 3 --upgrade ${PIP_CACHE_PACKAGES}
+    - pip list
+    - nox --session flake8
+    - nox --session black
+
+
 #
 # Testing Minimal (Linux)
 #
-linux_minimal_task:
+test_minimal_task:
+  only_if: $SKIP_TEST_MINIMAL_TASK == "" && $SKIP_ALL_TEST_TASKS == ""
+  << : *CREDITS_TEMPLATE
   matrix:
     env:
       PY_VER: 3.6
@@ -113,7 +135,9 @@ linux_minimal_task:
 #
 # Testing Full (Linux)
 #
-linux_task:
+test_full_task:
+  only_if: $SKIP_TEST_FULL_TASK == "" && $SKIP_ALL_TEST_TASKS == ""
+  << : *CREDITS_TEMPLATE
   matrix:
     env:
       PY_VER: 3.6
@@ -144,6 +168,8 @@ linux_task:
 # Testing Documentation Gallery (Linux)
 #
 gallery_task:
+  only_if: $SKIP_GALLERY_TASK == "" && $SKIP_ALL_DOC_TASKS == ""
+  << : *CREDITS_TEMPLATE
   matrix:
     env:
       PY_VER: 3.6
@@ -174,6 +200,8 @@ gallery_task:
 # Testing Documentation (Linux)
 #
 doctest_task:
+  only_if: $SKIP_DOCTEST_TASK == "" && $SKIP_ALL_DOC_TASKS == ""
+  << : *CREDITS_TEMPLATE
   matrix:
     env:
       PY_VER: 3.7
@@ -207,7 +235,9 @@ doctest_task:
 #
 # Testing Documentation Link Check (Linux)
 #
-link_task:
+linkcheck_task:
+  only_if: $SKIP_LINKCHECK_TASK == "" && $SKIP_ALL_DOC_TASKS == ""
+  << : *CREDITS_TEMPLATE
   matrix:
     env:
       PY_VER: 3.7

diff --git a/docs/iris/gallery_code/general/plot_anomaly_log_colouring.py b/docs/iris/gallery_code/general/plot_anomaly_log_colouring.py
@@ -12,18 +12,15 @@
 "zero band" which is plotted in white.
 
 To do this, we create a custom value mapping function (normalization) using
-the matplotlib Norm class `matplotlib.colours.SymLogNorm
-<https://matplotlib.org/api/_as_gen/matplotlib.colors.SymLogNorm.html#matplotlib.colors.SymLogNorm>`_.
-We use this to make a cell-filled pseudocolour plot with a colorbar.
+the matplotlib Norm class :obj:`matplotlib.colors.SymLogNorm`.
+We use this to make a cell-filled pseudocolor plot with a colorbar.
 
 NOTE: By "pseudocolour", we mean that each data point is drawn as a "cell"
 region on the plot, coloured according to its data value.
 This is provided in Iris by the functions :meth:`iris.plot.pcolor` and
 :meth:`iris.plot.pcolormesh`, which call the underlying matplotlib
-functions of the same names (i.e. `matplotlib.pyplot.pcolor
-<http://matplotlib.org/api/pyplot_api.html#matplotlib.pyplot.pcolor>`_
-and  `matplotlib.pyplot.pcolormesh
-<http://matplotlib.org/api/pyplot_api.html#matplotlib.pyplot.pcolormesh>`_).
+functions of the same names (i.e., :obj:`matplotlib.pyplot.pcolor`
+and :obj:`matplotlib.pyplot.pcolormesh`).
 See also: http://en.wikipedia.org/wiki/False_color#Pseudocolor.
 
 """
@@ -65,7 +62,7 @@ def main():
 
     # Use a standard colour map which varies blue-white-red.
     # For suitable options, see the 'Diverging colormaps' section in:
-    # http://matplotlib.org/examples/color/colormaps_reference.html
+    # http://matplotlib.org/stable/gallery/color/colormap_reference.html
     anom_cmap = "bwr"
 
     # Create a 'logarithmic' data normalization.

diff --git a/docs/iris/src/common_links.inc b/docs/iris/src/common_links.inc
@@ -1,9 +1,11 @@
 .. _SciTools: https://github.com/SciTools
+.. _black: https://black.readthedocs.io/en/stable/
 .. _Iris: https://github.com/SciTools/iris
 .. _Iris GitHub: https://github.com/SciTools/iris
 .. _iris mailing list: https://groups.google.com/forum/#!forum/scitools-iris
 .. _issue: https://github.com/SciTools/iris/issues
 .. _issues: https://github.com/SciTools/iris/issues
+.. _matplotlib: https://matplotlib.org/stable/
 .. _pull request: https://github.com/SciTools/iris/pulls
 .. _pull requests: https://github.com/SciTools/iris/pulls
 .. _contributor: https://github.com/SciTools/scitools.org.uk/blob/master/contributors.json
@@ -14,14 +16,13 @@
 .. _readthedocs.yml: https://github.com/SciTools/iris/blob/master/requirements/ci/readthedocs.yml
 .. _cirrus-ci: https://cirrus-ci.com/github/SciTools/iris
 .. _.cirrus.yml: https://github.com/SciTools/iris/blob/master/.cirrus.yml
+.. _flake8: https://flake8.pycqa.org/en/stable/
 .. _.flake8.yml: https://github.com/SciTools/iris/blob/master/.flake8
 .. _GitHub Help Documentation: https://docs.github.com/en/github
 .. _using git: https://docs.github.com/en/github/using-git
 .. _generating sss keys for GitHub: https://docs.github.com/en/github/authenticating-to-github/adding-a-new-ssh-key-to-your-github-account
 .. _New Issue: https://github.com/scitools/iris/issues/new/choose
-.. _matplotlib: https://matplotlib.org/
 .. _conda: https://docs.conda.io/en/latest/
 .. _sphinx: https://www.sphinx-doc.org/en/master/
 .. _napolean: https://sphinxcontrib-napoleon.readthedocs.io/en/latest/sphinxcontrib.napoleon.html
 .. _legacy documentation: https://scitools.org.uk/iris/docs/v2.4.0/
-.. _cirrus-ci: https://cirrus-ci.com/github/SciTools/iris
diff --git a/docs/iris/src/conf.py b/docs/iris/src/conf.py
@@ -179,18 +179,18 @@ def autolog(message):
 # -- intersphinx extension ----------------------------------------------------
 # See https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html
 intersphinx_mapping = {
-    "cartopy": ("http://scitools.org.uk/cartopy/docs/latest/", None),
-    "matplotlib": ("http://matplotlib.org/", None),
-    "numpy": ("http://docs.scipy.org/doc/numpy/", None),
-    "python": ("http://docs.python.org/2.7", None),
-    "scipy": ("http://docs.scipy.org/doc/scipy/reference/", None),
+    "cartopy": ("https://scitools.org.uk/cartopy/docs/latest/", None),
+    "matplotlib": ("https://matplotlib.org/stable/", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+    "python": ("https://docs.python.org/3/", None),
+    "scipy": ("https://docs.scipy.org/doc/scipy/reference/", None),
 }
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = "sphinx"
 
 # -- plot_directive extension -------------------------------------------------
-# See https://matplotlib.org/3.1.3/devel/plot_directive.html#options
+# See https://matplotlib.org/stable/api/sphinxext_plot_directive_api.html#options
 plot_formats = [
     ("png", 100),
 ]

diff --git a/docs/iris/src/developers_guide/contributing_ci_tests.rst b/docs/iris/src/developers_guide/contributing_ci_tests.rst
@@ -5,9 +5,9 @@
 Continuous Integration (CI) Testing
 ===================================
 
-The `Iris`_ GitHub repository is configured to run checks on the code
-automatically when a pull request is created, updated or merged against
-Iris **master**.  The checks performed are:
+The `Iris`_ GitHub repository is configured to run checks against all its
+branches automatically whenever a pull request is created, updated or merged.
+The checks performed are:
 
 * :ref:`testing_cla`
 * :ref:`testing_cirrus`
@@ -18,29 +18,65 @@ Iris **master**.  The checks performed are:
 SciTools CLA Checker
 ********************
 
-A bot that checks the user who created the pull request has signed the
-**Contributor's License Agreement (CLA)**.  For more information on this this
-please see https://scitools.org.uk/organisation.html#governance
+A bot which checks that the GitHub author of the pull request has signed the
+**SciTools Contributor's License Agreement (CLA)**.  For more information on
+this please see https://scitools.org.uk/organisation.html#governance.
 
 
 .. _testing_cirrus:
 
 Cirrus-CI
 *********
 
-The unit and integration tests in Iris are an essential mechanism to ensure
+Iris unit and integration tests are an essential mechanism to ensure
 that the Iris code base is working as expected.  :ref:`developer_running_tests`
-may be run manually but to ensure the checks are performed a
-continuous integration testing tool named `cirrus-ci`_ is used.
+may be performed manually by a developer locally. However Iris is configured to
+use the `cirrus-ci`_ service for automated Continuous Integration (CI) testing.
 
-A `cirrus-ci`_ configuration file named `.cirrus.yml`_
-is in the Iris repository which tells Cirrus-CI what commands to run.  The
-commands include retrieving the Iris code base and associated test files using
-conda and then running the tests.  `cirrus-ci`_ allows for a matrix of tests to
-be performed to ensure that all expected variations test successfully.
+The `cirrus-ci`_ configuration file  `.cirrus.yml`_ in the root of the Iris repository
+defines the tasks to be performed by `cirrus-ci`_. For further details
+refer to the `Cirrus-CI Documentation`_. The tasks performed during CI include:
+
+* linting the code base and ensuring it adheres to the `black`_ format
+* running the system, integration and unit tests for Iris
+* ensuring the documentation gallery builds successfully
+* performing all doc-tests within the code base
+* checking all URL references within the code base and documentation are valid
+
+The above `cirrus-ci`_ tasks are run automatically against all `Iris`_ branches
+on GitHub whenever a pull request is submitted, updated or merged. See the
+`Cirrus-CI Dashboard`_ for details of recent past and active Iris jobs.
+
+.. _skipping Cirrus-CI tasks:
+
+Skipping Cirrus-CI Tasks
+------------------------
+
+As a developer you may wish to not run all the CI tasks when you are actively
+developing e.g., you are writing documentation and there is no need for linting,
+or long running compute intensive testing tasks to be executed.
+
+As a convenience, it is possible to easily skip one or more tasks by setting
+the appropriate environment variable within the `.cirrus.yml`_ file to a
+**non-empty** string:
+
+* ``SKIP_LINT_TASK`` to skip `flake8`_ linting and `black`_ formatting
+* ``SKIP_TEST_MINIMAL_TASK`` to skip restricted unit and integration testing
+* ``SKIP_TEST_FULL_TASK`` to skip full unit and integration testing
+* ``SKIP_GALLERY_TASK`` to skip building the documentation gallery
+* ``SKIP_DOCTEST_TASK`` to skip running the documentation doc-tests
+* ``SKIP_LINKCHECK_TASK`` to skip checking for broken documentation URL references
+* ``SKIP_ALL_TEST_TASKS`` which is equivalent to setting ``SKIP_TEST_MINIMAL_TASK`` and ``SKIP_TEST_FULL_TASK``
+* ``SKIP_ALL_DOC_TASKS`` which is equivalent to setting ``SKIP_GALLERY_TASK``, ``SKIP_DOCTEST_TASK``, and ``SKIP_LINKCHECK_TASK``
+
+e.g., to skip the linting task, the following are all equivalent::
+
+   SKIP_LINT_TASK: "1"
+   SKIP_LINT_TASK: "true"
+   SKIP_LINT_TASK: "false"
+   SKIP_LINT_TASK: "skip"
+   SKIP_LINT_TASK: "unicorn"
 
-The `cirrus-ci`_ tests are run automatically against the `Iris`_ master
-repository when a pull request is submitted, updated or merged.
 
 GitHub Checklist
 ****************
@@ -50,6 +86,10 @@ passing:
 
 .. image:: ci_checks.png
 
-If any CI checks fail, then the pull request is unlikely to be merged to the
+If any CI tasks fail, then the pull request is unlikely to be merged to the
 Iris target branch by a core developer.
 
+
+.. _Cirrus-CI Dashboard: https://cirrus-ci.com/github/SciTools/iris
+.. _Cirrus-CI Documentation: https://cirrus-ci.org/guide/writing-tasks/
+
diff --git a/docs/iris/src/developers_guide/contributing_code_formatting.rst b/docs/iris/src/developers_guide/contributing_code_formatting.rst
@@ -58,6 +58,4 @@ will look similar to::
           their officially documentation for more information.
 
 
-.. _black: https://black.readthedocs.io/en/stable/
-.. _flake8: https://flake8.pycqa.org/en/stable/
 .. _pre-commit: https://pre-commit.com/