pr_code_changes.yaml

# Workflow that runs on code changes to a pull request.
#
# It runs on every pull request to main, with no path filter, so its checks,
# "Test / Result" above all, report on every pull request and a branch rule
# can require them: GitHub leaves a required check pending forever when a
# path filter skips its workflow, and a second workflow on the other paths
# cannot stand in, because a pull request that touches both kinds of path
# runs both. The Changes job decides instead. When no code changed, the jobs
# below are skipped, which a required check counts as passing, and the test
# suite reports Result as a pass without running.
#
# It also runs for merge queue groups (merge_group): with a merge queue on
# main, each pull request is tested again merged onto the latest main, with
# any pull requests queued ahead of it, and main moves only to a commit that
# passed. Each pull request was green on its own while #2251 and #2270
# together broke main on 11 October 2026 (7343f948).

name: Code changes
on:
  pull_request:
    branches:
      - main
  merge_group:
  workflow_dispatch:

# A new push to a pull request supersedes the run on its previous head, so
# cancel that run instead of letting it hold runners. Merge groups and manual
# dispatches are grouped by ref (each merge group has its own) and never
# cancelled.
concurrency:
  group: pr-code-changes-${{ github.event.pull_request.number || github.ref }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

jobs:
  Changes:
    runs-on: ${{ vars.CI_RUNNER_ARM != '' && (vars.CI_RUNNER_EVENTS == '' || contains(format(',{0},', vars.CI_RUNNER_EVENTS), format(',{0},', github.event_name))) && vars.CI_RUNNER_ARM || 'ubuntu-24.04-arm' }}
    permissions:
      contents: read
    timeout-minutes: 5
    outputs:
      code: ${{ steps.diff.outputs.code }}
    steps:
      - name: Checkout repo
        uses: actions/checkout@v6
        with:
          # The pull request's merge commit and its first parent, the base.
          fetch-depth: 2
      - name: Did the pull request change code?
        id: diff
        env:
          EVENT: ${{ github.event_name }}
          # The paths that make a change "code": the same list as the push
          # filter in code_changes.yaml (a test keeps them equal).
          CODE_PATHS: |
            policyengine_uk/**
            tests/**
            .github/**
            pyproject.toml
            uv.lock
            hatch_build.py
            Makefile
            conftest.py
            .gitignore
            README.md
        run: |
          set -euo pipefail
          # Only a pull request can skip its tests. A merge queue group
          # always runs them: main moves to the group's commit, and its
          # base_sha can be the group queued ahead of it rather than main,
          # so a diff against it could call a code change "no code".
          if [ "$EVENT" != pull_request ]; then
            echo "code=true" | tee -a "$GITHUB_OUTPUT"
            exit 0
          fi
          # The merge commit's first parent is the base branch.
          base=HEAD^1
          # NUL-separated and unquoted, with a rename listed as its old and
          # new paths, so a file moved out of policyengine_uk/ still counts.
          git -c core.quotePath=false diff --name-only --no-renames -z "$base" HEAD \
            > "$RUNNER_TEMP/changed.txt"
          python3 .github/changed_code.py "$RUNNER_TEMP/changed.txt" | tee -a "$GITHUB_OUTPUT"
  Python-Compat:
    name: Install + smoke-import (py${{ matrix.python-version }})
    needs: Changes
    if: needs.Changes.outputs.code == 'true'
    runs-on: ${{ vars.CI_RUNNER_X64 != '' && (vars.CI_RUNNER_EVENTS == '' || contains(format(',{0},', vars.CI_RUNNER_EVENTS), format(',{0},', github.event_name))) && vars.CI_RUNNER_X64 || 'ubuntu-latest' }}
    permissions:
      contents: read
    timeout-minutes: 15
    strategy:
      fail-fast: false
      matrix:
        python-version: ["3.11", "3.12", "3.13", "3.14"]
    steps:
      - uses: actions/checkout@v6
      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@v6
        with:
          python-version: ${{ matrix.python-version }}
      - name: Install uv
        uses: astral-sh/setup-uv@v8.1.0
      - name: Install package
        run: uv pip install --system .
      - name: Smoke-import
        run: python -c "import policyengine_uk; print('import OK')"
      - name: Check the installed package reports this commit
        # Outside the checkout, so Python imports the installed wheel, which
        # hatch_build.py built from this clean checkout.
        working-directory: ${{ runner.temp }}
        run: |
          python - "$(git -C "$GITHUB_WORKSPACE" rev-parse HEAD)" <<'EOF'
          import sys
          from policyengine_uk import build_metadata

          head = sys.argv[1]
          git_sha = build_metadata.get_runtime_metadata()["git_sha"]
          print(f"{build_metadata.PACKAGE_ROOT}: git_sha={git_sha}")
          assert "site-packages" in build_metadata.PACKAGE_ROOT.parts
          assert git_sha == head, f"expected {head}"
          EOF
  Release-Build:
    name: Release build records the commit
    needs: Changes
    if: needs.Changes.outputs.code == 'true'
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      # The constrained artifact build used by versioning.yaml, without publishing.
      - uses: actions/checkout@v6
      - name: Install uv
        uses: astral-sh/setup-uv@v8.1.0
      - name: Set up Python
        uses: actions/setup-python@v6
        with:
            python-version: '3.13'
      - name: Build package
        run: >-
          uv build --python 3.13 --sdist --wheel --out-dir dist
          --build-constraint .github/build-constraints.txt
      - name: Build a wheel from the sdist
        # make builds the release wheel from the checkout. Check the sdist
        # still builds the same package, as building the wheel from it once did.
        run: >-
          uv build --python 3.13 --wheel --out-dir "$RUNNER_TEMP/from-sdist"
          --build-constraint .github/build-constraints.txt dist/*.tar.gz
      - name: Check the wheel records this commit
        run: >-
          python .github/check_release_build.py dist "$(git rev-parse HEAD)"
          "$RUNNER_TEMP/from-sdist"
  Lint:
    # On every pull request, whatever it changes: ruff formats and checks
    # notebooks under docs/ and scripts/ too, so a documentation-only change
    # can break Lint for every later pull request (#1696 landed a notebook
    # that failed the format check; #1743 fixed it).
    runs-on: ${{ vars.CI_RUNNER_X64 != '' && (vars.CI_RUNNER_EVENTS == '' || contains(format(',{0},', vars.CI_RUNNER_EVENTS), format(',{0},', github.event_name))) && vars.CI_RUNNER_X64 || 'ubuntu-latest' }}
    permissions:
      contents: read
    timeout-minutes: 10
    steps:
        - uses: actions/checkout@v6
        - name: Install uv
          uses: astral-sh/setup-uv@v8.1.0
        - name: Check formatting
          # With the ruff that uv.lock pins, so a new ruff release cannot change
          # what Lint accepts until the lock is updated.
          run: |
            set -euo pipefail
            ruff=$(uv export --frozen --extra dev --no-hashes --no-header | { grep -E '^ruff==' || true; } | cut -d' ' -f1)
            if [ "$(printf '%s' "$ruff" | grep -c '^ruff==')" != 1 ]; then
              echo "::error::uv.lock should pin exactly one ruff; found: ${ruff:-none}"
              exit 1
            fi
            echo "RUFF=$ruff" >> "$GITHUB_ENV"
            uvx --from "$ruff" ruff format --check .
        - name: Lint
          # The ruff rules pyproject.toml selects, then two pyflakes rules it
          # ignores, checked in the package: F811, a definition that a later
          # one of the same name silently replaces (two PRs that each add a
          # Simulation.set_input merge cleanly, and the second wins; uk hub
          # notice 16), and F821, an undefined name. Neither has a finding
          # in the package today.
          run: |
            uvx --from "$RUFF" ruff check .
            uvx --from "$RUFF" ruff check --select F811,F821 policyengine_uk
        - name: No agent working notes at the repository root
          # Agent jobs keep their working notes at the root of their
          # worktree, and #2376's REPORT.md and PROGRESS.md reached main by
          # mistake on 12 October 2026. Their evidence belongs on the pull
          # request. The check is in Lint because Lint runs on every pull
          # request: these files are not code paths, so a pull request that
          # adds only them skips Test. It runs even when ruff failed, so one
          # run reports both. An explicit bash shell adds pipefail, so a git
          # failure fails the step instead of passing it.
          if: ${{ !cancelled() }}
          shell: bash
          run: |
            notes=$(git ls-files -- ':(top,icase)REPORT.md' ':(top,icase)PROGRESS.md' \
              ':(top,icase)HANDOFF.md' ':(top,icase)handoffs.jsonl' | tr '\n' ' ')
            if [ -n "$notes" ]; then
              echo "::error::Agent working notes at the repository root: ${notes}- post their evidence on the pull request and remove them."
              exit 1
            fi
  Docs:
    # The documentation, built against a pull request's code changes. A
    # pull request that changes only docs/ builds it in pr_docs_changes.yaml.
    name: Documentation build
    needs: Changes
    if: needs.Changes.outputs.code == 'true'
    runs-on: ${{ vars.CI_RUNNER_X64 != '' && (vars.CI_RUNNER_EVENTS == '' || contains(format(',{0},', vars.CI_RUNNER_EVENTS), format(',{0},', github.event_name))) && vars.CI_RUNNER_X64 || 'ubuntu-latest' }}
    permissions:
      contents: read
    timeout-minutes: 30
    steps:
      - name: Checkout repo
        uses: actions/checkout@v6
      # The environment the tests use: uv.lock with the dev extra (which
      # includes jupyter-book), so a new release cannot change the build.
      - name: Install the locked environment
        uses: ./.github/actions/test-environment
      - name: Test documentation builds
        run: make documentation
  # The YAML tests, the Python tests on five runners, and the check that
  # every test ran once and passed, in the locked environment. As one job
  # they took 59 minutes on 10 October 2026 (run 38075384588), and runs were
  # cancelled at a 60-minute limit (issues #2099 and #2257). The release
  # workflow runs the same suite on the wheel it publishes. Require
  # "Test / Result".
  Test:
    needs: Changes
    uses: ./.github/workflows/test-suite.yaml
    permissions:
      contents: read
      id-token: write
    with:
      # Skip only on an explicit "false", so a missing output runs the tests.
      skip: ${{ needs.Changes.outputs.code == 'false' }}
      # A merge group decides what main becomes: it must run the
      # microsimulation tests, never accept them as skipped for want of
      # the dataset credentials.
      require-data: ${{ github.event_name == 'merge_group' }}
    secrets:
      HUGGING_FACE_TOKEN: ${{ secrets.HUGGING_FACE_TOKEN }}