The release gate needs its own fixture repo — the canary cannot be trusted as one

[mmcky]

#135 proposes gating a release on a green canary. This issue argues that test-actions-lecture-intro cannot serve as that gate, and proposes splitting the two roles across two repos.

Raised from the consumer side (QuantEcon/workspace-lectures#33), but the work is entirely local to this repo and its fixtures.

The role conflict

test-actions-lecture-intro is, by its own history, the feature sandbox — the place a new action or version gets tried end to end. Recent commits: feat: enable PR-scoped build caching in CI (#36), feat: build PDF and notebooks in CI preview (#35), Test: Migrate to quantecon/actions@v0 (#26), chore: update to quantecon/actions v0.5.0 (#33). PR #49 relabelled it the canary, but nothing about its shape changed to match.

That is a genuinely useful role. It is just not compatible with being a gate, because a gate's whole value is that red means stop — and red in that repo is ambiguous.

Three things that can turn it red without the release being at fault

Each verified against the repo as it stands today:

Hazard	Evidence
Floating container	cache.yml:15, ci.yml:10, publish.yml:22 all run ghcr.io/quantecon/quantecon-build:latest. The environment changes underneath independently of the candidate, so a red may be a new image rather than a bad release
Build-time network reads	The fixture carries roughly a dozen remote data URLs, including high_dim_data and media.githubusercontent.com, with at least one lecture reading a CSV at build time (added in #48). Those exact URLs are being moved right now by the datasets migration, and media.githubusercontent.com 404s on plain-git files. A gate that fails on someone else's repoint is not a gate
Dependabot is enabled	.github/dependabot.yml is active with three open PRs, including sphinx-proof and Python 3.13 → 3.14. Merging any of them changes gate behaviour without a release having happened

A fourth, milder point: it runs container mode only, which today is lecture-dp's shape. The other six lecture repos still run conda/miniconda, so the gate would currently certify a path most consumers do not use. That resolves itself as QuantEcon/workspace-lectures#31 section B lands, but not before.

Proposal: split by role, not by consumer

Let each repo be good at one question.

Repo	Question it answers	Shape
test-actions-lecture-intro (existing)	Does the new thing work against a real-ish repo?	Realistic, messy, Dependabot on, :latest, pinned @v0. Keep as-is
New gate repo	Is this candidate releasable?	Frozen and boring — see below

Gate repo properties

Every one of these is a direct answer to a hazard above, so none is decoration:

• container pinned by digest, never a moving tag — a gate must vary only the thing under test;
• zero network reads at build time — every data file vendored into the repo;
• Dependabot off, no open dependency PRs, no ambient drift;
• small — roughly five lectures, so a run is minutes rather than the current fixture's fifty. A slow gate gets bypassed, which is the same failure as no gate;
• pinned @v0-next, per Release gating: require a green canary before v0 moves (adds a v0-next staging tag) #135, so it exercises the candidate rather than the previous release;
• content chosen to exercise what has actually broken in production rather than to look like a lecture site: a plotly cell forcing static export through kaleido (the Pin kaleido<1.0 in both containers to fix ChromeNotFoundError #85 path), a real matplotlib render, and quantecon_book_theme under xelatex. This is the fixture critique from testing: publish/preview/cache action logic has no automated tests #100's design comment, which the current fixture never adopted.

Why not a second workflow set in the existing repo

The hazards are repo-level properties, not workflow-level ones. Dependabot config is per repo. Vendored versus remote data is per repo. A frozen fixture and a drifting one cannot coexist in one tree. Two Pages targets is also a feature rather than a cost — a gate publishing over the sandbox's site would be its own problem.

Why not a repo per consumer shape yet

There are two axes, and only one justifies a new repo today. Role (sandbox versus gate) is immediate and is what the hazards above are about. Consumer shape (container versus conda, LaTeX-first versus tojupyter-first) is real today but is actively being migrated away by QuantEcon/workspace-lectures#31 section B — building per-shape fixtures now means maintaining fixtures for a shape being deleted.

Fixture-maintenance cost is what let the current fixture drift out of usefulness in the first place; multiplying it is the failure mode to avoid. Name the new repo for its role, and add a shape-specific one only if a genuinely divergent shape persists. lecture-jax's GPU path is the plausible candidate, already parked behind QuantEcon/lecture-jax#284.

The tradeoff, stated plainly

A small synthetic fixture can go green while a real fifty-lecture build fails. That is the price of determinism, and it is exactly why the sandbox should keep existing rather than be replaced. Gate catches regressions; sandbox catches integration surprises. Different questions, neither redundant.

Open questions

Question	Notes
Name	test-actions-release, test-actions-gate, or another member of the test-actions-* family
Fixture provenance	Purpose-built minimal lectures, or a trimmed copy of intro? Leaning purpose-built — a trimmed copy inherits the remote data URLs that are hazard #2
Does the sandbox's role get written into its README?	So the next person does not try to gate on it again, which is how this issue came about

Related

• Release gating: require a green canary before v0 moves (adds a v0-next staging tag) #135 — release gating and the v0-next staging tag; this is the fixture half of it
• testing: publish/preview/cache action logic has no automated tests #100 — testing; its stage 2 assumed one canary repo could do both jobs, and its design comment already described the fixture this proposes
• Pin kaleido<1.0 in both containers to fix ChromeNotFoundError #85 — the kaleido static-export failure the fixture should deliberately exercise
• test: unify container smoke tests and make the fixture exercise the Dockerfiles #108 — the smoke tests that could not fail; the same "fixture that cannot detect what it is for" problem, one level down
• QuantEcon/workspace-lectures#33 — the consumer-side view

[mmcky]

Name decided: test-actions-release.

It reads as the role rather than a consumer, which is the distinction that justifies the repo existing at all — the split is sandbox-versus-gate, not intro-versus-jax. It also sits naturally in the test-actions-* family beside test-actions-lecture-intro, so the pair is discoverable together, and it leaves room for a shape-specific sibling later if one is ever warranted (the GPU path being the only plausible candidate, and parked behind QuantEcon/lecture-jax#284).

That resolves the first open question; the fixture-provenance and README questions above are still open.

[mmcky]

Fixture provenance decided: purpose-built, not a trimmed copy of intro.

This is the choice that makes the gate trustworthy rather than merely smaller, and it has some concrete consequences worth writing down now.

Hazard #2 disappears by construction. A trimmed copy inherits the remote data URLs — that was the whole problem. Purpose-built content has no reason to fetch anything, so high_dim_data, media.githubusercontent.com and the datasets migration simply stop being able to turn the gate red.

Prefer generated data over vendored data. Since nothing is inherited, most cells can generate their own inputs — seeded numpy, a constructed DataFrame — which is stronger than vendoring: no files to drift, no LFS question, byte-identical every run. One small committed file is probably still worth keeping so the {download} and datasets path is exercised at all, but it should be the exception rather than the default.

Content is chosen by failure mode, not by subject. The fixture exists to break when the actions break, so each lecture should earn its place against something that has actually gone wrong in production: a plotly cell forcing static export through kaleido (#85), a real matplotlib render, and quantecon_book_theme under xelatex. #100's design comment made this argument for the existing fixture and it was never adopted — execute_notebooks: "off", a plain ```python fence rather than a {code-cell}, `html_theme: sphinx_book_theme`, and `fontpkg: ""` between them meant it could not fail in any of the ways that matter (#108).

It must cover all three builders, since the gate has to certify the publish path: pdflatex, jupyter and html — the sequence test-actions-lecture-intro's own publish.yml runs today.

Build in the self-test from the start. A gate that has never gone red is not known to work, and this repo has the precedent twice over (#108, #83). A purpose-built fixture can carry a staged-failure mode deliberately — the --self-test pattern test-container.yml adopted in #108 — so "prove the gate can stop a release" is a switch to flip rather than a thing to improvise later.

The one cost to keep in view: a small synthetic fixture can go green while a real fifty-lecture build fails. That is why test-actions-lecture-intro keeps the sandbox role rather than being retired — which is the remaining open question above.

[mmcky]

Correction — two claims in the issue body are wrong, and one hazard should be withdrawn.

I audited lectures/ without accounting for only_build_toc_files: true.

Hazard #2 (build-time network reads) does not apply. lectures/_toc.yml builds five lectures — geom_series, short_path, lln_clt, solow, linear_equations — selected against explicit criteria that include no network access at build time, with the other 45 left on disk and unbuilt. Checked directly: the built set contains zero remote data reads. The dozen URLs I cited are all in lectures that never build. Withdrawn.

"PR #49 relabelled it the canary, but nothing about its shape changed to match" is also wrong. #49 trimmed the toc, repinned @v0, and documented the reasoning in both the README and _toc.yml — including the April 2026 incident where the full book went red on a raising cell in inequality.md and stayed red and unwatched for months. That is the same signal-quality argument this issue makes, already acted on. I did not credit it.

What still stands, all re-verified:

Hazard	Status
Floating container — quantecon-build:latest in all three workflows	Holds. Repo-level environment drift, independent of the candidate
Dependabot enabled, three open PRs incl. sphinx-proof and Python 3.13 → 3.14	Holds
Pinned @v0, so it cannot exercise a candidate	Holds — the #135 problem
Role conflict	Holds. The commit history is still feature work end to end
Container-mode only, while six of seven lecture repos run conda	Holds, and self-corrects as QuantEcon/workspace-lectures#31 section B lands

And one gap the correction surfaced. The five built lectures exercise matplotlib, numpy linear algebra, scipy sampling, iterative dynamics and LaTeX-heavy math — but no plotly, and therefore no kaleido static export. That is the #85 failure path, and it is uncovered today. It is a good argument for the purpose-built fixture agreed above, and a cheap thing to add here in the meantime.

The case for a separate repo is narrower than the body argues, but intact. The decisive point is not fixture hygiene — #49 already did that work — it is that the sandbox wants Dependabot and a moving container, because that is how upstream breakage gets discovered early, while a gate must have neither. Those are contradictory repo-level settings, so one repo cannot hold both roles.

[mmcky]

Open question 3 resolved: yes. QuantEcon/test-actions-lecture-intro#52 writes the sandbox role into that repo's README, including the table of why its three ambiguity-inducing properties are the right ones for a sandbox and disqualifying for a gate.

All three open questions are now settled — name test-actions-release, purpose-built fixture, sandbox role documented.

[mmcky]

Sequenced under #138, the tracking issue for the gating work — it holds the order, the definition of done, and the open decisions. This issue keeps the design detail; #138 does not duplicate it.

PLAN.md now carries the same work as backlog items 0a–0d at P0 (#137).

[mmcky]

Verified this issue's claims against the canary and the repo before starting 0a, since it authorises creating a repository. The instinct is right and is already partly acted on — but several of the specific claims do not hold, and the "one repo cannot do both" inference is not earned. Recording it here rather than editing the body, since the decision is still open.

The reshaping already happened. PR #49 (merged 2026-08-05) cut lectures/_toc.yml to 7 documents, +22/−82. Its selection criteria, still at the top of that file, are verbatim the gate properties proposed here: no build-time network access, no heavy or optional imports, no local {doc} cross-references, no {cite} references. So "PR #49 relabelled it the canary, but nothing about its shape changed to match" is not accurate. The commits cited as evidence (#26, #33, #35, #36) are from Jan–Feb 2026 and sit at positions 5, 6, 9 and 13 in a 23-commit history — #49 and #52 are the two most recent and are the ones that contradict the framing.

Three related corrections. The last four CI runs took 3m, 3m, 3m and 6m, not "fifty". The built documents make no network reads — all 17 remote URLs live in the 44 .md files that only_build_toc_files: true excludes. And "must cover plotly/kaleido — the #85 path is uncovered by any fixture today" is wrong: containers/quantecon/tests/smoke-test.sh covers to_image export, and it has a staged-failure self-test.

Two of the three disqualifiers are not repo-level. container: is set per-workflow-file — three independent blocks at cache.yml:15, ci.yml:10, publish.yml:22 — and linkcheck.yml declares no container and no @v0 refs at all, so per-file variation already exists in that tree. Dependabot has not run since 2026-02-16; all 8 open PRs are mergeable_state=dirty against SHAs 19+ commits stale, and per-dependency ignore is a supported but unset knob. That leaves @v0 refs, which are also per-file.

The genuinely repo-level facts point the other way. The canary already holds NETLIFY_SITE_ID, a live Pages target and a gh-pages branch — it is the only place preview-netlify and publish-gh-pages have ever executed. And GitHub's 60-day inactivity disable already cost it 17 consecutive Sundays, which argues specifically against a deliberately frozen, zero-commit repo: the design maximises the one failure mode this org has already suffered.

The strongest argument for the gating work is not the one this issue makes. The canary's publish.yml has run 9 times ever and last on 2026-02-10, so publish-gh-pages has had zero end-to-end exercise across v0.7.0 → v0.11.1. That is a better case than "least-gated action in the set", which is literally false — preview-cloudflare has no coverage and no consumers anywhere.

A blocker that hits either option. Both preview actions gate three steps on github.event_name == 'pull_request' (preview-netlify/action.yml:48,63,101; preview-cloudflare/action.yml:60,75,148), so a dispatch-driven gate skips the build, deploy and comment and reports green having deployed nothing. A new fixture repo inherits that unchanged.

Next step: #143, which settles the two assumptions underneath both this issue and #135 for well under a day of work. The decisive one is whether uses: ./checked-out-path resolves for a composite action inside a container: job — the same host-vs-container path class that produced the 127 in #83. If it works, a single gate.yml in this repo holds every property asked for here and neither a second repo nor a v0-next tag is needed. If it fails, this issue stands as written and #135's design is the right one.

Leaving open pending #143.