Skip to content

Commit 4b6a21e

Browse files
luisleo526claude
andcommitted
CI: skip heavy jobs on docs-only changes (lane pf-ci-docs)
A new first job, changes, runs scripts/ci_docs_only.py on the standard runner and answers docs_only. A changed path is documentation when it is a Markdown file or lies under docs/, unless it lies under .github/, benchmarks/, scripts/ or tests/, is a CMake file, or is one of the four files a proof job reads (docs/pages/pine-to-native.md and docs/pages/native-engine.md, whose code blocks CTest rows compile and run; ADR-0001, which test_kernel_residuals, test_native_feature_rulings and the kernel profile's kernel-residuals stage read; docs/build.sh, whose retry self-test is a CTest row). A pull request is its tested merge against the base it merged into, a push is before..after; every doubt (a dispatch, a created or forced push, a merge of another head, an unreadable commit, an empty change, a failed classification) answers no. Each proof job (the four build legs, sanitizers, kernel-only, native-live, corpus-parity-subset) now needs changes alone and skips only a docs-only answer; preflight, which holds the documentation guards, and docs.yml run as before. The build aggregate passes a proof lane that succeeded or was skipped after changes succeeded and answered docs-only, and fails any other skip or result; preflight must always succeed. Pushes to main follow the same rule: release.yml is dispatch-only and builds its own tarballs, promote-baseline.yml reads the maintainers' pineforge/verify and pineforge/parity statuses on the PR head, no workflow starts on workflow_run, and the ruleset requires only those two statuses. The ci-workflow-contract stage pins the new wiring; test_ci_preflight.py runs the aggregate's shell over every lane outcome; the new docs-only-tests stage holds the rule against real git histories and fails when a CMake file reads a path the rule would call documentation. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
1 parent 8a9e582 commit 4b6a21e

7 files changed

Lines changed: 806 additions & 48 deletions

File tree

‎.github/workflows/ci.yml‎

Lines changed: 58 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,34 @@ env:
3131
# scripts/ci_preflight.py pins every runner, time limit and job count, and
3232
# docs/ci.md gives each limit's measured basis.
3333
jobs:
34+
# Whether the change is documentation only; scripts/ci_docs_only.py holds the
35+
# rule, and every doubt answers no. On a docs-only pull request or push the
36+
# proof jobs below skip and the build aggregate accepts exactly that skip.
37+
# Preflight, where the documentation guards run, does not wait for it, and
38+
# docs.yml builds the site as before. A few seconds of git: the standard
39+
# runner, for every event.
40+
changes:
41+
runs-on: ubuntu-24.04
42+
timeout-minutes: 5
43+
outputs:
44+
docs_only: ${{ steps.classify.outputs.docs_only }}
45+
steps:
46+
# The tested commit and its parents: a pull request's merge and the base
47+
# it merged into, a push's commit and its parent (the script fetches an
48+
# older before).
49+
- uses: actions/checkout@v4
50+
with:
51+
fetch-depth: 2
52+
persist-credentials: false
53+
54+
- name: Classify the change
55+
id: classify
56+
env:
57+
PR_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
58+
PUSH_BEFORE: ${{ github.event.before }}
59+
PUSH_FORCED: ${{ github.event.forced }}
60+
run: python3 scripts/ci_docs_only.py --github-output "$GITHUB_OUTPUT"
61+
3462
preflight:
3563
runs-on: ${{ (github.event_name == 'push' || github.event_name == 'schedule' || github.event_name == 'workflow_dispatch' || (github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository)) && 'pf-linux-x64-16' || 'ubuntu-24.04' }}
3664
# Its verifier-tests stage is one serial process: 475 s at 0d76a099's tree
@@ -81,6 +109,10 @@ jobs:
81109
build:
82110
# Each leg keeps its name, build (<image>, <type>), whatever the matrix carries.
83111
name: build (${{ matrix.os }}, ${{ matrix.build_type }})
112+
# Every proof job waits for the changes job alone and skips only a
113+
# docs-only change; a failed or unanswered classification runs it.
114+
needs: changes
115+
if: ${{ !cancelled() && needs.changes.outputs.docs_only != 'true' }}
84116
# A full-set leg waits on the test_ci_verify CTest row, 976-1288 s on the
85117
# standard runners at 0d76a099, which more cores do not shorten. There the
86118
# Release legs, which a fork's pull request runs in full, took 30.3 and
@@ -167,6 +199,8 @@ jobs:
167199
# instrumentation propagates into every test binary (CMakeLists.txt option
168200
# PINEFORGE_ENABLE_SANITIZERS).
169201
sanitizers:
202+
needs: changes
203+
if: ${{ !cancelled() && needs.changes.outputs.docs_only != 'true' }}
170204
runs-on: ${{ (github.event_name == 'push' || github.event_name == 'schedule' || github.event_name == 'workflow_dispatch' || (github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository)) && 'pf-linux-x64-16' || 'ubuntu-24.04' }}
171205
# A full run (push to main, manual dispatch) gives its CTest stage an hour
172206
# after the build; the PR set keeps its 30-minute stage, after about 30
@@ -221,6 +255,8 @@ jobs:
221255
# modules are built from the kernel alone, and every examples/native host
222256
# runs as an example_* row asserting both its exit code and its summary line.
223257
kernel-only:
258+
needs: changes
259+
if: ${{ !cancelled() && needs.changes.outputs.docs_only != 'true' }}
224260
runs-on: ${{ (github.event_name == 'push' || github.event_name == 'schedule' || github.event_name == 'workflow_dispatch' || (github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository)) && 'pf-linux-x64-16' || 'ubuntu-24.04' }}
225261
# 22.3 min on the standard runner at 0d76a099, where a fork's pull request
226262
# still runs the whole kernel set.
@@ -265,14 +301,19 @@ jobs:
265301

266302
# Reuse native proof once per CI run. Its manual dispatch runs every row.
267303
native-live:
304+
needs: changes
305+
if: ${{ !cancelled() && needs.changes.outputs.docs_only != 'true' }}
268306
uses: ./.github/workflows/native-live.yml
269307
with:
270308
exclude_slow: ${{ github.event_name == 'pull_request' }}
271309

272-
# Advisory TradingView parity subset on every CI run. The maintainers post
273-
# the required pineforge/parity status from their separate parity verdict.
274-
# Keep this job unfiltered so build-gate reports its result on every run.
310+
# Advisory TradingView parity subset on every CI run of a change that is not
311+
# docs-only. The maintainers post the required pineforge/parity status from
312+
# their separate parity verdict. Keep this job unfiltered by path so
313+
# build-gate reports its result on every such run.
275314
corpus-parity-subset:
315+
needs: changes
316+
if: ${{ !cancelled() && needs.changes.outputs.docs_only != 'true' }}
276317
uses: ./.github/workflows/corpus-parity.yml
277318
with:
278319
mode: subset
@@ -282,7 +323,7 @@ jobs:
282323
# maintainers, rather than this build context.
283324
build-gate:
284325
name: build
285-
needs: [preflight, build, sanitizers, native-live, kernel-only, corpus-parity-subset]
326+
needs: [changes, preflight, build, sanitizers, native-live, kernel-only, corpus-parity-subset]
286327
if: always()
287328
# A few seconds of shell: the standard runner, for every event.
288329
runs-on: ubuntu-24.04
@@ -291,16 +332,25 @@ jobs:
291332
- name: Require every verification lane to have passed
292333
shell: bash
293334
env:
335+
CHANGES_RESULT: ${{ needs.changes.result }}
336+
DOCS_ONLY: ${{ needs.changes.outputs.docs_only }}
294337
PREFLIGHT_RESULT: ${{ needs.preflight.result }}
295338
BUILD_RESULT: ${{ needs.build.result }}
296339
SANITIZER_RESULT: ${{ needs.sanitizers.result }}
297340
NATIVE_RESULT: ${{ needs.native-live.result }}
298341
KERNEL_RESULT: ${{ needs.kernel-only.result }}
299342
PARITY_RESULT: ${{ needs.corpus-parity-subset.result }}
300343
run: |
301-
printf '%s\n' "preflight: $PREFLIGHT_RESULT" "matrix: $BUILD_RESULT" \
344+
printf '%s\n' "changes: $CHANGES_RESULT, docs only: ${DOCS_ONLY:-unanswered}" \
345+
"preflight: $PREFLIGHT_RESULT" "matrix: $BUILD_RESULT" \
302346
"sanitizers: $SANITIZER_RESULT" "native: $NATIVE_RESULT" \
303347
"kernel: $KERNEL_RESULT" "corpus parity (subset): $PARITY_RESULT"
304-
[[ "$PREFLIGHT_RESULT" == "success" && "$BUILD_RESULT" == "success" \
305-
&& "$SANITIZER_RESULT" == "success" && "$NATIVE_RESULT" == "success" \
306-
&& "$KERNEL_RESULT" == "success" && "$PARITY_RESULT" == "success" ]]
348+
# A proof lane passes by succeeding, or by having been skipped after
349+
# the changes job succeeded and answered docs-only. A lane skipped
350+
# for any other reason fails, and preflight must always succeed.
351+
docs_only=false
352+
if [[ "$CHANGES_RESULT" == "success" && "$DOCS_ONLY" == "true" ]]; then docs_only=true; fi
353+
passed() { [[ "$1" == "success" || ( "$docs_only" == "true" && "$1" == "skipped" ) ]]; }
354+
[[ "$PREFLIGHT_RESULT" == "success" ]] && passed "$BUILD_RESULT" \
355+
&& passed "$SANITIZER_RESULT" && passed "$NATIVE_RESULT" \
356+
&& passed "$KERNEL_RESULT" && passed "$PARITY_RESULT"

‎CONTRIBUTING.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -295,7 +295,8 @@ The merge gate is two commit statuses on the PR head, `pineforge/verify` and
295295
`ci_verify.py` profiles and their parity verification on it. The GitHub Actions
296296
jobs (build on Ubuntu + macOS in Release and Debug, sanitizers, ctest, the source
297297
guards, the install/`find_package` smoke test and the parity subset) are
298-
advisory.
298+
advisory. A change that touches documentation only runs the preflight guards
299+
and the documentation build and skips the rest; `docs/ci.md` names the rule.
299300

300301
### How a parity campaign gates a merge
301302

‎docs/ci.md‎

Lines changed: 82 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,8 @@ This checks the CI/native workflow syntax, expressions and shell commands,
1111
source ABI/hash/schema guards, and the verifier's failure-handling tests. A
1212
failure fails the advisory aggregate `build` job and retains logs in
1313
`build-ci-preflight/`. The compilation lanes start alongside preflight.
14+
A documentation-only change skips them and runs preflight alone
15+
([Documentation-only changes](#documentation-only-changes)).
1416
It does not compile the engine or replace any complete verification profile.
1517

1618
Then use the same verification entrypoint as GitHub Actions before publishing:
@@ -41,9 +43,9 @@ runs each image, and each job's time limit, is in
4143

4244
The two source-only benchmark CTest rows run the 25 harness unit tests and
4345
`benchmarks/check_provenance.py`. The latter reads historical commits (including
44-
`933fe583`), so every checkout in `.github/workflows/ci.yml` fetches full Git
45-
history. A depth-1 checkout fails the provenance row even when the current
46-
benchmark files are correct.
46+
`933fe583`), so every checkout in `.github/workflows/ci.yml` but the `changes`
47+
job's fetches full Git history. A depth-1 checkout fails the provenance row
48+
even when the current benchmark files are correct.
4749

4850
## Profiles
4951

@@ -406,9 +408,10 @@ judge <1 s — **94 s** end to end over an up-to-date build directory, against
406408
1792 s for the run phase alone in full mode.
407409

408410
`corpus-parity.yml` exposes it as a reusable workflow (`mode: subset`) and
409-
`ci.yml` calls it on every CI run and lists it in `build-gate`'s `needs`. A
410-
skipped dependency fails that advisory aggregate job, so the subset remains
411-
unfiltered by path. The merge ruleset requires `pineforge/verify` and
411+
`ci.yml` calls it on every CI run that changes more than documentation and
412+
lists it in `build-gate`'s `needs`. A dependency skipped for anything but a
413+
documentation-only change fails that advisory aggregate job, so the subset
414+
remains unfiltered by path. The merge ruleset requires `pineforge/verify` and
412415
`pineforge/parity`, posted by the maintainers' `lab verify` tooling after
413416
full verification on the PR head's exact tree.
414417

@@ -603,14 +606,17 @@ Compiler objects, binaries and dependency caches are not uploaded
603606
as diagnostics.
604607

605608
Superseded pull-request runs are canceled. Main/post-merge and manual CI runs
606-
use distinct concurrency groups and remain uncanceled. A PR runs preflight,
607-
both Release jobs, kernel-only and the parity subset with their full sets;
609+
use distinct concurrency groups and remain uncanceled. A PR that changes more
610+
than documentation runs preflight, both Release jobs, kernel-only and the
611+
parity subset with their full sets;
608612
both Debug jobs, sanitizers and native-live run the registered set excluding
609613
the 29 CTest rows labelled `slow` in `tests/CMakeLists.txt`. The first 27 were
610614
chosen from INT23/INT24 job logs: over 60 seconds in either sanitizer run or
611615
over 30 seconds in either Debug run. Preflight and all proof jobs start in
612-
parallel. The advisory `build` aggregate succeeds only if every job succeeds.
613-
INT25 re-measured the rows wave G enlarged or added (RATIO-HARDEN's timing
616+
parallel. The proof jobs wait only for the few-second `changes` job, which
617+
decides whether the change is documentation only. The advisory `build`
618+
aggregate succeeds only if every job succeeds, or was skipped for a
619+
documentation-only change. INT25 re-measured the rows wave G enlarged or added (RATIO-HARDEN's timing
614620
legs, V19-FIX's scaling rows, and the new KERNEL-EDGE, K-ULP4, C-SURFACE-1 and
615621
DOC-TRUTH-4 rows) in a full sanitizers and Debug run on the maintainers' x86-64
616622
verification host (twelve parallel CTest jobs): none crosses either threshold,
@@ -627,8 +633,9 @@ sanitizers (20.3 s Debug) and is the 29th; no other new row comes near a
627633
threshold (the largest, `test_magnified_aggregated_tape`, 3.4 s under
628634
sanitizers).
629635

630-
A push to `main` and a manual dispatch of `ci.yml` run every profile without
631-
the exclusion. Their sanitizers CTest stage gets an hour (`ci_verify.py`
636+
A push to `main` that changes more than documentation and a manual dispatch of
637+
`ci.yml` run every profile without the exclusion. Their sanitizers CTest stage
638+
gets an hour (`ci_verify.py`
632639
bounds CTest at 30 minutes otherwise, the PR set included), because main's full
633640
set ran out of 30 minutes twice, and the sanitizers job allows 120 minutes for
634641
that hour after its build. Standalone manual dispatch of `native-live.yml` is also full.
@@ -651,6 +658,59 @@ The full corpus sweep remains a separate acceptance step. The nightly and
651658
manual corpus workflow, and the maintainers' full parity verification, keep
652659
the broader population running.
653660

661+
### Documentation-only changes
662+
663+
A pull request or a push to `main` whose change is documentation only runs
664+
`preflight` and the documentation build and skips every proof job: the four
665+
`build` legs, both macOS legs among them, `sanitizers`, `kernel-only`,
666+
`native-live` and `corpus-parity-subset`. Every other check that reads the
667+
pages is a `preflight` stage: `doc-anchors`, `doc-lint`, `doc-reverts`,
668+
`doc-pine-coverage`, `design-inventory`, `kernel-seam-rows`, the native C
669+
surface table (`source-guard-native-c-surface`) and their self-tests, beside
670+
the workflow wiring guards. `docs.yml` builds the Doxygen site on every pull
671+
request and push, as before.
672+
673+
The first job of `ci.yml`, `changes`, decides with
674+
[`scripts/ci_docs_only.py`](../scripts/ci_docs_only.py). A changed path is
675+
documentation when it is a Markdown file (`*.md`) or lies under `docs/`,
676+
unless it lies under `.github/`, `benchmarks/`, `scripts/` or `tests/`, is a
677+
CMake file, or is one of the four files a proof job reads:
678+
`docs/pages/pine-to-native.md` and `docs/pages/native-engine.md`, whose code
679+
blocks `test_pine_to_native_worked` and `test_native_engine_complete_host`
680+
compile and run; `docs/adr/0001-kernel-adapter-boundary.md`, which
681+
`test_kernel_residuals`, `test_native_feature_rulings` and the kernel
682+
profile's `kernel-residuals` stage hold the kernel against; and
683+
`docs/build.sh`, whose retry self-test is `test_docs_doxygen_retry`. A change
684+
to one of those four runs every job. A change is documentation only when every
685+
path it changes, both sides of a rename, is documentation. For a pull request
686+
the change is the merge GitHub tests against the base it merged into; for a
687+
push, the pushed commit against the previous tip. Every doubt answers no and
688+
runs the proof jobs in full: a manual dispatch, a push that creates the branch
689+
or is forced, a merge that is not the pull request head's, a commit git cannot
690+
read, an empty change, and a `changes` job that fails or never answers.
691+
692+
Each proof job waits for `changes` alone, seconds on the standard runner;
693+
`preflight` waits for nothing. The advisory `build` aggregate passes a proof
694+
job that succeeded, or one that was skipped while `changes` succeeded and
695+
answered documentation-only. A proof job skipped for any other reason fails
696+
it, and so does any `preflight` result but success.
697+
698+
A push to `main` follows the same rule, since nothing downstream needs the
699+
proof jobs to have run on a merged commit: `release.yml` starts only on a
700+
manual dispatch and builds and verifies its own tarballs,
701+
`promote-baseline.yml` reads the `pineforge/verify` and `pineforge/parity`
702+
statuses on the pull request head, no workflow here starts on `workflow_run`,
703+
and the ruleset requires only those two statuses. A documentation merge
704+
therefore does not rebuild; the `ci.yml` run on its commit is `preflight` and
705+
the skip.
706+
707+
`scripts/test_ci_docs_only.py` (`docs-only-tests`, a `ci_preflight` stage)
708+
holds the rule against real git histories, pull request merges and pushes
709+
alike, and fails when a CMake file reads a path the rule would call
710+
documentation. The `ci-workflow-contract` stage pins the wiring, and
711+
`scripts/test_ci_preflight.py` runs the aggregate's own shell over every
712+
outcome of every lane.
713+
654714
### CI-LITE timing estimate
655715

656716
The INT24 PR run `36105656107` measured 9.1 min preflight, 30.2/27.8 min
@@ -703,7 +763,8 @@ explicitly, so they stay `build (<image>, <type>)`. `native-live.yml` and
703763
`corpus-parity.yml` apply the test themselves; in a `workflow_call` the
704764
`github` context is the caller's, so a fork's pull request through CI gets the
705765
standard runner there too. The advisory `build` aggregate runs a few seconds of
706-
shell and stays on the standard runner for every event.
766+
shell and stays on the standard runner for every event. So does the `changes`
767+
job, a two-commit checkout and one `git diff`.
707768

708769
Each `ci_verify.py` call passes `--jobs "$(getconf _NPROCESSORS_ONLN)"` and
709770
`check_corpus_parity.sh` gets the same count as `JOBS`, so build and CTest
@@ -712,7 +773,8 @@ and 3 on the standard runners. The larger Linux runner is configured for at
712773
most eight jobs at once, and one CI run starts seven there (preflight, the two
713774
Ubuntu `build` legs, sanitizers, kernel-only, native-live and the parity
714775
subset); a pull request that touches the corpus pin or the parity tooling also
715-
starts the whole sweep there, an eighth. A second run that overlaps them waits
776+
starts the whole sweep there, an eighth. A documentation-only change starts
777+
preflight alone there. A second run that overlaps them waits
716778
for a runner. Larger runners bill the organization's Actions budget: with no
717779
payment method or a spending limit of zero, their jobs wait for a runner that
718780
never comes, since GitHub does not fall back to a standard one. The test keeps
@@ -734,7 +796,11 @@ exactly one core-count `--jobs` (counted over the whole job, however its
734796
commands are chained, blocked or carried, with the flag and its value on one
735797
line), or any other `--jobs` or `JOBS` value fails preflight, and so does a jobs
736798
line or `runs-on` the check cannot read; `scripts/test_ci_preflight.py` holds
737-
the mutations.
799+
the mutations. The same stage pins the documentation-only skip: `changes` and
800+
`preflight` wait for nothing and run on every event, each proof job needs
801+
`changes` alone and carries the one skip condition
802+
(`!cancelled() && needs.changes.outputs.docs_only != 'true'`), and the
803+
`build` aggregate reads every result and the answer.
738804

739805
More cores do not shorten every job. The `test_ci_verify` CTest row
740806
(`scripts/test_ci_verify.py`) is one Python process, and in the main run at
@@ -776,3 +842,4 @@ bounds the M2 from above.
776842
| `corpus-parity` | 120 | 16.3-26.2 min on the standard runner, 10.1-10.3 min on the verification hosts. |
777843
| `corpus-parity-subset` | 30 | 1.8-4.7 min on the standard runner, 2.4-3.8 min on the verification hosts. |
778844
| `build` (aggregate) | 5 | Seconds. |
845+
| `changes` | 5 | Seconds: a two-commit checkout and one `git diff`, on the standard runner. |

0 commit comments

Comments
 (0)