Next steps after the 2026-09-28 session: release gating (#138) and loose ends

[quantecon-services]

Hand-off from the 2026-09-28 session, so the work can be picked up again. Close this once every item below is done or has moved into its own issue.

Where things stand

• The release-gating spike is done (Spike: settle the two gate-mechanism assumptions before building for them #143). Its results are in the findings comment.
  • A gate can check out a candidate commit and call uses: ./actions-repo/<action> inside a container job.
  • On any event but pull_request, both preview actions pass without deploying, and nothing in the log says so.
  • Rewriting four uses: lines lets a gate test build-jupyter-cache's internal calls at the candidate, which the planned v0-next tag could not.
• The docs the spike disproved are corrected in docs: correct the statements the #143 spike disproved #211, which is merged. docs/dev/PLAN.md items 0a–0c now record the result. The decisions are still open.
• The spike's code is kept. .github/workflows/spike-143.yml and .github/spike-143/ are in the commits of [spike QuantEcon/actions#143, DO NOT MERGE] local uses: in a container job test-actions-lecture-intro#69. That PR is closed and its branch deleted. The workflow is a starting point for a gate.yml.
• The evidence is kept. The canary runs are 36378684976 (push), 36378695414 (dispatch) and 36378719592 (pull_request). Their evidence artifacts are kept for 90 days.

Next steps

In dependency order. Steps 4 and 5 can happen at any time.

1. Decide #143

These are the questions left open in the findings comment:

• Where the gate lives: a gate.yml in the canary, or a new fixture repo (The release gate needs its own fixture repo — the canary cannot be trusted as one #136).
• How previews get tested outside a PR: an opt-in input in the preview actions, or a gate that opens a PR.
• Which candidate commits the gate accepts. The suggestion is main and v* tags only. Also decide whether the gate's secrets live in an environment only main can use.
• Build conditions: a committed image digest or :latest resolved once per run; cold or warm builds; intersphinx on or off.
• Whether the gate covers publish-gh-pages. Doing so would overwrite the canary's Pages site.

Then:

• Record the choices on Spike: settle the two gate-mechanism assumptions before building for them #143 and close it.
• Re-scope Release gating: require a green canary before v0 moves (adds a v0-next staging tag) #135: drop v0-next?
• Re-scope The release gate needs its own fixture repo — the canary cannot be trusted as one #136: gate fixture content and hygiene, rather than a new repo?
• Refresh Tracking: release gating — get to a candidate that is verified before v0 moves #138's "Where we stand".

2. Fix the preview actions (no issue yet)

This is needed if step 1 picks the opt-in input. It is also needed before a scheduled canary ci.yml (PLAN 0c) can test anything. The suggested design:

• An opt-in input, for example dispatch-alias, limited to a reserved dispatch- prefix so it can never hit pr-N or Cloudflare production.
• An allow-list of events (workflow_dispatch, schedule), never a deny-list. The pull_request literal is what keeps pull_request_target out (fix(preview): surface deploy errors, pin CLIs, remove unsafe fork guidance #105).
• A deployed output, and a ::notice:: whenever nothing is deployed. Callers check deployed == 'true'.

The release that ships this changes every consumer's PR path. Test it by hand with a real canary PR first (CONTRIBUTING.md, Staged Releases).

3. Build the gate and prove it (PLAN 0b–0d)

• gate.yml: a workflow_dispatch input for the candidate SHA, checked against main and v* tags before any secret is used.
• Fixture: add what The release gate needs its own fixture repo — the canary cannot be trusted as one #136 asks for and the canary lacks: plotly/kaleido (Pin kaleido<1.0 in both containers to fix ChromeNotFoundError #85), all three build-jupyter-cache builders, cold builds, and no network reads.
• 0c: give the canary's publish.yml a workflow_dispatch trigger and remove its tag-only job if:. Schedule ci.yml once step 2 has shipped.
• 0d: a deliberately broken candidate must turn the gate red and stop the v0 move, and a red gate must reach a person.

4. The next release

• [Unreleased] changes what build-lectures (feat(build-lectures): print failed notebooks' tracebacks in the failure report #198) and setup-environment (fix(setup-environment): bumping cache-version builds a fresh Conda environment (#205) #206) do. So the next release needs the manual canary check whether or not the gate exists yet.

5. The canary's README (QuantEcon/test-actions-lecture-intro)

• After step 1, rewrite "This repo is not the release gate". Its @v0 and :latest reasons are per workflow, not per repo.
• Fix "no build-time network access": cold builds fetch intersphinx inventories.

Loose ends

• Container validation: no image reaches :latest untested, and the lecture matrix is a trustworthy signal #188's "Where we stand" named test-containers-lectures: absorb transient raw-GitHub 429s when building lecture repos #102 (closed) as the next item. Updated on 2026-09-28: it names test-containers-lectures: lecture-python.myst doubled to the 120-minute ceiling #141, and its status bullets reflect that day's matrix run.
• PLAN.md's test-containers-lectures: absorb transient raw-GitHub 429s when building lecture repos #102 row said "Review ci(lecture-validation): retry a failed HTML build once with --all; restore lecture-python-programming to the matrix #203" and called Retry transient lecture HTML build failures #144 open; both are closed. Fixed by docs(plan): record #102 as closed by #203, and the run that exercised it #214, merged on 2026-09-28.
  • The weekly matrix run 36370003884 exercised ci(lecture-validation): retry a failed HTML build once with --all; restore lecture-python-programming to the matrix #203's retry.
  • 6 of 8 legs passed, lecture-python-programming included.
  • Both lecture-python.myst legs failed the retry, on bayes_nonconj only.
• The weekly matrix stays red (🔴 CI failure: Test Container Builds #159) until bayes_nonconj: declare the truncated log-normal prior's (0, 1] support (numpyro 0.22) lecture-python.myst#1065 fixes bayes_nonconj (numpyro 0.22).
• Decision: HTML-only previews — stale PDF/ipynb download buttons and the weekly LaTeX-breakage SLA #146, open since July, still blocks lecture-python.myst: HTML-only PR previews; three-format build behind a full-preview label #148, Optimize preview builds: phased plan for the fastest PR previews (tracking) #92's biggest speed-up.
• The user manual (docs: a user manual for every action (what it does, how to set it up, every input and output) #178): PRs 2 and 3 merged (docs(manual): doc generator and drift checks, the chapter template, and the setup-environment chapter (#178 PR 2) #204, docs(manual): chapters for the other seven actions, and delete QUICK-REFERENCE.md (#190) #213), so the next item is docs(manual): cross-cutting chapters, signpost the templates and container READMEs, delete MIGRATION-GUIDE and CONTAINER-GUIDE #191.

Notes for a Claude session picking this up

• If the gate is built in the canary, add QuantEcon/test-actions-lecture-intro to the session with push access.
• The session's network proxy blocks artifact downloads (*.blob.core.windows.net). Read job logs through the API instead.
• The session's git proxy refused to delete a branch. Delete branches in the GitHub UI.