Skip to content

feat(restore-jupyter-cache): the templates restore the execution cache, keyed on the environment too (#270) - #280

Merged
mmcky merged 5 commits into
mainfrom
feat/270-execution-cache-templates
Nov 7, 2026
Merged

mmcky merged 5 commits into
mainfrom
feat/270-execution-cache-templates

Conversation

@mmcky

@mmcky mmcky commented Nov 7, 2026

Copy link
Copy Markdown
Contributor

#160's step 1 (#275) made a build-cache restore remove the restored <path>/html. That stopped a deleted page or static file from being published again. It left _build/jupyter and _build/latex, as the last cache build made them, including a removed lecture's notebook and a deleted PDF. A workflow that builds jupyter or pdflatex over the restored build cache, and copies their output into the site, still publishes those. The canary's ci.yml does that, and so does either template with its download steps uncommented. The rest of the restored _build saves no work: a fresh checkout gives every source file a new modification time, so Sphinx rewrites every page. Only _build/.jupyter_cache spares anything, by sparing notebook execution.

So this PR is step 2: the templates restore cache-type: 'execution', _build/.jupyter_cache alone. That could not be done as things stood, because of how the two caches were keyed:

  • the build cache's key hashes the environment files, and never falls back across a change to environment;
  • the execution cache's key hashed only the lectures, and fell back to any execution cache.

So under execution, a pull request that changed environment.yml, an Anaconda baseline bump for one, restored outputs made with the old packages, re-executed nothing, and passed. This PR gives the execution cache the build cache's environment keying first. The maintainer agreed the design and its three decisions on #270, comment.

cache-type: execution Before After
Key build-jupyter-cache saves jupyter-cache-<md>-<run id> jupyter-cache-<env>-<update>-<md>-<run id>
Restore's fallbacks, after the key's own prefix jupyter-cache- (any execution cache) jupyter-cache-<env>-<update>-, then jupyter-cache-<env>-: the build cache's, exactly
A pull request that edits a lecture Falls back to the cache build's execution cache The same
A pull request that changes environment Restored the old packages' outputs, and passed Misses, and executes every lecture, as build does
A pull request that changes only a separate environment-update file Restored Restored, through jupyter-cache-<env>-, as build does (the maintainer's decision 3)
environment, environment-update inputs "Ignored for the execution cache" Apply to both types

<env>, <update> and <md> are the hashes of environment, environment-update and the .md files under source-dir. restore-jupyter-cache's default stays build, and its build restore is unchanged.

Changes

File Change
build-jupyter-cache/action.yml "Generate cache keys" makes both keys in one step, the execution cache's from ENV_HASH, UPDATE_HASH and SOURCE_HASH through env:, and logs both. "Save execution cache" takes steps.cache-key.outputs.exec-key in place of its inline hashFiles. The environment and environment-update descriptions say the hash is part of both caches' keys. No new input or output: cache-key is still the build cache's
restore-jupyter-cache/action.yml The execution branch builds the new key and the fallbacks in the table above, with a comment on why. The environment and environment-update descriptions lose "With cache-type: build" and "Ignored for the execution cache". The status report's "No cache found" list loses "After lecture content changes (execution cache)". A lecture change never caused a miss, since it falls back, and "After environment.yml changes" now covers both types
templates/ci.yml The restore step becomes "Restore execution cache", with cache-type: 'execution' and a comment on why. The header, the prerequisites, the pdf-check hand-off comment and the execute_notebooks note say which cache
templates/publish.yml The restore step becomes "Restore execution cache", with with: cache-type: 'execution' and the same comment. The header changes to match
templates/cache.yml The header's first line names both caches. The install-latex lines are untouched, since the latex session may edit them
.github/workflows/test-actions.yml See "The tests"
docs/user/actions/restore-jupyter-cache.md The generated input rows. The chapter:
• recommends execution, and says when the build cache is still the one: a build that offers the PDF or the notebooks without building them;
• restores execution in its minimal and save-cache examples, and adds an example for the build cache;
• "In the templates" says how a repository that copied an older template moves;
• the keys table, "Why the keys are what they are", the last paragraph of "The restored HTML is removed" and three troubleshooting entries follow
docs/user/actions/build-jupyter-cache.md The generated input rows, the caches table's new key, and two sentences naming which cache
docs/dev/ARCHITECTURE.md "Two caches" only: the execution cache first, as the one the templates restore, and the build cache as the default's
docs/user/getting-started.md, composition.md, actions/publish-gh-pages.md, actions/build-lectures.md Each said the templates restore the build cache, or that only the build cache's key hashes the environment. Agreed with the organiser, since none is in this session's list. build-lectures.md is the chapter only, not the action
docs/dev/TESTING.md restore-jupyter-cache's row adds unit-exec-env-miss
docs/dev/PLAN.md The "Preview speed" row drops #270
CHANGELOG.md Two entries under [Unreleased], ### Changed, with no ⚠️ marker, as the maintainer decided

The tests

  • The header's second constraint used to say that a genuine execution-cache miss could not be built, because of the bare jupyter-cache- fallback. It now says why every restore with generated keys passes a salted environment. Both types' fallbacks now include its hash, and with no file the hash is empty, so the fallback would match other runs' caches.
  • unit-exec-seed writes and passes a salted harness/environment.yml, and asserts a genuine miss, as unit-build-seed does.
  • unit-exec-restore and unit-exec-restore-save pass it, and expect the new key.
  • New, unit-exec-env-miss. It restores the seed's lectures, byte for byte, under a differently salted environment file, and asserts a miss with no _build/.jupyter_cache. Then, as the control, it restores with the seed's environment and an edited lecture, and asserts a fallback hit under jupyter-cache-<env>-- with the seed's STAMP. That control is what nearly every pull request does. It is in harness-summary's needs: beside the other unit-exec-* jobs.
  • bjc-restore-exec passes the fixture's environment, and expects the new key. bjc-smoke runs this PR's own build-jupyter-cache, whose save steps are its own, not @v0's, so this round trip shows the save and the restore agree.

Callers

I checked every QuantEcon workflow that calls either action, through code search in the org and across GitHub, and read each hit's workflows through the API:

Caller Restores Effect of this PR
lecture-dp, ci.yml and publish.yml The default, build None: the build cache's key and restore are unchanged. Once v0 moves, its cache.yml saves the execution cache under the new key, which it does not restore
The canary, ci.yml cache-type: 'build', with save-cache: 'true' None, as above
test-lecture-theme-sphinx Nothing, deliberately. It runs build-jupyter-cache only Its execution cache gets the new key, unread

Nothing outside QuantEcon calls either action. No workflow restores execution, which is why the CHANGELOG entry carries no ⚠️ marker. A workflow that did would miss once after v0 moves, until its next cache build: slower, not failing, unless it also sets fail-on-miss: 'true'. The entry says so.

A repository that copied an older template keeps the build cache, with step 1's prune, until it changes:

  • in ci.yml, cache-type: 'build' becomes cache-type: 'execution' on the restore step;
  • in publish.yml, the restore step, which passes no inputs, gains with: cache-type: 'execution'.

If its cache.yml gives build-jupyter-cache an environment or environment-update, the restore steps should be given the same, as before. A site that offers the PDF or the notebooks from the build cache without building them keeps build.

What I checked, and how

The issue, against origin/main at e40924a, in the agreed check, posted on #270. Every claim held, but most cited lines had moved since 9644f17:

  • the execution key and its fallbacks were at restore-jupyter-cache/action.yml:167-185;
  • the template restore steps at templates/ci.yml:157-162 and templates/publish.yml:91-92;
  • the harness's execution-key assertions at :753, :786 and :2646.

The check found two things the issue did not say:

  • The new fallback carries the salted environment hash only if the jobs pass a salted file, and none did. The repository has no root environment.yml, so the hash would have been empty.
  • The red test is decisive only if the lectures are held fixed. Then today's key, which hashes the lectures alone, restores the seed's own cache.

Storage, for M3 (gh api …/actions/caches):

Repository Build cache Execution cache
lecture-dp 91.6 MiB 15.7 MiB
The canary 6.3 MiB 0.7 MiB

lecture-python.myst's zipped _build artifact is about 300 MiB. The maintainer kept the full _build save unchanged, since restore-jupyter-cache's default restores it. Retiring it, or making it opt-in, goes with a later change of that default.

The new checks fail on today's actions. I pushed the harness commit alone, 8d1f898, on main, to a throwaway branch, and dispatched the harness. Two jobs failed at their new assertions:

  • unit-exec-seed reported cache-hit: expected [false], got [true] with key [jupyter-cache-0402c945…-42316732919]. That is another run's execution cache from main, through the bare fallback.
  • bjc-restore-exec reported cache-key: expected [jupyter-cache-c263993c…--c0d06946…-42345491853], got [jupyter-cache-c0d06946…-42345491853]. Today's save key has no environment hash.

The seed's failure skipped its three dependents. So I pushed one more commit to the throwaway branch, for the demonstration only: continue-on-error on the seed's miss assertion, so the dependents run against today's actions too. That run failed them all:

  • unit-exec-env-miss, the new test: cache-hit: expected [false], got [true] with key [jupyter-cache-3fc5c339…-42345836349]: outputs executed under another environment were restored (#270). Today's key hashes the lectures alone, so it restored the seed's own cache under a different environment file.
  • unit-exec-restore and unit-exec-restore-save: cache-key: expected [jupyter-cache-46c0469a…--3fc5c339…-42345836349], got [jupyter-cache-3fc5c339…-42345836349].
  • bjc-restore-exec: as in the first run.

I then deleted the throwaway branch.

Locally, with actionlint 1.7.12 (its release's SHA-256 checked) and shellcheck 0.11.0: python3 scripts/generate-docs.py --check --check-examples --actionlint …, actionlint and python3 scripts/lint-shell.py are clean, and the CHANGELOG diff adds lines only under [Unreleased].

This branch's harness run is this PR's own check: every changed job must pass with the new keys.

What to watch after merge

Nothing runs at merge. The PR changes no containers/** file, and neither setup-environment nor build-lectures, so it needn't wait for Monday's lecture-matrix run. The templates reach a repository only when copied, and the key change reaches callers when v0 moves to the release that carries it. The harness on main saves new-format keys from the merge on.

For the staged release, the canary should exercise this. On a staging branch, switch the canary's ci.yml to cache-type: 'execution', keeping save-cache: 'true', then show:

  1. A staged cache.yml run logs the execution cache key as jupyter-cache-<env>--<md>-<run id>.
  2. A staged pull request reports an execution restore with a matched key, and its build executes only the lectures it changed.
  3. A staged pull request that deletes a lecture and a _static file gets a preview where the lecture's page, its _notebooks/<lecture>.ipynb and the static file return 404, while a control page returns 200. The notebook is the case step 1 could not fix: under build, the canary builds jupyter over the restored cache, and the notebook comes back.
  4. A staged pull request that changes environment.yml reports "No cache found", and executes every lecture.
  5. A second push to that pull request restores its own saved execution cache.

Not in this PR

  • Changing restore-jupyter-cache's default from build to execution. It is a separate decision, best taken once lecture-dp and the canary have run on execution for a while. It would need a ⚠️ marker, and the full _build save's future goes with it.
  • Moving lecture-dp and the canary to execution, a one-line edit each, after the release. The canary's is the organiser's at release time.
  • The execution cache's fallback crossing environment-update, which it shares with the build cache. A stricter rule for both would mean the templates' restore steps passing environment-update whenever cache.yml does.

Closes #270.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WT8bMZiq7Bm5J79q1N3EWq

mmcky and others added 4 commits November 7, 2026 17:05
…ge (#270)

The execution cache's key is to hash the environment files, with the
build cache's fallbacks, so the jobs that restore it now pass a salted
harness/environment.yml, and expect
jupyter-cache-{env hash}--{md hash}-{run id}.

unit-exec-seed asserts a genuine miss, which the bare jupyter-cache-
fallback used to rule out. A new job, unit-exec-env-miss, restores the
seed's lectures byte for byte under another environment file and
asserts a miss: the key used to hash the lectures alone, and restored
the seed's own cache. Its control restores after a lecture edit with the
seed's environment, and must fall back to the seed's cache, as nearly
every pull request does. bjc-restore-exec checks that
build-jupyter-cache saves under the key the restore looks up. The
header's second constraint now says why every generated-key restore
passes a salted environment.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WT8bMZiq7Bm5J79q1N3EWq
…'s key hashes the environment (#270)

The execution cache's key hashed only the lectures, and a restore fell
back to any execution cache. .jupyter_cache revalidates each notebook
against its code, but not against the packages that executed it, so a
pull request that changed environment.yml restored outputs made with
the old packages, re-executed nothing, and passed. The build cache's
key has never crossed an environment change.

build-jupyter-cache now saves the execution cache as
jupyter-cache-{env hash}-{update hash}-{md hash}-{run id}, from the
same step as the build cache's key, and logs both. restore-jupyter-cache
looks it up with the build cache's fallbacks after the lectures' own
prefix: jupyter-cache-{env}-{update}-, then jupyter-cache-{env}-. So
both types miss on the same changes, and environment and
environment-update apply to both. The status report's "normal for"
list loses "After lecture content changes (execution cache)", which a
lecture change never caused, since it falls back.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WT8bMZiq7Bm5J79q1N3EWq
…270)

A restored build cache brings back what the last cache build made,
including what the source has deleted since. Step 1 (#275) removes the
restored html, but _build/jupyter and _build/latex stay, and a build
that makes the notebooks or the PDF over them copies a removed
lecture's notebook, or a deleted PDF, into the site. The restored
_build saves no work beyond .jupyter_cache: a fresh checkout makes
Sphinx rewrite every page.

Both templates now restore cache-type 'execution', _build/.jupyter_cache
alone, which leaves nothing of the kind, and is about a sixth of the
download in lecture-dp. Its key now hashes the environment, so a pull
request that changes environment.yml still misses and executes every
lecture. The steps are renamed "Restore execution cache", and the
headers, prerequisites and the pdf-check hand-off say which cache.
cache.yml's header names both caches.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WT8bMZiq7Bm5J79q1N3EWq
…an environment change (#270)

The restore chapter recommends the execution cache, and says when the
build cache is still the one to restore: a build that offers the PDF
or the notebooks without building them. Its minimal and save-cache
examples restore `execution`, a new example shows the build cache, and
"In the templates" says how a repository that copied an older template
moves. The keys table and "Why the keys are what they are" give the
execution cache's new key and fallbacks, which never cross an
`environment` change; the troubleshooting entries follow.

ARCHITECTURE's "Two caches" puts the execution cache first, as the one
the templates restore, and the build cache as the default's. The
build-jupyter-cache chapter gives the new key. Getting started,
composition, publish-gh-pages and build-lectures say the templates
restore the execution cache, and the migration note drops any interim
prune of the restored _build. TESTING's restore row adds
unit-exec-env-miss; PLAN's preview-speed row drops #270. The
CHANGELOG's two entries are under Changed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WT8bMZiq7Bm5J79q1N3EWq
Copilot AI balanced review requested due to automatic review settings November 7, 2026 06:15

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note

Copilot was unable to complete this review at the selected tier due to model policy or plan restrictions.

🟡 Changes recommended

A reviewer-raised documentation nit remains unresolved, where the getting-started guide’s wording about pruning the restored _build is broader than the provided command example that targets _build/html specifically.

1 open issue
What changed in this PR

This pull request updates the QuantEcon GitHub Actions templates and caching actions so CI/publish workflows restore only the Jupyter execution cache (_build/.jupyter_cache) and ensures the execution cache key is environment-aware (includes environment + environment-update hashes). This prevents reusing notebook outputs produced under a different package set after environment changes, while avoiding stale _build artifacts being republished.

Changes:

  • Make the execution cache key include environment + update + source hashes, with environment-scoped restore fallbacks.
  • Switch templates/ci.yml and templates/publish.yml to restore cache-type: execution by default.
  • Update harness tests to assert correct miss/fallback behavior on environment vs. lecture changes; align docs/architecture/changelog with the new semantics.

Notes (nits):

  • docs/user/getting-started.md: wording suggests pruning all _build, but the example (jb clean . --html) is HTML-specific.
  • templates/cache.yml: header comment still reads like it only generates the build cache, though it now creates both caches.

Assessment: This pull request is ready to be approved.

File Review focus / summary
templates/​publish.yml Restore step updated to explicitly restore the execution cache (cache-type: execution) and adjust explanatory comments.
templates/​ci.yml Restore step updated to restore execution cache by default; comments updated to reflect env-keyed behavior and expected misses.
templates/​cache.yml Template workflow context for producing caches; header wording nit noted re: “build cache” vs. two caches.
restore-jupyter-cache/​action.yml Execution-mode key construction and restore fallbacks updated to include environment/update hashes; messaging/docs strings adjusted.
docs/​user/​getting-started.md Guidance updated to match execution-cache restore in templates; nit noted about _build vs _build/html phrasing.
docs/​user/​composition.md Documentation aligned so environment files apply to/cache-key both cache types.
docs/​user/​actions/​restore-jupyter-cache.md Expanded guidance/examples/keys table to recommend execution cache and document new key + fallback behavior.
docs/​user/​actions/​publish-gh-pages.md Updated to reflect template behavior restoring execution cache in publish workflow.
docs/​user/​actions/​build-lectures.md Updated wording to avoid implying only the build cache is involved; aligns with new template behavior.
docs/​user/​actions/​build-jupyter-cache.md Updated cache key documentation for execution cache and clarified which cache templates restore.
docs/​dev/​TESTING.md Test matrix updated to include execution-cache env-miss coverage (e.g., unit-exec-env-miss).
docs/​dev/​PLAN.md Planning note updated to reflect completion of the related work item (drops #270 reference).
docs/​dev/​ARCHITECTURE.md “Two caches” documentation revised to describe execution cache first and its updated keying/restore behavior.
CHANGELOG.md Unreleased entries added documenting execution-cache key change and template behavior update.
build-jupyter-cache/​action.yml Cache key generation consolidated; execution cache save now uses the computed env-aware key; logs updated.
.github/​workflows/​test-actions.yml Harness extended/updated to assert new execution-cache key format and correct miss/fallback behavior.

Review effort: Balanced

Comment thread docs/user/getting-started.md Resolved
…ader both caches (#270)

Getting started's migration note said to drop an interim prune of the
restored `_build`, while its example, `jb clean . --html`, prunes
`_build/html` alone; the note names `_build/html` again. cache.yml's
header still spoke of one cache in its title and its success and
failure lines; it now speaks of both. From Copilot's review of #280.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WT8bMZiq7Bm5J79q1N3EWq
@mmcky

mmcky commented Nov 7, 2026

Copy link
Copy Markdown
Contributor Author

Copilot's review summary also noted that templates/cache.yml's header still read as if it made one cache. Line 3 already named both caches, but the title and the success and failure lines still spoke of one. 168e1c4 makes them plural. The workflow's name: Build Cache is unchanged, since it is the name a copied workflow shows in each repository's Actions tab.

Claude Code (on behalf of mmcky)

@mmcky
mmcky merged commit 7fbb78f into main Nov 7, 2026
58 checks passed
@mmcky
mmcky deleted the feat/270-execution-cache-templates branch November 7, 2026 06:26
mmcky added a commit that referenced this pull request Nov 7, 2026
Brings in #280 (#270). CHANGELOG: main's ### Changed under
[Unreleased] stays first, and this branch's ### Fixed follows it.
PLAN.md: main's Preview speed row, without the #216 row.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WT8bMc6gKgTU85ZHgMKnXB
mmcky added a commit that referenced this pull request Nov 9, 2026
Brings in #280, #281, #283 and #284. CHANGELOG keeps main's [Unreleased]
entries and puts #142's in Changed; PLAN keeps main's rows and drops #142
from the Container validation row.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WT8bMZzgrBo6FK6GsstoUY
mmcky added a commit that referenced this pull request Nov 10, 2026
* release: v0.17.0

Cut [0.17.0] - 2026-11-10 under an empty [Unreleased]: setup-latex
(#283), setup-environment's install-latex on the LaTeX cache (#284),
the execution cache keyed on the environment and the templates
restoring it (#280), preview-cloudflare's deploy-url (#281), and
:latest promoted only after the smoke test (#274).

PLAN's release line: 9 actions with setup-latex, v0.17.0 the latest
release, @v0 on v0.16.0 until this release's canary and the lecture
matrix have passed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WT8bMbZoC2dpGt3sPyBjyd

* docs(plan): format the release line's v0.17.0 as code, as its other versions are

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WT8bMbZoC2dpGt3sPyBjyd

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

restore-jupyter-cache: the templates restore only the execution cache, keyed on the environment too (#160, step 2)

2 participants