@@ -11,6 +11,8 @@ This checks the CI/native workflow syntax, expressions and shell commands,
1111source ABI/hash/schema guards, and the verifier's failure-handling tests. A
1212failure 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 ) ).
1416It does not compile the engine or replace any complete verification profile.
1517
1618Then 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
4244The 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
4064081792 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
413416full verification on the PR head's exact tree.
414417
@@ -603,14 +606,17 @@ Compiler objects, binaries and dependency caches are not uploaded
603606as diagnostics.
604607
605608Superseded 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;
608612both Debug jobs, sanitizers and native-live run the registered set excluding
609613the 29 CTest rows labelled ` slow ` in ` tests/CMakeLists.txt ` . The first 27 were
610614chosen from INT23/INT24 job logs: over 60 seconds in either sanitizer run or
611615over 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
614620legs, V19-FIX's scaling rows, and the new KERNEL-EDGE, K-ULP4, C-SURFACE-1 and
615621DOC-TRUTH-4 rows) in a full sanitizers and Debug run on the maintainers' x86-64
616622verification 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
627633threshold (the largest, ` test_magnified_aggregated_tape ` , 3.4 s under
628634sanitizers).
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 `
632639bounds CTest at 30 minutes otherwise, the PR set included), because main's full
633640set ran out of 30 minutes twice, and the sanitizers job allows 120 minutes for
634641that 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
651658manual corpus workflow, and the maintainers' full parity verification, keep
652659the 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
656716The 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
705765standard 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
708769Each `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
712773most eight jobs at once, and one CI run starts seven there (preflight, the two
713774Ubuntu `build` legs, sanitizers, kernel-only, native-live and the parity
714775subset); 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
716778for a runner. Larger runners bill the organization's Actions budget : with no
717779payment method or a spending limit of zero, their jobs wait for a runner that
718780never 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
734796commands are chained, blocked or carried, with the flag and its value on one
735797line), or any other `--jobs` or `JOBS` value fails preflight, and so does a jobs
736798line 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
739805More 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