Merge branch 'master' into docs_stable_show_version

* master:
  make iris.common.metadata._hexdigest public (SciTools#4020)
  cirrus-ci conditional tasks (SciTools#4019)

.cirrus.yml

@@ -18,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.
@@ -50,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
@@ -62,12 +72,12 @@ 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
 
 
@@ -82,14 +92,15 @@ compute_credits_template: &CREDITS_TEMPLATE
 # 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).$(($(date +%U) / ${CACHE_PERIOD})):${PIP_CACHE_BUILD} ${PIP_CACHE_PACKAGES}"
+      - 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}
@@ -101,7 +112,8 @@ lint_task:
 #
 # Testing Minimal (Linux)
 #
-linux_minimal_task:
+test_minimal_task:
+  only_if: $SKIP_TEST_MINIMAL_TASK == "" && $SKIP_ALL_TEST_TASKS == ""
   << : *CREDITS_TEMPLATE
   matrix:
     env:
@@ -125,7 +137,8 @@ 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:
@@ -159,6 +172,7 @@ linux_task:
 # Testing Documentation Gallery (Linux)
 #
 gallery_task:
+  only_if: $SKIP_GALLERY_TASK == "" && $SKIP_ALL_DOC_TASKS == ""
   << : *CREDITS_TEMPLATE
   matrix:
     env:
@@ -188,6 +202,7 @@ gallery_task:
 # Testing Documentation (Linux)
 #
 doctest_task:
+  only_if: $SKIP_DOCTEST_TASK == "" && $SKIP_ALL_DOC_TASKS == ""
   << : *CREDITS_TEMPLATE
   matrix:
     env:
@@ -222,7 +237,8 @@ doctest_task:
 #
 # Testing Documentation Link Check (Linux)
 #
-link_task:
+linkcheck_task:
+  only_if: $SKIP_LINKCHECK_TASK == "" && $SKIP_ALL_DOC_TASKS == ""
   << : *CREDITS_TEMPLATE
   matrix:
     env:

docs/src/common_links.inc

@@ -3,6 +3,7 @@
 
 .. _black: https://black.readthedocs.io/en/stable/
 .. _.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
 .. _cirrus-ci: https://cirrus-ci.com/github/SciTools/iris
 .. _conda: https://docs.conda.io/en/latest/

docs/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/
+

docs/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/

docs/src/whatsnew/latest.rst

@@ -42,6 +42,12 @@ This document explains the changes made to Iris for this release
    ``iris.plot.plot(z_cube)`` will produce a z-vs-phenomenon plot, where before
    it would have produced a phenomenon-vs-z plot. (:pull:`3906`)
 
+#. `@bjlittle`_ introduced :func:`iris.common.metadata.hexdigest` to the
+   public API. Previously it was a private function introduced in ``v3.0.0``.
+   Given any object, :func:`~iris.common.metadata.hexdigest` returns a string
+   representation of the 64-bit non-cryptographic hash of the object using the
+   extremely fast `xxhash`_ hashing algorithm. (:pull:`4020`)
+
 
 🐛 Bugs Fixed
 =============
@@ -124,6 +130,10 @@ This document explains the changes made to Iris for this release
 #. `@akuhnregnier`_ replaced `deprecated numpy 1.20 aliases for builtin types`_.
    (:pull:`3997`)
 
+#. `@bjlittle`_ added conditional task execution to `.cirrus.yml`_ to allow
+   developers to easily disable `cirrus-ci`_ tasks. See
+   :ref:`skipping Cirrus-CI tasks`. (:pull:`4019`)
+
 
 .. comment
     Whatsnew author names (@github name) in alphabetical order. Note that,
@@ -146,3 +156,4 @@ This document explains the changes made to Iris for this release
 .. _PyPI: https://pypi.org/project/scitools-iris/
 .. _Python 3.8: https://www.python.org/downloads/release/python-380/
 .. _README.md: https://github.com/SciTools/iris#-----
+.. _xxhash: http://cyan4973.github.io/xxHash/

lib/iris/_representation.py

@@ -9,7 +9,7 @@
 import re
 
 import iris.util
-from iris.common.metadata import _hexdigest as quickhash
+from iris.common.metadata import hexdigest
 
 
 class DimensionHeader:
@@ -101,7 +101,7 @@ def _summary_coord_extra(self, cube, coord):
                     # ..except setdefault fails if values are numpy arrays.
                     if key not in attributes:
                         attributes[key] = value
-                    elif quickhash(attributes[key]) != quickhash(value):
+                    elif hexdigest(attributes[key]) != hexdigest(value):
                         # NOTE: fast and array-safe comparison, as used in
                         # :mod:`iris.common.metadata`.
                         vary.add(key)