Merge branch 'main' into theme_play

* main: (71 commits)
  Skip TestConstrainedLoad if data missing (SciTools#4319)
  Add 'Good First Issue' label to reasons an issue doesn't go stale (SciTools#4317)
  Gallery: simplify quiver example (SciTools#4120)
  Improve styling in a minor way in docs (SciTools#4314)
  bump version (SciTools#4310)
  Made clear we only test on Linux. (SciTools#4309)
  Updated environment lockfiles (SciTools#4308)
  Include Discussions in Getting Involved. (SciTools#4307)
  Fixed text to show as link. (SciTools#4305)
  [pre-commit.ci] pre-commit autoupdate (SciTools#4299)
  Updated environment lockfiles (SciTools#4298)
  cartopy feature download (SciTools#4304)
  Mesh Loading (AVD-1813) (SciTools#4262)
  reset whatsnew latest (SciTools#4288)
  Updated environment lockfiles (SciTools#4289)
  Update cube.py (SciTools#4287)
  Integrated whatsnew for v3.1 release (rc0) (SciTools#4285)
  Version changes and final whatsnew tweaks for 3v1rc0. (SciTools#4284)
  Missing whatsnew entries for 3.1 release. (SciTools#4283)
  Update CF standard name table to v77 (SciTools#4282)
  ...

Author: tkknight

.cirrus.yml

@@ -26,7 +26,7 @@ env:
   # Maximum cache period (in weeks) before forcing a new cache upload.
   CACHE_PERIOD: "2"
   # Increment the build number to force new cartopy cache upload.
-  CARTOPY_CACHE_BUILD: "0"
+  CARTOPY_CACHE_BUILD: "3"
   # Increment the build number to force new conda cache upload.
   CONDA_CACHE_BUILD: "0"
   # Increment the build number to force new nox cache upload.
@@ -38,7 +38,7 @@ env:
   # Conda packages to be installed.
   CONDA_CACHE_PACKAGES: "nox pip"
   # Git commit hash for iris test data.
-  IRIS_TEST_DATA_VERSION: "2.0.0"
+  IRIS_TEST_DATA_VERSION: "2.4"
   # Base directory for the iris-test-data.
   IRIS_TEST_DATA_DIR: ${HOME}/iris-test-data
 
@@ -72,6 +72,14 @@ linux_task_template: &LINUX_TASK_TEMPLATE
     fingerprint_script:
       - echo "${CIRRUS_OS}"
       - echo "$(date +%Y).$(expr $(date +%U) / ${CACHE_PERIOD}):${CARTOPY_CACHE_BUILD}"
+    populate_script:
+      - conda create --quiet --name cartopy-cache cartopy
+      - source ${HOME}/miniconda/etc/profile.d/conda.sh >/dev/null 2>&1
+      - conda activate cartopy-cache >/dev/null 2>&1
+      - cd $(mktemp -d)
+      - wget --quiet https://raw.githubusercontent.com/SciTools/cartopy/master/tools/cartopy_feature_download.py
+      - python cartopy_feature_download.py physical --output ${HOME}/.local/share/cartopy --no-warn
+      - conda deactivate >/dev/null 2>&1
   nox_cache:
     folder: ${CIRRUS_WORKING_DIR}/.nox
     reupload_on_changes: true
@@ -105,7 +113,7 @@ iris_test_data_template: &IRIS_TEST_DATA_TEMPLATE
 #
 # Linting
 #
-precommit_task:
+task:
   only_if: ${SKIP_LINT_TASK} == ""
   << : *CREDITS_TEMPLATE
   auto_cancellation: true
@@ -129,7 +137,7 @@ precommit_task:
 #
 # Testing (Linux)
 #
-test_task:
+task:
   only_if: ${SKIP_TEST_TASK} == ""
   << : *CREDITS_TEMPLATE
   matrix:
@@ -155,7 +163,7 @@ test_task:
 #
 # Documentation Testing and Gallery (Linux)
 #
-doctest_task:
+task:
   only_if: ${SKIP_DOCTEST_TASK} == "" && ${SKIP_ALL_DOC_TASKS} == ""
   << : *CREDITS_TEMPLATE
   env:
@@ -179,7 +187,7 @@ doctest_task:
 #
 # Documentation Link Check (Linux)
 #
-linkcheck_task:
+task:
   only_if: ${SKIP_LINKCHECK_TASK} == "" && ${SKIP_ALL_DOC_TASKS} == ""
   << : *CREDITS_TEMPLATE
   env:

.github/workflows/benchmark.yml

@@ -0,0 +1,48 @@
+# This is a basic workflow to help you get started with Actions
+
+name: benchmark-check
+
+on:
+  # Triggers the workflow on push or pull request events but only for the master branch
+  pull_request:
+
+jobs:
+  benchmark:
+    runs-on: ubuntu-latest
+
+    steps:
+      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
+      - uses: actions/checkout@v2
+
+      - name: Checkout the branches
+        run: |
+          git fetch --depth=1 origin ${{ github.event.pull_request.base.ref }}
+          git branch _base FETCH_HEAD
+          git fetch --depth=1 origin ${{ github.ref }}
+          git branch _head FETCH_HEAD
+
+      - name: Setup asv
+        run: |
+          pip install asv
+          cd benchmarks
+          asv machine --yes
+
+      - name: Run benchmarks on source and target
+        run: |
+          cd benchmarks
+          asv continuous --factor 1.2 _base _head
+
+      - name: Write a compare file to the output folder
+        if: ${{ always() }}
+        run: |
+          cd benchmarks
+          asv compare -s _base _head > .asv/compare.txt
+
+      - name: Archive asv results
+        if: ${{ always() }}
+        uses: actions/upload-artifact@v2
+        with:
+          name: asv-report
+          path: |
+            benchmarks/.asv/results
+            benchmarks/.asv/compare.txt

.github/workflows/stale.yml

@@ -0,0 +1,78 @@
+# See https://github.com/actions/stale
+
+name: Stale issues and pull-requests
+on:
+  schedule:
+    - cron: 0 0 * * *
+
+jobs:
+  stale:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/[email protected]
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+
+          # Idle number of days before marking issues/prs stale.
+          days-before-stale: 500
+
+          # Idle number of days before closing stale issues/prs.
+          days-before-close: 28
+
+          # Comment on the staled issues.
+          stale-issue-message: |
+            In order to maintain a backlog of relevant issues, we automatically label them as stale after 500 days of inactivity.
+
+            If this issue is still important to you, then please comment on this issue and the stale label will be removed.
+
+            Otherwise this issue will be automatically closed in 28 days time.
+
+          # Comment on the staled prs.
+          stale-pr-message: | 
+            In order to maintain a backlog of relevant PRs, we automatically label them as stale after 500 days of inactivity.
+
+            If this PR is still important to you, then please comment on this PR and the stale label will be removed.
+
+            Otherwise this PR will be automatically closed in 28 days time.
+
+          # Comment on the staled issues while closed.
+          close-issue-message: |
+            This stale issue has been automatically closed due to a lack of community activity.
+            
+            If you still care about this issue, then please either:
+              * Re-open this issue, if you have sufficient permissions, or
+              * Add a comment pinging `@SciTools/iris-devs` who will re-open on your behalf.
+
+          # Comment on the staled prs while closed.
+          close-pr-message: |
+            This stale PR has been automatically closed due to a lack of community activity.
+            
+            If you still care about this PR, then please either:
+              * Re-open this PR, if you have sufficient permissions, or
+              * Add a comment pinging `@SciTools/iris-devs` who will re-open on your behalf.
+
+          # Label to apply on staled issues. 
+          stale-issue-label: Stale
+
+          # Label to apply on staled prs.
+          stale-pr-label: Stale
+
+          # Labels on issues exempted from stale.
+          exempt-issue-labels: |
+            "Status: Blocked,Status: Decision Required,Peloton 🚴‍♂️,Good First Issue"
+
+          # Labels on prs exempted from stale.
+          exempt-pr-labels: |
+            "Status: Blocked,Status: Decision Required,Peloton 🚴‍♂️,Good First Issue"
+
+          # Max number of operations per run.
+          operations-per-run: 300
+
+          # Remove stale label from issues/prs on updates/comments.
+          remove-stale-when-updated: true
+
+          # Order to get issues/PRs.
+          ascending: true
+
+          # Exempt all issues/prs with milestones from stale.
+          exempt-all-milestones: true

.pre-commit-config.yaml

@@ -28,7 +28,7 @@ repos:
     -   id: no-commit-to-branch
 
 -   repo: https://github.com/psf/black
-    rev: 21.7b0
+    rev: 21.8b0
     hooks:
     -   id: black
         pass_filenames: false
@@ -42,14 +42,14 @@ repos:
         args: [--config=./setup.cfg]
 
 -   repo: https://github.com/pycqa/isort
-    rev: 5.9.2
+    rev: 5.9.3
     hooks:
     -   id: isort
         types: [file, python]
         args: [--filter-files]
 
 -   repo: https://github.com/asottile/blacken-docs
-    rev: v1.10.0
+    rev: v1.11.0
     hooks:
     -   id: blacken-docs
         types: [file, rst]

MANIFEST.in

@@ -4,6 +4,7 @@ include CHANGES COPYING COPYING.LESSER
 # Files from setup.py package_data that are not automatically added to source distributions
 recursive-include lib/iris/tests/results *.cml *.cdl *.txt *.xml *.json
 recursive-include lib/iris/etc *
+include lib/iris/tests/stock/file_headers/*
 
 recursive-include requirements *
 

asv.conf.json

@@ -0,0 +1,17 @@
+{
+    "version": 1,
+    "project": "scitools-iris",
+    "project_url": "https://github.com/SciTools/iris",
+    "repo": "..",
+    "environment_type": "conda-lock",
+    "show_commit_url": "http://github.com/scitools/iris/commit/",
+
+    "benchmark_dir": "./benchmarks",
+    "env_dir": ".asv/env",
+    "results_dir": ".asv/results",
+    "html_dir": ".asv/html",
+    "plugins": [".conda_lock_plugin"],
+    // this is not an asv standard config entry, just for our plugin
+    // path to lockfile, relative to project base
+    "conda_lockfile": "requirements/ci/nox.lock/py38-linux-64.lock"
+}

benchmarks/asv.conf.json

@@ -0,0 +1,49 @@
+# Copyright Iris contributors
+#
+# This file is part of Iris and is released under the LGPL license.
+# See COPYING and COPYING.LESSER in the root of the repository for full
+# licensing details.
+"""Common code for benchmarks."""
+
+import os
+from pathlib import Path
+
+# Environment variable names
+_ASVDIR_VARNAME = "ASV_DIR"  # As set in nightly script "asv_nightly/asv.sh"
+_DATADIR_VARNAME = "BENCHMARK_DATA"  # For local runs
+
+ARTIFICIAL_DIM_SIZE = int(10e3)  # For all artificial cubes, coords etc.
+
+# Work out where the benchmark data dir is.
+asv_dir = os.environ.get("ASV_DIR", None)
+if asv_dir:
+    # For an overnight run, this comes from the 'ASV_DIR' setting.
+    benchmark_data_dir = Path(asv_dir) / "data"
+else:
+    # For a local run, you set 'BENCHMARK_DATA'.
+    benchmark_data_dir = os.environ.get(_DATADIR_VARNAME, None)
+    if benchmark_data_dir is not None:
+        benchmark_data_dir = Path(benchmark_data_dir)
+
+
+def testdata_path(*path_names):
+    """
+    Return the path of a benchmark test data file.
+
+    These are based from a test-data location dir, which is either
+    ${}/data (for overnight tests), or ${} for local testing.
+
+    If neither of these were set, an error is raised.
+
+    """.format(
+        _ASVDIR_VARNAME, _DATADIR_VARNAME
+    )
+    if benchmark_data_dir is None:
+        msg = (
+            "Benchmark data dir is not defined : "
+            'Either "${}" or "${}" must be set.'
+        )
+        raise (ValueError(msg.format(_ASVDIR_VARNAME, _DATADIR_VARNAME)))
+    path = benchmark_data_dir.joinpath(*path_names)
+    path = str(path)  # Because Iris doesn't understand Path objects yet.
+    return path

benchmarks/benchmarks/__init__.py

@@ -0,0 +1,59 @@
+# Copyright Iris contributors
+#
+# This file is part of Iris and is released under the LGPL license.
+# See COPYING and COPYING.LESSER in the root of the repository for full
+# licensing details.
+"""
+AuxFactory benchmark tests.
+
+"""
+
+import numpy as np
+
+from benchmarks import ARTIFICIAL_DIM_SIZE
+from iris import aux_factory, coords
+
+
+class FactoryCommon:
+    # TODO: once https://github.com/airspeed-velocity/asv/pull/828 is released:
+    #       * make class an ABC
+    #       * remove NotImplementedError
+    #       * combine setup_common into setup
+
+    """
+    A base class running a generalised suite of benchmarks for any factory.
+    Factory to be specified in a subclass.
+
+    ASV will run the benchmarks within this class for any subclasses.
+
+    Should only be instantiated within subclasses, but cannot enforce this
+    since ASV cannot handle classes that include abstract methods.
+    """
+
+    def setup(self):
+        """Prevent ASV instantiating (must therefore override setup() in any subclasses.)"""
+        raise NotImplementedError
+
+    def setup_common(self):
+        """Shared setup code that can be called by subclasses."""
+        self.factory = self.create()
+
+    def time_create(self):
+        """Create an instance of the benchmarked factory. create method is
+        specified in the subclass."""
+        self.create()
+
+    def time_return(self):
+        """Return an instance of the benchmarked factory."""
+        self.factory
+
+
+class HybridHeightFactory(FactoryCommon):
+    def setup(self):
+        data_1d = np.zeros(ARTIFICIAL_DIM_SIZE)
+        self.coord = coords.AuxCoord(points=data_1d, units="m")
+
+        self.setup_common()
+
+    def create(self):
+        return aux_factory.HybridHeightFactory(delta=self.coord)