From 822a204248a0ef7ced2d620c6e2e65a2f6a0bd0c Mon Sep 17 00:00:00 2001 From: DoubleGate Date: Mon, 20 Jul 2026 02:54:45 -0400 Subject: [PATCH 1/2] ci: give rustdoc its own job instead of burying it in `test` A commit with a broken intra-doc link reached the PR branch last cycle. I said CI would have caught it; checking the run history, that was wrong in an instructive way -- the run on that commit is marked CANCELLED, not failed. rustdoc never executed. The gate did not fail, it did not run. Two causes, both structural rather than bad luck: 1. rustdoc was the LAST step of the `test` job, sitting behind fmt, clippy and the full test run. With `cancel-in-progress` enabled for pull_request events (a deliberate cost optimisation), a quick follow-up push supersedes the run -- and whatever is furthest from the front of the queue is what gets lost. Being last made it the most likely casualty. 2. When it did fail, it reported as "test (ubuntu-latest) failed", which points at the wrong subsystem. Nothing in the check name said "docs". Now its own job: `rustdoc (-D warnings)`, ubuntu-only, with no `needs:` so it starts immediately rather than queueing behind the matrix. It finishes in well under a minute -- fast enough to be genuinely useful feedback, and small enough that it is rarely mid-flight when a supersede happens. The job name now names what broke. The comment in the workflow records WHY it is a separate job, so a future tidy-up does not fold it back into `test` as an apparent simplification. Verified rather than assumed: reintroducing the exact defect that slipped through (public docs linking to the private `Pipeline::flush_pending`) makes the new job's command fail, while `cargo test --workspace` stays green and blind to it -- which is precisely why it needed to stop being a step inside the test job. Note this does not change what `main` is verified against: cancel-in-progress only applies to pull_request events, and the post-merge run on `main` always executes in full. What was at risk was catching the problem EARLY, on the PR, which is the entire point of running it there. Co-Authored-By: Claude Opus 4.8 --- .github/workflows/ci.yml | 29 ++++++++++++++++++++++++++++- CHANGELOG.md | 15 +++++++++++++++ 2 files changed, 43 insertions(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 0e5d0a81..74b745a8 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -79,8 +79,35 @@ jobs: - run: cargo fmt --all --check - run: cargo clippy --workspace --all-targets -- -D warnings - run: cargo test --workspace + + rustdoc: + name: rustdoc (-D warnings) + # Its OWN job, deliberately, for two reasons learned the hard way. + # + # 1. It used to be the LAST step of the `test` job, after the slow test run. + # That made it the most likely thing to be lost when a follow-up push + # cancelled the run (`cancel-in-progress` below), and in practice a commit + # with a broken intra-doc link sailed through because the run was + # CANCELLED before rustdoc ever executed -- not because it passed. + # 2. A rustdoc failure reported as "test (ubuntu-latest) failed", which + # points at the wrong thing. Now the job name says what broke. + # + # No `needs:`, so it starts immediately and finishes in well under a minute + # -- fast enough to be genuinely useful feedback, and small enough that it is + # rarely mid-flight when a supersede happens. + runs-on: ubuntu-latest + timeout-minutes: 30 + steps: + - uses: actions/checkout@v7 + - uses: dtolnay/rust-toolchain@1.97 + - uses: Swatinem/rust-cache@v2 + # rustdoc builds the whole workspace including the frontend, so the + # alsa/udev headers its build scripts need must be present. + - uses: ./.github/actions/linux-build-deps + # -D warnings turns every rustdoc lint into an error: broken intra-doc + # links, public docs linking to private items, and missing docs on public + # items (the workspace sets `missing_docs = "warn"`). - run: RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps - if: runner.os == 'Linux' test-roms: name: test (test-roms feature) diff --git a/CHANGELOG.md b/CHANGELOG.md index b162a8cd..706d75e5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,21 @@ All notable changes to RustyN64 are documented here. The format is based on The next rung is `v0.2.0 "Interpreter"` — the VR4300 (see [`to-dos/VERSION-PLAN.md`](to-dos/VERSION-PLAN.md)). +### Fixed — rustdoc gets its own CI job + +`RUSTDOCFLAGS="-D warnings" cargo doc` was the **last step of the `test` job**, after the slow +test run. Two consequences, both observed rather than theorised: + +- It was the most likely thing to be lost to `cancel-in-progress`. A commit with a broken + intra-doc link (public docs linking to a private item) went through with its run marked + **`cancelled`, not failed** — rustdoc never executed. The gate did not fail; it did not run. +- A rustdoc failure reported as `test (ubuntu-latest) failed`, pointing at the wrong subsystem. + +Now a dedicated `rustdoc (-D warnings)` job with no `needs:`, so it starts immediately, runs in +parallel with the tests, and finishes in well under a minute — fast enough to be useful feedback +and small enough to rarely be mid-flight when a supersede happens. Verified by reintroducing the +exact defect that slipped through: the job's command rejects it, and `cargo test` is blind to it. + ### Added — the ADR 0007 five-stage pipeline (T-11-001, second half) `crates/rustyn64-cpu/src/pipeline.rs`. **Structure, not instructions** — the stages move latches From 2e420814787b7e7a0caf4e5e1a29c02a11f04197 Mon Sep 17 00:00:00 2001 From: DoubleGate Date: Mon, 20 Jul 2026 02:57:55 -0400 Subject: [PATCH 2/2] docs: quote the rustdoc gate's exact invocation in the CHANGELOG Adopts Copilot's comment on PR #3. The entry abbreviated the command to `RUSTDOCFLAGS="-D warnings" cargo doc`, dropping `--workspace --no-deps`. Harmless as prose, but the entry is describing a CI gate, so it reads as a local repro -- and the abbreviated form behaves differently: without `--no-deps` it documents every dependency too, so `-D warnings` can fail on third-party doc warnings the project does not control. Someone copying it to reproduce a CI failure could land on a confusing false positive. Co-Authored-By: Claude Opus 4.8 --- CHANGELOG.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 706d75e5..aa05981c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,8 +11,8 @@ The next rung is `v0.2.0 "Interpreter"` — the VR4300 (see ### Fixed — rustdoc gets its own CI job -`RUSTDOCFLAGS="-D warnings" cargo doc` was the **last step of the `test` job**, after the slow -test run. Two consequences, both observed rather than theorised: +`RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps` was the **last step of the +`test` job**, after the slow test run. Two consequences, both observed rather than theorised: - It was the most likely thing to be lost to `cancel-in-progress`. A commit with a broken intra-doc link (public docs linking to a private item) went through with its run marked