Release version 2025.10.00

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,21 +1,24 @@
-**Description**
+# Description
+
 Include a summary of the change and which issue is fixed. Please also include
 relevant motivation and context. List any dependencies that are required for
 this change.
 
 Fixes # (issue)
 If this is a hotfix to a released version, please specify it.
 
-**How Has This Been Tested?**
+## How has this been tested?
+
 Please describe the tests that you ran to verify your changes. Please also note
 any relevant details for your test configuration (e.g. compiler, OS).  Include
 enough information so someone can reproduce your tests.
 
-**Checklist:**
+## Checklist
+
 - [ ] My code follows the style guidelines of this project
 - [ ] I have performed a self-review of my own code
 - [ ] I have commented my code, particularly in hard-to-understand areas
-- [ ] I have made corresponding changes to the documentation
+- [ ] I have made corresponding changes to the documentation (e.g. add new modules to docs/docstrings/)
 - [ ] My changes generate no new warnings
 - [ ] Any dependent changes have been merged and published in downstream modules
 - [ ] New check tests, if applicable, are included

.github/workflows/create-cache.yaml

@@ -0,0 +1,52 @@
+name: "Create GHA cache"
+
+# GitHub puts the following restrictions on cache sharing. PRs can access
+#
+# - caches that were created by the PR / earlier runs of the PR
+# - caches that were created on the target branch
+#
+# To get effective cache sharing between PRs, we create caches on the `develop`
+# branch (which is where almost all PRs merge into).
+
+on:
+  push:
+    branches: [develop]
+
+# Cancel running jobs if there's a newer push
+concurrency:
+  group: ${{ github.repository }}-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # GitHub Actions cache of the pre-commit environment
+  pre-commit:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+
+      - name: Setup Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - uses: actions/cache@v4
+        id: cache
+        with:
+          path: ~/.cache/pre-commit
+          key: pre-commit_${{ env.pythonLocation }}_${{ hashFiles('.pre-commit-config.yaml') }}
+          lookup-only: true  # don't actually download the cache
+
+      - name: Populate pre-commit environment (if not cached)
+        if: steps.cache.outputs.cache-hit != 'true'
+        run: |
+          pip install pre-commit
+          pre-commit install --install-hooks
+
+  # GitHub Actions cache of pyFV3 test data
+  pyFV3_test_data:
+    uses: NOAA-GFDL/pyFV3/.github/workflows/create_cache.yml@develop
+
+  # GitHub Actions cache of pySHiELD test data
+  pySHiELD_test_data:
+    uses: NOAA-GFDL/pySHiELD/.github/workflows/create_cache.yml@develop

.github/workflows/docs_build.yaml

@@ -0,0 +1,34 @@
+name: "Build docs"
+
+# This workflow builds the docs to catch us when modules are moved/deleted
+# and the auto-generated docstrings can't build anymore. This does not catch
+# us when new modules are added.
+
+# Run these these whenever ...
+on:
+  pull_request: # ... a PR is opened / updated
+  merge_group: # ... the PR is added to the merge queue
+
+# cancel running jobs if theres a newer push
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+
+      - name: Setup Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install mkdocs
+        run: pip install mkdocs-material mkdocstrings[python]
+
+      - name: Build docs
+        run: mkdocs build

.github/workflows/docs_deploy.yaml

@@ -0,0 +1,35 @@
+name: "NDSL documentation"
+
+# Documentation gets automatically deployed upon merge to develop
+on:
+  push:
+    branches:
+      - develop
+
+# Security: Restrict permissions of this workflow to whats needed.
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email github-actions[bot]@users.noreply.github.com
+
+      - name: Setup python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.11
+
+      - name: Install dependencies
+        run: pip install mkdocs-material mkdocstrings[python]
+
+      - name: Deploy docs to GitHub Pages
+        run: mkdocs gh-deploy --force

.github/workflows/fv3_translate_tests.yaml

@@ -1,10 +1,16 @@
 name: "FV3 translate tests"
+
+# Run these these whenever ...
 on:
-  pull_request:
+  pull_request: # ... a PR is opened / updated
+  merge_group: # ... the PR is added to the merge queue
+  push:
+    branches:
+      - main # ... when merging into the main branch
 
 jobs:
   fv3_translate_tests:
     uses: NOAA-GFDL/pyFV3/.github/workflows/translate.yaml@develop
     with:
-      component_trigger:  true
+      component_trigger: true
       component_name: NDSL

.github/workflows/lint.yaml

@@ -1,6 +1,12 @@
 name: "Lint"
+
+# Run these these whenever ...
 on:
-  pull_request:
+  pull_request: # ... a PR is opened / updated
+  merge_group: # ... the PR is added to the merge queue
+  push:
+    branches:
+      - main # ... when merging into the main branch
 
 # cancel running jobs if theres a newer push
 concurrency:
@@ -11,18 +17,23 @@ jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
-        - name: Checkout repository
-          uses: actions/checkout@v4
-          with:
-            submodules: 'recursive'
+      - name: Checkout repository
+        uses: actions/checkout@v5
+
+      - name: Setup Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
 
-        - name: Setup Python 3.11
-          uses: actions/setup-python@v5
-          with:
-            python-version: '3.11'
+      # Only restore (don't save) caches on PRs. New caches created from PRs won't be
+      # accessible from other PRs, see workflows/create-cache.yaml.
+      - uses: actions/cache/restore@v4
+        with:
+          path: ~/.cache/pre-commit
+          key: pre-commit_${{ env.pythonLocation }}_${{ hashFiles('.pre-commit-config.yaml') }}
 
-        - name: Install pre-commit
-          run: pip install pre-commit
+      - name: Install pre-commit
+        run: pip install pre-commit
 
-        - name: Run lint via pre-commit
-          run: pre-commit run --all-files
+      - name: Run lint via pre-commit
+        run: pre-commit run --all-files

.github/workflows/pace_tests.yaml

@@ -1,10 +1,16 @@
 name: "pace main tests"
+
+# Run these these whenever ...
 on:
-  pull_request:
+  pull_request: # ... a PR is opened / updated
+  merge_group: # ... the PR is added to the merge queue
+  push:
+    branches:
+      - main # ... when merging into the main branch
 
 jobs:
   pace_main_tests:
     uses: NOAA-GFDL/pace/.github/workflows/main_unit_tests.yaml@develop
     with:
-      component_trigger:  true
+      component_trigger: true
       component_name: NDSL

.github/workflows/shield_tests.yaml

@@ -1,10 +1,16 @@
 name: "SHiELD Translate tests"
+
+# Run these these whenever ...
 on:
-  pull_request:
+  pull_request: # ... a PR is opened / updated
+  merge_group: # ... the PR is added to the merge queue
+  push:
+    branches:
+      - main # ... when merging into the main branch
 
 jobs:
   shield_translate_tests:
     uses: NOAA-GFDL/pySHiELD/.github/workflows/translate.yaml@develop
     with:
-      component_trigger:  true
+      component_trigger: true
       component_name: NDSL

.github/workflows/unit_tests.yaml

@@ -1,6 +1,12 @@
 name: "NDSL unit tests"
+
+# Run these these whenever ...
 on:
-  pull_request:
+  pull_request: # ... a PR is opened / updated
+  merge_group: # ... the PR is added to the merge queue
+  push:
+    branches:
+      - main # ... when merging into the main branch
 
 # cancel running jobs if theres a newer push
 concurrency:
@@ -10,28 +16,31 @@ concurrency:
 jobs:
   ndsl_unit_tests:
     runs-on: ubuntu-latest
-    container:
-      image: ghcr.io/noaa-gfdl/miniforge:mpich
     steps:
 
-        - name: Checkout repository
-          uses: actions/checkout@v4
-          with:
-            submodules: 'recursive'
+      - name: Checkout repository
+        uses: actions/checkout@v5
+        with:
+          submodules: 'recursive'
+
+      - name: Setup Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
 
-        - name: Install Python packages
-          run: pip3 install .[test]
+      - name: Install mpi (MPICH flavor)
+        run: pip3 install mpich
 
-        - name: prepare input eta files
-          run: python tests/grid/generate_eta_files.py
+      - name: Install Python packages
+        run: pip3 install .[test]
 
-        - name: Run serial-cpu tests
-          run: coverage run --rcfile=setup.cfg -m pytest tests
+      - name: Run serial-cpu tests
+        run: coverage run --rcfile=pyproject.toml -m pytest tests
 
-        - name: Run parallel-cpu tests
-          run: mpiexec -np 6 --oversubscribe coverage run --rcfile=setup.cfg -m mpi4py -m pytest tests/mpi
+      - name: Run parallel-cpu tests
+        run: mpiexec -np 6 coverage run --rcfile=pyproject.toml -m mpi4py -m pytest tests/mpi
 
-        - name: Output code coverage
-          run: |
-            coverage combine
-            coverage report
+      - name: Output code coverage
+        run: |
+          coverage combine
+          coverage report