Pp derived bounds

.github/workflows/benchmarks_report.yml

@@ -80,4 +80,4 @@ jobs:
       - name: Post reports
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: python benchmarks/bm_runner.py _gh_post
+        run: benchmarks/bm_runner.py _gh_post

.github/workflows/benchmarks_run.yml

@@ -21,6 +21,8 @@ on:
 
 jobs:
   pre-checks:
+    # This workflow supports two different scenarios (overnight and branch).
+    #  The pre-checks job determines which scenario is being run.
     runs-on: ubuntu-latest
     if: github.repository == 'SciTools/iris'
     outputs:
@@ -36,9 +38,11 @@ jobs:
           # SEE ALSO .github/labeler.yml .
           paths: requirements/locks/*.lock setup.py
       - id: overnight
+        name: Check overnight scenario
         if: github.event_name != 'pull_request'
         run: echo "check=true" >> "$GITHUB_OUTPUT"
       - id: branch
+        name: Check branch scenario
         if: >
           github.event_name == 'pull_request'
           &&
@@ -67,13 +71,14 @@ jobs:
 
     steps:
       # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
-      - uses: actions/checkout@v4
+      - name: Checkout repo
+        uses: actions/checkout@v4
         with:
           fetch-depth: 0
 
       - name: Install Nox
         run: |
-          pip install nox
+          pip install nox!=2025.05.01
 
       - name: Cache environment directories
         id: cache-env-dir
@@ -107,6 +112,8 @@ jobs:
           echo "OVERRIDE_TEST_DATA_REPOSITORY=${GITHUB_WORKSPACE}/${IRIS_TEST_DATA_PATH}/test_data" >> $GITHUB_ENV
 
       - name: Benchmark this pull request
+        # If the 'branch' condition(s) are met: use the bm_runner to compare
+        #  the proposed merge with the base branch.
         if: needs.pre-checks.outputs.branch == 'true'
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -115,10 +122,14 @@ jobs:
           nox -s benchmarks -- branch origin/${{ github.base_ref }}
 
       - name: Run overnight benchmarks
+        # If the 'overnight' condition(s) are met: use the bm_runner to compare
+        #  each of the last 24 hours' commits to their parents.
         id: overnight
         if: needs.pre-checks.outputs.overnight == 'true'
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        # The first_commit argument allows a custom starting point - useful
+        #  for manual re-running.
         run: |
           first_commit=${{ inputs.first_commit }}
           if [ "$first_commit" == "" ]
@@ -132,6 +143,8 @@ jobs:
           fi
 
       - name: Warn of failure
+        # The overnight run is not on a pull request, so a failure could go
+        #  unnoticed without being actively advertised.
         if: >
           failure() &&
           steps.overnight.outcome == 'failure'
@@ -143,13 +156,15 @@ jobs:
           gh issue create --title "$title" --body "$body" --label "Bot" --label "Type: Performance" --repo $GITHUB_REPOSITORY
 
       - name: Upload any benchmark reports
+        # Uploading enables more downstream processing e.g. posting a PR comment.
         if: success() || steps.overnight.outcome == 'failure'
         uses: actions/upload-artifact@v4
         with:
           name: benchmark_reports
           path: .github/workflows/benchmark_reports
 
       - name: Archive asv results
+        # Store the raw ASV database(s) to help manual investigations.
         if: ${{ always() }}
         uses: actions/upload-artifact@v4
         with:

.github/workflows/ci-linkchecks.yml

@@ -0,0 +1,35 @@
+name: Linkcheck
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "00 06 * * *"
+
+jobs:
+  linkChecker:
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write # required for peter-evans/create-issue-from-file
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Link Checker
+        id: lychee
+        uses: lycheeverse/lychee-action@82202e5e9c2f4ef1a55a3d02563e1cb6041e5332
+        with:
+          token: ${{secrets.GITHUB_TOKEN}}
+          fail: false
+          args: "--verbose --max-concurrency 1 './docs/**/*.rst' './docs/**/*.inc' './lib/**/*.py'"
+
+      - name: Create Issue From File
+        if: steps.lychee.outputs.exit_code != 0
+        uses: peter-evans/create-issue-from-file@e8ef132d6df98ed982188e460ebb3b5d4ef3a9cd
+        with:
+          title: Link Checker Report
+          content-filepath: ./lychee/out.md
+          labels: "Bot, Type: Documentation, Type: Bug"
+
+      - name: Fail Workflow On Link Errors
+        if: steps.lychee.outputs.exit_code != 0
+        run:
+          exit {{ steps.lychee.outputs.exit_code }}

.github/workflows/ci-manifest.yml

@@ -23,4 +23,4 @@ concurrency:
 jobs:
   manifest:
     name: "check-manifest"
-    uses: scitools/workflows/.github/workflows/ci-manifest.yml@2025.02.3
+    uses: scitools/workflows/.github/workflows/ci-manifest.yml@2025.05.4

.github/workflows/ci-template-check.yml

@@ -0,0 +1,16 @@
+# Checks if a PR makes any changes that ought to be shared via templating.
+# See the called workflow in the scitools/workflows repo for more details.
+
+name: ci-template-check
+
+on:
+  pull_request_target:
+    branches:
+      - main
+
+jobs:
+  prompt-share:
+    uses: scitools/workflows/.github/workflows/[email protected]
+    secrets: inherit
+    with:
+      pr_number: ${{ github.event.pull_request.number }}

.github/workflows/ci-tests.yml

@@ -36,7 +36,7 @@ jobs:
       matrix:
         os: ["ubuntu-latest"]
         python-version: ["3.13"]
-        session: ["doctest", "gallery", "linkcheck"]
+        session: ["doctest", "gallery"]
         include:
           - os: "ubuntu-latest"
             python-version: "3.13"

.github/workflows/refresh-lockfiles.yml

@@ -14,5 +14,5 @@ on:
 
 jobs:
   refresh_lockfiles:
-    uses: scitools/workflows/.github/workflows/refresh-lockfiles.yml@2025.02.3
+    uses: scitools/workflows/.github/workflows/refresh-lockfiles.yml@2025.05.4
     secrets: inherit

.lycheeignore

@@ -0,0 +1,59 @@
+# nonfunctional, found in some code examples
+file:///
+
+# DEAD : legacy in various old whatsnews
+https://biggus.readthedocs.io
+
+# unkown problem, works in browser : used in further_topics/ugrid/data_model
+https://doi.org/10.3390/jmse2010194
+
+# DEAD, todo:remove, used in docs/src/userguide/plotting_a_cube.rst
+https://effbot.org
+
+# nonfunctional, found in some code examples
+https://foo/
+
+# DEAD, todo:remove, used in docs/src/further_topics/ugrid/data_model.rst
+https://ibm-design-language.eu-de.mybluemix.net/design/language/resources/color-library
+
+# DEAD, legacy in whatsnew/1.4.rst
+https://geoport.whoi.edu/thredds/dodsC/bathy/gom15
+
+# exist, but bad certificates
+https://georepository.com
+https://geoport.whoi.edu:80/thredds/
+
+# catch (at least) github userids, of which many in whatsnews, too many --> "too many requests" failures
+https://github.com/[^/]*$
+
+# GitHub seems especially keen to rate-limit "blob" URLs.
+#  (maybe because these are especially associated with abuse?)
+https://github.com/[^/]*/[^/]*/blob/.*
+
+# nonfunctional example, used in docs/src/developers_guide/gitwash/development_workflow.rst
+https://github.com/your-user-name/iris
+
+# problem with bad certificate (review sometime?)
+https://scitools.github.com/cartopy
+
+# returns 403 when accessed from GitHub Actions
+https://stackoverflow.com
+
+# legacy ref in whatsnew/3.0.rst
+https://stickler-ci.com
+
+# DEAD, todo:remove, used in lib/iris/symbols.py
+https://www.wmo.int/pages/prog/www/DPFS/documents/485_Vol_I_en_colour.pdf
+
+# DEAD, todo:remove, used in docs/src/userguide/plotting_a_cube.rst
+# unkown problem, works in browser : used in docs/src/index.rst
+https://www.flaticon.com
+
+# nonfunctional example, used in lib/iris/io/__init__.py
+https://www.thing.com
+
+# DEAD, todo:remove, used in docs/src/userguide/plotting_a_cube.rst
+https://www.personal.psu.edu/cab38/ColorBrewer/ColorBrewer_updates.html
+
+# nonfunctional, found in some code examples
+https://www.somehost.com

.pre-commit-config.yaml

@@ -29,7 +29,7 @@ repos:
     -   id: no-commit-to-branch
 
 -   repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: "v0.9.7"
+    rev: "v0.11.11"
     hooks:
     -   id: ruff
         types: [file, python]
@@ -45,7 +45,7 @@ repos:
         additional_dependencies: [tomli]
 
 -   repo: https://github.com/PyCQA/flake8
-    rev: 7.1.2
+    rev: 7.2.0
     hooks:
     -   id: flake8
         types: [file, python]

MANIFEST.in

@@ -1,33 +1,112 @@
-prune .github
-prune benchmarks
-prune docs
-prune etc
+# NOTE: based on a generic template in Scitools/.github/templates/MANIFEST.in
+
+# General principles
+#     - enable user to build locally, as well as in CI
+#     - make it ignore temporary files generated by dev processes, e.g. coverage checks
+#     - encode typical decisions, e.g. whether we package docs, requirements etc
+
+#---------
+# SECTION: main code sources
+# N.B. package dir is "lib" not "src"
 recursive-include lib *.cdl *.cml *.json *.md *.py *.template *.txt *.xml
+    # principles:
+    #    - *no* "prune" command is used
+    #    - use "include-recursive", by relevant file extensions
+    # hints:
+    #     - top-level dir is typically "src", but maybe "lib" or <package-name>
+    #     - default package rules mean we generally don't actually *need* a statement
+    #         - but it's better to be explicit
+    #     - extension filetypes are typically sources (*.py)
+    #         - might also need testdata files, e.g. *.nc, *.npy *.npz
+    #         - also possibly non-python, e.g. *.pyx for Cython
+
+
+#---------
+# SECTION: docs
+prune docs
+# and if required ... include ONLY docs source files.
+# E.G. recursive-include docs *.rst *.inc
+    # principles:
+    #    - use prune to ignore everything (optionally: except the docs sources)
+    # hints:
+    #    - most projects don't want to package the docs, but some currently do (cf-units).
+
+
+#---------
+# SECTION: requirements
 prune requirements
 recursive-include requirements *.txt
-prune tools
+    # principles:
+    #    include just requirements-level info, not lock files
+    # hints:
+    #    - not all projects include requirements, but they can be drawn in anyway by dynamic dependencies
+    #        in the setuptools build process, linked via config in pyproject.toml
+    #    - for some repos, the *.txt are actually lockfiles.  This probably needs fixing.
+
+
+#---------
+# SECTION: root files
 exclude .flake8
 exclude .git-blame-ignore-revs
 exclude .git_archival.txt
 exclude .gitattributes
 exclude .gitignore
+exclude .lycheeignore
 exclude .mailmap
 exclude .pre-commit-config.yaml
 exclude .readthedocs.yml
 exclude .ruff.toml
 exclude CHANGES
+include CITATION.cff
 exclude CODE_OF_CONDUCT.md
-exclude codecov.yml
 include COPYING
 include COPYING.LESSER
-include CITATION.cff
 include LICENSE
 exclude Makefile
-exclude noxfile.py
+exclude codecov.yml
+include noxfile.py
+    # principles:
+    #    - *ANY* file in the root should be explicitly "include"- or "exclude"-d
+    #         - EXCEPT (possibly) those covered by setuptools default rules (see above link)
+    #             - including : README.md/.rst; pyproject.toml; setup.py/.cfg
+    #         - N.B. a GHA "ci-manifest" check, if used, will check all this
+    #    - the above are typical ones : given in sorted order
+    #    - NB many will (eventually) be templated, but that is a separate issue
+    #    - probably, this section can be included as *boilerplate*
+    #        - i.e. it doesn't matter if some of the files mentioned don't exist
+
+
+#---------
+# SECTION: generic exclusions
+# (1) top-level directories to omit entirely
+prune .github
+prune .nox
+prune .tox
+prune .coverage
+# (2) top-level files to omit
+exclude .coveragerc
+# (3) file types (path patterns) to skip everywhere
+global-exclude *.py[cod]
+global-exclude __pycache__
+    # principles:
+    #    - common directories, files and file-types to be generally ignored
+    #        - all outside version control, temporary non-coding output and cache data
+    #             produced by dev processes, automation or user tools
+    #    - by having this section LAST, it can remove files which might have been added by
+    #        previous sections -- such as python compiler cache files
+    #    - can include this section as **boilerplate** :
+    #        - won't all exist in every repo, but including them all does no harm
+
+
+#
+#=================================
+# Local Iris-specific settings
+#
+prune benchmarks
+prune etc
+prune tools
 
 # files required to build iris.std_names module
 include etc/cf-standard-name-table.xml
 include tools/generate_std_names.py
 
-global-exclude *.py[cod]
-global-exclude __pycache__

README.md

@@ -12,8 +12,8 @@
 |                  |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 |------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | ⚙️ CI            | [![ci-manifest](https://github.com/SciTools/iris/actions/workflows/ci-manifest.yml/badge.svg)](https://github.com/SciTools/iris/actions/workflows/ci-manifest.yml) [![ci-tests](https://github.com/SciTools/iris/actions/workflows/ci-tests.yml/badge.svg)](https://github.com/SciTools/iris/actions/workflows/ci-tests.yml) [![ci-wheels](https://github.com/SciTools/iris/actions/workflows/ci-wheels.yml/badge.svg)](https://github.com/SciTools/iris/actions/workflows/ci-wheels.yml) [![pre-commit](https://results.pre-commit.ci/badge/github/SciTools/iris/main.svg)](https://results.pre-commit.ci/latest/github/SciTools/iris/main) |
-| 💬 Community     | [![Contributor Covenant](https://img.shields.io/badge/contributor%20covenant-2.1-4baaaa.svg)](https://www.contributor-covenant.org/version/2/1/code_of_conduct/) [![GH Discussions](https://img.shields.io/badge/github-discussions%20%F0%9F%92%AC-yellow?logo=github&logoColor=lightgrey)](https://github.com/SciTools/iris/discussions) [![twitter](https://img.shields.io/twitter/follow/scitools_iris?color=yellow&label=twitter%7Cscitools_iris&logo=twitter&style=plastic)](https://twitter.com/scitools_iris)                                                                                                                         |
-| 📖 Documentation | [![rtd](https://readthedocs.org/projects/scitools-iris/badge/?version=latest)](https://scitools-iris.readthedocs.io/en/latest/?badge=latest)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| 💬 Community     | [![Contributor Covenant](https://img.shields.io/badge/contributor%20covenant-2.1-4baaaa.svg)](https://www.contributor-covenant.org/version/2/1/code_of_conduct/) [![GH Discussions](https://img.shields.io/badge/github-discussions%20%F0%9F%92%AC-yellow?logo=github&logoColor=lightgrey)](https://github.com/SciTools/iris/discussions) [![bluesky](https://img.shields.io/badge/scitools-0285FF?label=bluesky&logo=bluesky&logoColor=0285FF)](https://bsky.app/profile/scitools.bsky.social)                                                                                                                                              |
+| 📖 Documentation | [![rtd](https://readthedocs.org/projects/scitools-iris/badge/?version=latest)](https://scitools-iris.readthedocs.io/en/latest/?badge=latest) [![Check Links](https://github.com/SciTools/iris/actions/workflows/ci-linkchecks.yml/badge.svg)](https://github.com/SciTools/iris/actions/workflows/ci-linkchecks.yml)                                                                                                                                                                                                                                                                                                                          |
 | 📈 Health        | [![codecov](https://codecov.io/gh/SciTools/iris/branch/main/graph/badge.svg?token=0GeICSIF3g)](https://codecov.io/gh/SciTools/iris)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | ✨ Meta           | [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) [![NEP29](https://raster.shields.io/badge/follows-NEP29-orange.png)](https://numpy.org/neps/nep-0029-deprecation_policy.html) [![license - bds-3-clause](https://img.shields.io/github/license/SciTools/iris)](https://github.com/SciTools/iris/blob/main/LICENSE) [![conda platform](https://img.shields.io/conda/pn/conda-forge/iris.svg)](https://anaconda.org/conda-forge/iris)                                                                                             |
 | 📦 Package       | [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.595182.svg)](https://doi.org/10.5281/zenodo.595182) [![conda-forge](https://img.shields.io/conda/vn/conda-forge/iris?color=orange&label=conda-forge&logo=conda-forge&logoColor=white)](https://anaconda.org/conda-forge/iris) [![pypi](https://img.shields.io/pypi/v/scitools-iris?color=orange&label=pypi&logo=python&logoColor=white)](https://pypi.org/project/scitools-iris/) [![pypi - python version](https://img.shields.io/pypi/pyversions/scitools-iris.svg?color=orange&logo=python&label=python&logoColor=white)](https://pypi.org/project/scitools-iris/)                    |