From e266898460a5d84ab0aa6c73eac027f86ad788b1 Mon Sep 17 00:00:00 2001 From: Maria Hutt Date: Mon, 14 Sep 2026 15:47:08 -0700 Subject: [PATCH 1/5] chore(ci): split OS-independent checks into their own jobs --- .github/workflows/CI.yml | 70 +++++++++++++++---- .../actions/check-admonitions/action.yml | 6 -- 2 files changed, 58 insertions(+), 18 deletions(-) diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml index 308663ffe0..6292e8bf4b 100644 --- a/.github/workflows/CI.yml +++ b/.github/workflows/CI.yml @@ -6,9 +6,45 @@ name: Validate Docs on: [pull_request] +env: + NODE_VERSION: 24 + jobs: - test: - name: Test on ${{ matrix.os }} + # The result does not vary by operating system, so this runs once. + admonitions: + name: Check Admonitions + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + # The check diffs against the pull request base, so it needs history. + fetch-depth: 0 + - uses: ./.github/workflows/actions/check-admonitions + + # These produce the same verdict on any operating system, so they run once. + checks: + name: Checks + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - name: βš™οΈ Use Node.js + uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0 + with: + node-version: ${{ env.NODE_VERSION }} + cache: npm + - name: πŸ•ΈοΈ Install Dependencies + run: npm ci + - name: Test + run: npm run test + - name: 🧩 Typecheck + run: npm run typecheck + - name: πŸ”€ Spell Check + run: npm run spellcheck + + cross-platform: + name: Cross-platform on ${{ matrix.os }} runs-on: ${{ matrix.os }} strategy: matrix: @@ -22,23 +58,33 @@ jobs: - name: βš™οΈ Use Node.js uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0 with: - node-version: 24 + node-version: ${{ env.NODE_VERSION }} + cache: npm - name: πŸ•ΈοΈ Install Dependencies run: npm ci + # Prettier rewrites line endings, so this is the check most likely to + # differ between operating systems. - name: πŸ–ŒοΈ Lint run: npm run lint - - name: Test - run: npm run test - - name: 🧩 Typecheck - run: npm run typecheck - - name: πŸ”€ Spell Check - run: npm run spellcheck - - uses: ./.github/workflows/actions/check-admonitions - uses: ./.github/workflows/actions/check-translations - # Lint and spell check changes should be pushed - # to the branch before the branch is merge eligible. + # Lint changes should be pushed to the branch before the branch is merge + # eligible. # # The translation keys check should not produce any changes. - name: πŸ” Check Diff run: git diff --exit-code shell: bash + + # One stable name for branch protection, so the matrix can change freely. + verify: + # The required check on main and the feature branches. Renaming this + # blocks merges until the protection rules are updated to match. + name: Verify + if: ${{ always() }} + needs: [admonitions, checks, cross-platform] + runs-on: ubuntu-latest + + steps: + - name: Check job status + if: ${{ contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled') }} + run: exit 1 diff --git a/.github/workflows/actions/check-admonitions/action.yml b/.github/workflows/actions/check-admonitions/action.yml index e3f4bf6948..916a439e56 100644 --- a/.github/workflows/actions/check-admonitions/action.yml +++ b/.github/workflows/actions/check-admonitions/action.yml @@ -14,18 +14,12 @@ runs: # # Only the files the pull request touches are checked, so an existing # page is never anyone else's problem to fix. - # - # The event payload has no file list, so the changed files come from a - # diff. The checkout is shallow and the base commit is fetched here - # rather than through `fetch-depth` on the checkout, which would pull - # the full history for every step in the job just to serve this one. - name: πŸ”Ž Check Admonitions shell: bash env: BASE_SHA: ${{ github.event.pull_request.base.sha }} CHANGED_FILES: ${{ runner.temp }}/changed-files.txt run: | - git fetch --quiet --no-tags --depth=1 origin "$BASE_SHA" git diff --name-only --diff-filter=ACMR "$BASE_SHA" HEAD > "$CHANGED_FILES" node <<'JS' const { readFileSync } = require('fs'); From dfa136e92dbfb72adb5ee5c3c5347118172597e3 Mon Sep 17 00:00:00 2001 From: Maria Hutt Date: Tue, 15 Sep 2026 19:15:08 -0700 Subject: [PATCH 2/5] chore(ci): move the translations check out of the OS matrix --- .github/workflows/CI.yml | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml index 6292e8bf4b..49377feca5 100644 --- a/.github/workflows/CI.yml +++ b/.github/workflows/CI.yml @@ -42,6 +42,7 @@ jobs: run: npm run typecheck - name: πŸ”€ Spell Check run: npm run spellcheck + - uses: ./.github/workflows/actions/check-translations cross-platform: name: Cross-platform on ${{ matrix.os }} @@ -66,11 +67,8 @@ jobs: # differ between operating systems. - name: πŸ–ŒοΈ Lint run: npm run lint - - uses: ./.github/workflows/actions/check-translations # Lint changes should be pushed to the branch before the branch is merge # eligible. - # - # The translation keys check should not produce any changes. - name: πŸ” Check Diff run: git diff --exit-code shell: bash From 44a11fd47464099e29648504d7548e91c5bc37f7 Mon Sep 17 00:00:00 2001 From: Maria Hutt Date: Tue, 15 Sep 2026 19:25:43 -0700 Subject: [PATCH 3/5] chore(ci): give each job one comment for its own reason --- .github/workflows/CI.yml | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml index 49377feca5..4329cbf47c 100644 --- a/.github/workflows/CI.yml +++ b/.github/workflows/CI.yml @@ -10,7 +10,8 @@ env: NODE_VERSION: 24 jobs: - # The result does not vary by operating system, so this runs once. + # Needs no dependencies, so it reports in seconds rather than queueing behind + # npm ci and lint. admonitions: name: Check Admonitions runs-on: ubuntu-latest @@ -49,9 +50,8 @@ jobs: runs-on: ${{ matrix.os }} strategy: matrix: - # Build processes work differently across operating systems, so the - # checks run on each one to make sure anyone can contribute to the - # docs. + # Prettier rewrites line endings, so Lint is the one check whose + # verdict depends on the operating system. os: [windows-latest, macOS-latest] steps: @@ -63,8 +63,6 @@ jobs: cache: npm - name: πŸ•ΈοΈ Install Dependencies run: npm ci - # Prettier rewrites line endings, so this is the check most likely to - # differ between operating systems. - name: πŸ–ŒοΈ Lint run: npm run lint # Lint changes should be pushed to the branch before the branch is merge @@ -73,10 +71,10 @@ jobs: run: git diff --exit-code shell: bash - # One stable name for branch protection, so the matrix can change freely. verify: - # The required check on main and the feature branches. Renaming this - # blocks merges until the protection rules are updated to match. + # The one required check on main and the feature branches, so the jobs + # above can change without touching the protection rules. Renaming this + # blocks merges until those rules are updated to match. name: Verify if: ${{ always() }} needs: [admonitions, checks, cross-platform] From a5df9cd4457e1b79bcf99d28464058137341d368 Mon Sep 17 00:00:00 2001 From: Maria Hutt Date: Tue, 15 Sep 2026 19:28:45 -0700 Subject: [PATCH 4/5] chore(ci): cancel superseded runs with a concurrency group --- .github/workflows/CI.yml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml index 4329cbf47c..c247a0a6a9 100644 --- a/.github/workflows/CI.yml +++ b/.github/workflows/CI.yml @@ -6,6 +6,11 @@ name: Validate Docs on: [pull_request] +# A new push supersedes the run before it. +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + env: NODE_VERSION: 24 From a7cfb0fe80630af35f1883c60735f28a6931ed18 Mon Sep 17 00:00:00 2001 From: Maria Hutt Date: Tue, 15 Sep 2026 19:35:47 -0700 Subject: [PATCH 5/5] chore(ci): document the fetch-depth the admonition check needs --- .github/workflows/actions/check-admonitions/action.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.github/workflows/actions/check-admonitions/action.yml b/.github/workflows/actions/check-admonitions/action.yml index 916a439e56..8cd33474a5 100644 --- a/.github/workflows/actions/check-admonitions/action.yml +++ b/.github/workflows/actions/check-admonitions/action.yml @@ -14,6 +14,9 @@ runs: # # Only the files the pull request touches are checked, so an existing # page is never anyone else's problem to fix. + # + # The caller has to check out with `fetch-depth: 0`, which a composite + # action cannot require for itself. - name: πŸ”Ž Check Admonitions shell: bash env: