Merge branch 'master' into sunt05/gh3-xsmd-input

Resolve conflict in test_df_state_conversion.py by adopting semantic
assertion approach from master (checking specific field presence/absence)
rather than brittle column count assertions.

Author: sunt05

.claude/reference/quick-start.md

@@ -53,11 +53,24 @@ make test
 ## Makefile Commands
 
 - `make setup` - Create virtual environment with uv (if available)
-- `make dev` - Install SUEWS in editable mode
+- `make dev` - Install SUEWS in editable mode (self-healing, works after clean)
 - `make test` - Run test suite
 - `make clean` - Smart clean (keeps .venv if active)
 - `make format` - Format Python and Fortran code
 
+## Common Workflows
+
+```bash
+# Fresh start (most common for troubleshooting)
+make clean && make dev
+
+# Update code and rebuild
+git pull && make dev
+
+# Build and test changes
+make dev && make test
+```
+
 ## Package Name Differences
 
 When migrating from mamba:

.github/ISSUE_TEMPLATE/release-checklist.md

@@ -15,11 +15,12 @@ assignees: ''
 - [ ] **Clean state**: `git checkout master && git pull && git status` (clean)
 - [ ] **Tests pass**: `make test` (all pass)
 - [ ] **Docs build**: `make docs` (no errors)
+- [ ] **Update CHANGELOG.md**: Add entry under today's date with `[feature]`, `[bugfix]`, `[change]` tags + issue links
+- [ ] **Create version history page**: Create `docs/source/version-history/vYYYY.M.D.rst` and add to toctree in `version-history.rst` (remove `new_latest` label from previous version)
 
 ## Create Release
 
-- [ ] **Update CHANGELOG.md**: Add entry under today's date with `[feature]`, `[bugfix]`, `[change]` tags + issue links
-- [ ] **Commit & push**: `git add CHANGELOG.md && git commit -m "docs: update changelog for YYYY.M.D" && git push`
+- [ ] **Commit & push**: `git add CHANGELOG.md docs/source/version-history/ && git commit -m "docs: update changelog and version history for YYYY.M.D" && git push`
 - [ ] **Tag & push**:
 ```bash
 VERSION="YYYY.M.D"
@@ -50,7 +51,7 @@ git push origin $VERSION
 
 ## Announce (Optional)
 
-- [ ] [UMEP Discussions](https://github.com/UMEP-dev/UMEP/discussions)
+- [ ] [SUEWS Discussions](https://github.com/UMEP-dev/SUEWS/discussions)
 
 ---
 

.github/actions/build-suews/action.yml

@@ -22,6 +22,10 @@ inputs:
     description: 'Suffix for wheel artifact name (e.g., "", "-umep")'
     required: false
     default: ''
+  test_tier:
+    description: 'Test tier: smoke, core, cfg, standard, or all'
+    required: false
+    default: 'standard'
 
 runs:
   using: 'composite'
@@ -129,7 +133,14 @@ runs:
           pip install delvewheel
         CIBW_REPAIR_WHEEL_COMMAND_WINDOWS: "delvewheel repair -w {dest_dir} {wheel}"
         CIBW_TEST_REQUIRES: ${{ inputs.is_umep_variant == 'true' && 'pytest oldest-supported-numpy' || 'pytest' }}
-        CIBW_TEST_COMMAND: "python -m pytest {project}/test -v --tb=short --durations=10"
+        # Test tiers: choose subset based on path detection and trigger
+        CIBW_TEST_COMMAND: >
+          python -m pytest {project}/test -v --tb=short
+          ${{ inputs.test_tier == 'smoke' && '-m smoke' ||
+              inputs.test_tier == 'core' && '-m "smoke or core"' ||
+              inputs.test_tier == 'cfg' && '-m "smoke or cfg"' ||
+              inputs.test_tier == 'standard' && '-m "not slow"' ||
+              '--durations=10' }}
         MACOSX_DEPLOYMENT_TARGET: ${{ inputs.buildplat == 'macos-13' && '13.0' || '15.0' }}
 
     - name: Upload wheels

.github/pages/index.html

@@ -235,7 +235,7 @@
                 </div>
             </a>
 
-            <a href="https://github.com/UMEP-dev/umep/discussions" class="nav-card">
+            <a href="https://github.com/UMEP-dev/SUEWS/discussions" class="nav-card">
                 <span class="nav-icon">💬</span>
                 <div class="nav-title">Community</div>
                 <div class="nav-description">

.github/workflows/build-publish_to_pypi.yml

@@ -86,9 +86,9 @@ name: Build and Publish Python wheels to PyPI and TestPyPI
 # - Both wheel sets deployed to PyPI together (production tags only)
 # - UMEP builds use Python 3.12 only (aligned with QGIS 3.40 LTR bundled Python)
 # - UMEP build triggers (runs on ALL events for continuous NumPy 1.x testing):
-#   * PRs: manylinux cp312 (NumPy 1.x validation before merge)
-#   * Master/manual: manylinux cp312 (continuous UMEP compatibility testing)
-#   * Nightly/dev tags: manylinux cp312 (daily testing, uses .dev1 to avoid version collision)
+#   * PRs: win cp312 (NumPy 1.x validation before merge, Windows = QGIS primary platform)
+#   * Master/manual: win cp312 (continuous UMEP compatibility testing)
+#   * Nightly/dev tags: win cp312 (daily testing, uses .dev1 to avoid version collision)
 #   * Production tags: all platforms cp312 (complete distribution → PyPI, uses rc1 suffix)
 #
 # UMEP INTEGRATION:
@@ -178,39 +178,72 @@ jobs:
     # Only run for pull requests (push/tag/schedule always build)
     if: github.event_name == 'pull_request'
     outputs:
-      needs-build: ${{ steps.filter.outputs.code }}
+      needs-build: ${{ steps.filter.outputs.core == 'true' || steps.filter.outputs.util == 'true' || steps.filter.outputs.cfg == 'true' || steps.filter.outputs.tests == 'true' }}
+      core-changed: ${{ steps.filter.outputs.core }}
+      util-changed: ${{ steps.filter.outputs.util }}
+      cfg-changed: ${{ steps.filter.outputs.cfg }}
+      tests-changed: ${{ steps.filter.outputs.tests }}
     steps:
       - uses: actions/checkout@v4
 
       - uses: dorny/paths-filter@v3
         id: filter
         with:
           filters: |
-            code:
+            core:
+              # Fortran physics
+              - 'src/suews/src/**'
+              # Fortran driver interface
+              - 'src/supy_driver/**'
+              - 'src/supy/supy_driver/**'
+              # Core Python files that affect scientific rigour
+              - 'src/supy/_run.py'
+              - 'src/supy/_supy_module.py'
+              - 'src/supy/_load.py'
+              - 'src/supy/_post.py'
+              - 'src/supy/_check.py'
+              - 'src/supy/_save.py'
+              - 'src/supy/suews_sim.py'
+              # Catch-all for core package changes
               - 'src/suews/**'
+            util:
+              # Utility modules (nice-to-have)
+              - 'src/supy/util/**'
+              # Default category for remaining supy changes
               - 'src/supy/**'
-              - 'src/supy_driver/**'
-              - '.github/workflows/build-publish_to_pypi.yml'
-              - '.github/actions/build-suews/**'
-              - 'test/**'
-              - 'scripts/**'
-              # NOTE: schemas/** excluded - JSON metadata files don't require builds
-              # Bot-created schema PRs use schema-pr-validation.yml instead
+            cfg:
+              # Config validation
+              - 'src/supy/data_model/**'
+              # CLI commands
+              - 'src/supy/cmd/**'
+              # JSON configs
+              - 'src/supy/*.json'
+              # Schemas
+              - 'schemas/**'
+              # Build system / infra
+              - '.github/**'
               - 'pyproject.toml'
               - 'meson.build'
               - 'meson_options.txt'
               - 'Makefile'
               - 'get_ver_git.py'
+              - 'scripts/**'
+            tests:
+              - 'test/**'
 
   # Determine if we should run limited or full matrix
   determine_matrix:
     name: Determine build matrix
     runs-on: ubuntu-latest
+    needs: [detect-changes]
+    # Always run - detect-changes is skipped for non-PR events, but we still need matrix
+    if: always() && (needs.detect-changes.result == 'success' || needs.detect-changes.result == 'skipped')
     outputs:
       buildplat: ${{ steps.set-matrix.outputs.buildplat }}
       python: ${{ steps.set-matrix.outputs.python }}
       umep_buildplat: ${{ steps.set-matrix.outputs.umep_buildplat }}
       umep_python: ${{ steps.set-matrix.outputs.umep_python }}
+      test_tier: ${{ steps.set-matrix.outputs.test_tier }}
     steps:
       - name: Set matrix based on trigger type
         id: set-matrix
@@ -220,30 +253,67 @@ jobs:
           PR_PLATFORMS='[["ubuntu-latest", "manylinux", "x86_64"], ["macos-latest", "macosx", "arm64"], ["windows-2025", "win", "AMD64"]]'
           MINIMAL_PLATFORMS='[["ubuntu-latest", "manylinux", "x86_64"]]'
 
+          CORE_CHANGED="${{ needs.detect-changes.outputs.core-changed || 'false' }}"
+          UTIL_CHANGED="${{ needs.detect-changes.outputs.util-changed || 'false' }}"
+          CFG_CHANGED="${{ needs.detect-changes.outputs.cfg-changed || 'false' }}"
+          TESTS_CHANGED="${{ needs.detect-changes.outputs.tests-changed || 'false' }}"
+
           # Python version strategies:
           # - Draft PR: minimal (1 platform, bookend versions) for fastest feedback
           # - PR/Master: reduced (ARM Mac + Linux + Windows, bookend versions) for speed with good coverage
           # - Tags/Schedule/Manual: full (all platforms including x86_64 Mac, all Python versions) for comprehensive testing
 
           if [[ "${{ github.event_name }}" == "pull_request" ]] && [[ "${{ github.event.pull_request.draft }}" == "true" ]]; then
-            echo "Running minimal matrix for draft PR (1 platform, bookend Python versions)"
-            echo "buildplat=$MINIMAL_PLATFORMS" >> $GITHUB_OUTPUT
-            echo 'python=["cp39", "cp314"]' >> $GITHUB_OUTPUT
-          elif [[ "${{ github.event_name }}" == "pull_request" ]] || [[ "${{ github.event_name }}" == "push" && "${{ github.ref }}" == "refs/heads/master" ]]; then
-            echo "Running reduced matrix for PR/master (ARM Mac + Linux + Windows, bookend Python versions)"
-            echo "buildplat=$PR_PLATFORMS" >> $GITHUB_OUTPUT
-            echo 'python=["cp39", "cp314"]' >> $GITHUB_OUTPUT
+            if [[ "$CORE_CHANGED" == "true" ]]; then
+              echo "Draft PR with core changes - reduced platforms, core tests"
+              echo "buildplat=$PR_PLATFORMS" >> $GITHUB_OUTPUT
+              echo 'python=["cp39", "cp314"]' >> $GITHUB_OUTPUT
+              echo "test_tier=core" >> $GITHUB_OUTPUT
+            elif [[ "$CFG_CHANGED" == "true" ]]; then
+              echo "Draft PR with cfg changes - reduced platforms, cfg tests"
+              echo "buildplat=$PR_PLATFORMS" >> $GITHUB_OUTPUT
+              echo 'python=["cp39", "cp314"]' >> $GITHUB_OUTPUT
+              echo "test_tier=cfg" >> $GITHUB_OUTPUT
+            else
+              echo "Draft PR with util/tests changes - minimal platform, smoke tests"
+              echo "buildplat=$MINIMAL_PLATFORMS" >> $GITHUB_OUTPUT
+              echo 'python=["cp39", "cp314"]' >> $GITHUB_OUTPUT
+              echo "test_tier=smoke" >> $GITHUB_OUTPUT
+            fi
+          elif [[ "${{ github.event_name }}" == "pull_request" ]]; then
+            if [[ "$CORE_CHANGED" == "true" ]]; then
+              echo "Ready PR with core changes - reduced platforms, standard tests"
+              echo "buildplat=$PR_PLATFORMS" >> $GITHUB_OUTPUT
+              echo 'python=["cp39", "cp314"]' >> $GITHUB_OUTPUT
+              echo "test_tier=standard" >> $GITHUB_OUTPUT
+            elif [[ "$CFG_CHANGED" == "true" ]]; then
+              echo "Ready PR with cfg changes - reduced platforms, standard tests"
+              echo "buildplat=$PR_PLATFORMS" >> $GITHUB_OUTPUT
+              echo 'python=["cp39", "cp314"]' >> $GITHUB_OUTPUT
+              echo "test_tier=standard" >> $GITHUB_OUTPUT
+            else
+              echo "Ready PR with util/tests changes - reduced platforms, smoke tests"
+              echo "buildplat=$PR_PLATFORMS" >> $GITHUB_OUTPUT
+              echo 'python=["cp39", "cp314"]' >> $GITHUB_OUTPUT
+              echo "test_tier=smoke" >> $GITHUB_OUTPUT
+            fi
+          elif [[ "${{ github.event_name }}" == "schedule" ]]; then
+            echo "Running full matrix for nightly (all platforms, all Python versions, all tests)"
+            echo "buildplat=$FULL_PLATFORMS" >> $GITHUB_OUTPUT
+            echo 'python=["cp39", "cp310", "cp311", "cp312", "cp313", "cp314"]' >> $GITHUB_OUTPUT
+            echo "test_tier=all" >> $GITHUB_OUTPUT
           else
-            echo "Running full matrix for tags/schedule/manual (all platforms including x86_64 Mac, all Python versions)"
+            echo "Running full matrix for tags/manual (all platforms, all Python versions, all tests)"
             echo "buildplat=$FULL_PLATFORMS" >> $GITHUB_OUTPUT
             echo 'python=["cp39", "cp310", "cp311", "cp312", "cp313", "cp314"]' >> $GITHUB_OUTPUT
+            echo "test_tier=all" >> $GITHUB_OUTPUT
           fi
 
           # UMEP builds: Python 3.12 only (aligned with QGIS 3.40 LTR bundled Python)
-          # PR: manylinux only for quick validation
+          # PR/nightly: Windows only (QGIS primary platform) for quick validation
           # Production: all platforms for complete UMEP distribution
           echo "UMEP matrix: cp312 only (QGIS 3.40 LTR uses Python 3.12)"
-          echo 'umep_buildplat=[["ubuntu-latest", "manylinux", "x86_64"]]' >> $GITHUB_OUTPUT
+          echo 'umep_buildplat=[["windows-2025", "win", "AMD64"]]' >> $GITHUB_OUTPUT
           echo 'umep_python=["cp312"]' >> $GITHUB_OUTPUT
 
   build_wheels:
@@ -280,6 +350,7 @@ jobs:
           python: ${{ matrix.python }}
           is_umep_variant: 'false'
           wheel_name_suffix: ''
+          test_tier: ${{ needs.determine_matrix.outputs.test_tier }}
 
   build_umep:
     name: Build UMEP wheel (rc1/dev1) for ${{ matrix.python }}-${{ matrix.buildplat[1] }} ${{ matrix.buildplat[2] }}
@@ -321,6 +392,7 @@ jobs:
           python: ${{ matrix.python }}
           is_umep_variant: 'true'
           wheel_name_suffix: '-umep'
+          test_tier: ${{ needs.determine_matrix.outputs.test_tier }}
 
   # PR gate: single consolidated check for branch protection
   # This job ALWAYS runs for PRs and reports pass/fail based on build results
@@ -467,7 +539,7 @@ jobs:
     needs:
       - deploy_pypi
     # Run whenever PyPI deployment succeeds (already ensures it's a production tag)
-    if: needs.deploy_pypi.result == 'success'
+    if: always() && needs.deploy_pypi.result == 'success'
 
     permissions:
       contents: write  # Required to create releases