Repository navigation
docs: 2026.06 baseline, measured image sizes, and READMEs reconciled with the shipped code (#106, #109, #99) - #175
Conversation
Both images ship anaconda=2026.06 (containers/quantecon/environment.yml:11; the lean image carries the matching pin set), but seven sites still said 2025.12. They now say 2026.06. Image sizes were a mix of round "~8GB / ~3GB" figures, a "~60% smaller" claim, and an older measured pair. Every size site now carries the pair the fixed size job (#172) produced on 2026-09-23, run 35856865426 (Docker 28.0.4, overlay2, ubuntu-latest), and says which metric it is: - quantecon (full): 3.33 GB compressed (what a cold pull downloads), 8.60 GB on disk - quantecon-build (lean): 2.93 GB compressed, 7.33 GB on disk The lean image is about 12% smaller to pull and 15% smaller on disk, so the "faster CI pulls" / "fast image pulls" wording becomes "a modestly smaller pull", and the lean README's unmeasured pull-time and package-count rows go. "Minimal TexLive" was false. The two Dockerfiles' apt lists differ in exactly two packages: the lean image drops texlive-luatex and adds graphviz; texlive-latex-extra and texlive-fonts-extra are in both. The docs now say so, and name what actually distinguishes the lean image: no anaconda metapackage, an explicit package list pinned to the 2026.06 baseline. The full image's "Complete TexLive installation" is corrected to match. CHANGELOG history and PLAN.md:68's narration of the old date-pin keep their 2025.12 mentions on purpose. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DwQrz9VbFrbAD7uh2LTgzh
…109, #99) The docs half of #109, with #99 folded in. The code items (the build-jupyter-cache latex-requirements-file passthrough, the cname warning and the template pin-drift check) ride with #107's PR. Examples that failed for adopters: - permissions: the preview-netlify and preview-cloudflare "Complete Workflow Example" blocks declared none, and the root README and QUICK-REFERENCE container quick starts declared contents/packages only. Both preview actions list, create and update PR comments through github.rest.issues.* with github.token, so each block now grants contents: read and pull-requests: write. - actions/checkout: the remaining 29 @v4 and 2 @v5 references across 13 docs move to @v7, matching the templates (#168) and this repo's workflows. with: fetch-depth lines are kept. Documented behaviour that does not exist: - QUICK-REFERENCE: the "Preview with Custom URL" recipe passed an alias input preview-netlify does not accept (the alias is fixed at pr-N); it becomes a short "Preview URL" note. The setup-environment key row now carries the environment-name and python-version segments and the cached path. The sample log block's "LaTeX cache hit" line (no LaTeX caching exists) and its other invented lines are replaced by strings the actions actually print. The "Pages 404?" snippet recommended contents: write, which as a permissions block would also drop pages and id-token; it now lists pages: write and id-token: write, with contents: write only for create-release-assets (#99). - MIGRATION-GUIDE: the collab.yml snippet passed build-html and cache-workflow, which build-lectures never accepted; it now restores the cache with restore-jupyter-cache and builds with builder/source-dir. The copied commit message no longer claims LaTeX caching, and the build-jupyter-cache key carries its update-hash segment here and in ARCHITECTURE (#99). - build-lectures README: "use setup-latex" pointed at a removed action; the inputs table gains the missing failure-artifact-name row. - README and ARCHITECTURE said restore-jupyter-cache "never saves"; it is read-only by default with an optional PR-scoped save-cache. - setup-environment README: the cache key and path now match action.yml. Templates and the custom domain: - The Actions Pages deploy ignores a CNAME file, so the cname input has no effect. templates/publish.yml, templates/README.md, MIGRATION-GUIDE and QUICK-REFERENCE now point at Settings -> Pages instead of offering cname. - templates/publish.yml's release-asset block now says it needs a tag trigger (the file runs on pushes to main and manual dispatch) and contents: write (the job grants contents: read). - New templates/latex-requirements.txt: the TeX packages the two images share, in the whole-line-comment format setup-environment parses. The cache.yml standard-runner comment and templates/README point at it, since a standard-runner pdflatex build fails without the file. - cache.yml and templates/README describe the _build artifact as failure-only, which it has been since v0.8.0. Smaller items: the lean image README's last @main example moves to @v0; the full image README's theme version reads 0.21.0, the environment.yml pin. README's Contributing section now points at CONTRIBUTING.md, which tests by branch and moves v0; CONTRIBUTING gains the staged-release procedure decided on #110 (decision 4), its known limits and the rollback. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DwQrz9VbFrbAD7uh2LTgzh
…109) PLAN.md: - The consumers table said five lecture repos were pinned to v0.8.0 or v0.9.0. Dependabot bumped all six exact call sites to v0.11.1 between 2026-08-12 and 2026-08-24 (#110's 2026-09-23 revalidation; the pins are confirmed by code search). The rows, the "Corrected" note and the lecture-jax rollout row now say so; the section keeps its structure. - The August triage table already had rows for the issues #106 lists, except #135. Each row is refreshed to its state on 2026-09-23 (all are open; the open PRs #144, #170, #171 and #172 and the in-progress #105 and #107 work are named), and #135 gets a row. No rows are duplicated. - Item 10's "propagate corrected container-size figures" half is marked done by this sweep; the trim itself stays open as its own PR (decision 1 on #110). - The "Last updated" line records this pass. CONTRIBUTING.md: the doc-update matrix gains a PLAN.md row, so a backlog item or consumer ref that moves updates the plan rather than waiting for the next audit. CHANGELOG.md: one [Unreleased] Documentation entry for the sweep. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DwQrz9VbFrbAD7uh2LTgzh
- templates/latex-requirements.txt: describe the file format so it holds under both the current parse (grep -v '^#') and #173's, where '#' starts a comment anywhere. Drop the claim that an inline '#' reaches apt-get. - templates/publish.yml: the release-asset note lists a third change, the tag pattern under the github-pages environment's deployment branches and tags, which otherwise reject a tag-triggered run. - CONTRIBUTING.md: the staged-release limits say that steps 2-3 run neither publish-gh-pages (the canary's publish.yml fires only on a publish* tag) nor setup-environment at the candidate ref, replacing the narrower release-asset bullet. - PLAN.md: #172 is marked open with the run the sizes come from; #144 needs a rebase before review. - CHANGELOG.md: the 2026.06 baseline is the full image's metapackage and the lean image's pin set, not something both images ship. - containers/README.md: the lean image carries the pinned science stack, so "Jupyter Book build tools only" loses "only". Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DwQrz9VbFrbAD7uh2LTgzh
- Four more job examples call preview-netlify without a permissions block (MIGRATION-GUIDE's preview job, QUICK-REFERENCE's standard CI workflow, both ARCHITECTURE workflows). Each now grants contents: read and pull-requests: write (plus packages: read where it pulls the image), so the CHANGELOG line saying preview examples grant pull-requests: write is true of every one. - README's publish-gh-pages feature line no longer lists custom-domain support first; custom domains are set in Settings -> Pages. - MIGRATION-GUIDE's sample commit message says "conda environment caching": there is no separate pip cache. - PLAN.md's #105 and #107 rows cite the now-open #174 (draft) and #173. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DwQrz9VbFrbAD7uh2LTgzh
There was a problem hiding this comment.
Copilot review overview
🔵 Needs a closer look
The sweep spans 19+ files and asserts many facts that can only be confirmed by a human (externally measured image sizes and cross-repo consumer pins), and merging its containers/** edits rebuilds and pushes both :latest images.
Review effort: Balanced
Findings: 1
Open (1)
What changed in this PR
This is a documentation-only PR that reconciles the repository's docs with the shipped code, folding issues #106, #109's docs half, and #99 into a single sweep (per decision 1 on the #110 tracking issue). It updates stale factual claims across READMEs, guides, templates, and planning docs so adopters and maintainers see accurate information. I verified the code-facing claims against the actual sources: the Anaconda 2026.06 pins (containers/*/environment.yml), the measured size figures (consistent across all 19 files), the TeX Live diff (texlive-luatex full-only, graphviz lean-only), the setup-environment cache key/path (action.yml:133-134), the build-jupyter-cache key (action.yml:95), the deploy-url output, the sample log lines, and that actions/checkout@v7 matches the repo's own workflows.
Changes:
- Refreshes container facts everywhere: Anaconda
2025.12→2026.06, round~8GB/~3GB→ measured figures (full 3.33 GB compressed / 8.60 GB on disk; lean 2.93 / 7.33 GB), and corrects "minimal TexLive" to the accurate apt-list diff. - Reconciles action/template docs with shipped inputs and behavior: adds
permissions:blocks for preview examples, bumpscheckoutto@v7, removes nonexistent inputs/log lines, fixes cache-key docs and the Pages-404 permissions snippet, and points custom-domain guidance to Settings → Pages. - Adds
templates/latex-requirements.txt, documents a staged-release procedure inCONTRIBUTING.md, refreshesPLAN.md, and records the sweep inCHANGELOG.md.
| File | Description |
|---|---|
| TESTING.md | Updates first-pull size note to measured figures |
| templates/README.md | Documents latex-requirements.txt, artifact-on-failure, and Settings→Pages custom domain |
| templates/publish.yml | Clarifies cname has no effect and the release-asset prerequisites (comments only) |
| templates/latex-requirements.txt | New example LaTeX package list for standard-runner PDF builds |
| templates/cache.yml | Notes standard-runner LaTeX reads latex-requirements.txt and fails if missing |
| setup-environment/README.md | Corrects size table, checkout ref, and cache key/path to match action.yml |
| README.md | Updates feature blurbs, sizes, permissions, checkout, and defers release steps to CONTRIBUTING |
| publish-gh-pages/README.md | Bumps checkout to @v7 |
| preview-netlify/README.md | Adds pull-requests: write permission block |
| preview-cloudflare/README.md | Adds pull-requests: write permission block |
| PLAN.md | Refreshes consumers table, disposition table, item 10, and Last-updated line |
| docs/QUICK-REFERENCE.md | Fixes sizes, permissions, cache key, preview-URL note, log block, and Pages-404 snippet |
| docs/MIGRATION-GUIDE.md | Fixes collab.yml inputs, cache-key text, cname guidance, and LaTeX-cache claim |
| docs/GPU-AMI-SETUP.md | Bumps checkout to @v7 |
| docs/CONTAINER-GUIDE.md | Updates sizes and Anaconda baseline |
| docs/ARCHITECTURE.md | Updates sizes, cache key, restore-cache wording, and adds permissions |
| CONTRIBUTING.md | Adds staged-release procedure, rollback, and a PLAN.md doc-update row |
| containers/VALIDATION.md | Updates sizes and TeX Live description |
| containers/README.md | Updates sizes, baseline, and TeX Live wording |
| containers/quantecon/README.md | Updates baseline and theme version, checkout refs |
| containers/quantecon-build/README.md | Updates sizes/baseline/TeX Live, fixes @main→@v0 |
| CHANGELOG.md | Adds one Documentation entry under [Unreleased] |
| build-lectures/README.md | Adds failure-artifact-name row, fixes removed setup-latex reference |
| build-jupyter-cache/README.md | Bumps checkout refs to @v7 |
| .github/copilot-instructions.md | Updates container size/description lines |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Copilot review on #175. The header says the file lists the TeX packages and build tools both images install, but omitted make, which both Dockerfiles install under "Build tools". It is needed, not incidental: jupyter-book 1.0.4.post1's pdflatex builder runs `make all-pdf` in the LaTeX output directory (jupyter_book/cli/main.py). Hosted Ubuntu runners ship make already, so on them this is a no-op install; on a minimal runner it is the difference between a PDF and a failed build. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DwQrz9VbFrbAD7uh2LTgzh
# Conflicts: # CHANGELOG.md
Refresh the #105 disposition row now that the README warning is on main. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DwQrz9VbFrbAD7uh2LTgzh
#162 moved both images to quantecon-book-theme 0.22.0 (full pins ==0.22.0, lean >=0.22.0) after this sweep set the full image's README to 0.21.0. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DwQrz9VbFrbAD7uh2LTgzh
…106, #109) lecture-python-programming.fr exact-pins preview-netlify and publish-gh-pages (with create-release-assets) at v0.11.1, moved there from v0.8.0 by Dependabot on 2026-09-23, so it joins the consumers table and the exact-pin count becomes eight call sites across six repos. README.md and copilot-instructions.md said the current release was v0.8.0; it is v0.11.1. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
|
Answering the open point: yes, add Pushed in d1b8fb1, together with the two remaining stale facts in files this PR already edits: README.md line 9 and copilot-instructions.md line 133 both said the current release was v0.8.0; it is v0.11.1. The theme line at 0.22.0 from eaee1a6 stands. The rest of the copilot-instructions status block (the June date, "7 composite actions", the lecture-dp "Next" line) is left for the docs trim, since #176 edits the same block. Assisted-by: Claude Code (Claude Fable 5.1) |
d1b8fb1 added lecture-python-programming.fr (two exact @v0.11.1 call sites, including publish-gh-pages). Two counts elsewhere in PLAN.md still predated it: the Last-updated line said all six exact pins, and the lecture-progress note had publish-gh-pages at 7/7 with five exact. They now read eight pins across six repos, and 8/8 with six exact. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DwQrz9VbFrbAD7uh2LTgzh
|
Thanks. d1b8fb1 checks out. Follow-up in 878356d: two other counts in
The historical "Corrected 2026-08-11" narrative is left as written, since your "Added 2026-09-23" sentence brings it up to date. No other changes. Generated by Claude Code |
The first size report on main (run 35930060129, after #162 rebuilt both images with quantecon-book-theme 0.22.0) reads full 3.33 GB compressed / 8.60 GB on disk, unchanged, and lean 2.93 GB / 7.32 GB: the lean on-disk figure dropped by about 5 MB, enough to move the second decimal. The eleven sites that quoted 7.33 now say 7.32, and PLAN.md's #106 row cites that main run instead of the earlier branch dispatch. The ~15% (on disk) and ~12% (compressed) gaps still hold. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DwQrz9VbFrbAD7uh2LTgzh
…4xxo7v Resolves the two conflicts with main after #173 and #175 landed: the copilot-instructions status block keeps main's refreshed release and container lines with this branch's "8 composite actions" line, and the CHANGELOG's [Unreleased] Added section carries both sets of entries. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

This is one docs PR for #106 and #109's docs half, with #99 folded in, as decision 1 on #110 set out. The QUICK-REFERENCE trim (PLAN item 10) is not part of it: the four QUICK-REFERENCE items are fixed where they are, and the trim stays a separate, later PR.
#106
Anaconda baseline, 2025.12 → 2026.06, at all seven sites. The lean image is described as an explicit package list pinned to that baseline, not as shipping the metapackage.
Measured image sizes everywhere, each labelled with its metric. The figures come from the size job fixed in fix(ci): make the image-size job report both sizes, and fail when it cannot #172, from the first report on
main(run 35930060129, after deps: bump the conda group across 2 directories with 1 update #162's rebuild; Docker 28.0.4 overlay2):quantecon(full)quantecon-build(lean)"Minimal TexLive" corrected in all four files, along with the matching "Complete TexLive" claim for the full image. I re-diffed the apt lists: each image installs 30 packages, and the only differences are
texlive-luatex(full only) andgraphviz(lean only).PLAN.md:@v0.11.1: eight call sites across six repos.lecture-python-programming.fr, which the August audit missed and which Dependabot moved from@v0.8.0today. It was added in d1b8fb1.CONTRIBUTING.md: the doc-update matrix gains aPLAN.mdrow.#109 docs half and #99
permissions:blocks. Every job example that calls a preview action now grantscontents: readandpull-requests: write. That covers both preview READMEs, the root quick start, QUICK-REFERENCE (two examples), MIGRATION-GUIDE and both ARCHITECTURE workflows. The actions callissues.listComments,createCommentandupdateCommentwithgithub.token.actions/checkout: all 29@v4and 2@v5references move to@v7. Inbuild-jupyter-cache/README.mdandpublish-gh-pages/README.md, which fix(actions): #107 correctness batch and #109 code items #173 also edits, only the checkout lines change.alias:recipe becomes a one-line "Preview URL" note: the alias is fixed atpr-{number}, and the URL comes fromdeploy-url.setup-environmentcache key and path now matchaction.yml.contents: read,pages: writeandid-token: write, withcontents: writeneeded only forcreate-release-assets.collab.ymlsnippet uses real inputs:restore-jupyter-cache@v0, thenbuild-lectureswithbuilder: 'html'andsource-dir: 'lectures'.cnameline now points to Settings → Pages.build-jupyter-cachekey readsbuild-{env-hash}-{update-hash}-{run-id}, here and in ARCHITECTURE.build-lectures/README.md:setup-latexbecomessetup-environmentwithinstall-latex: 'true', and thefailure-artifact-namerow is added.save-cache" inREADME.mdand ARCHITECTURE.setup-environment/README.md: the cache key and path now matchaction.yml:133-134.templates/publish.yml(comments only):contents: write, and allowing the tag under thegithub-pagesenvironment's deployment rules.cnamementions point to Settings → Pages.templates/README.mdis updated to match.templates/latex-requirements.txt: the 11 TeX packages and build tools both images share, for standard-runner pdflatex builds. It includesmake, because jupyter-book's pdflatex builder runsmake all-pdf. It is linked fromtemplates/cache.ymlandtemplates/README.md.@main→@v0in the lean README.README.mdandcopilot-instructions.md(d1b8fb1).CHANGELOG.md: one documentation entry.Validation
2025.12(outside the deliberatePLAN.md:68narration),~8GB/~3GB, "60% smaller", or7.33;checkout@v4/@v5,setup-latex, "never saves", or "LaTeX cache".templates/*.ymlparse.setup-environment's own parse, on bothmain's version and fix(actions): #107 correctness batch and #109 code items #173's, yields exactly the 11 packages fromtemplates/latex-requirements.txt.main's parser, which fix(actions): #107 correctness batch and #109 code items #173 changes. It now uses only whole-line comments, which are true under both parsers.pull-requests: write; the count turned out to be four, and all are fixed.makewas missing from the example requirements list. It is fixed in 919e617, and the thread is answered and resolved.mainthrough docs(preview-*): warn against pull_request_target instead of recommending it (#105) #170, fix(ci): make the image-size job report both sizes, and fail when it cannot #172, ci: bump the github-actions group across 1 directory with 2 updates #167, test(containers): exercise the real theme and FreeFont path in the smoke fixture (#108) #171 and deps: bump the conda group across 2 directories with 1 update #162:Merge notes
containers/**READMEs andVALIDATION.md, so merging rebuilds and pushes both:latestimages (build-containers.yml:3-8). Nothing that goes into the images changes.maincan leaveCHANGELOG.md[Unreleased]conflicting here, and feat: deploy-cloudflare — publish private sites to a Worker behind Access, and prove they are gated (#163) #176 overlaps several of the same docs. I'll mergemainin and resolve as PRs land.copilot-instructions.mdstatus block, meaning the June date, "7 composite actions" and the lecture-dp "Next" line. Also left:TESTING.md:186's "~10-20 sec" repeat-pull claim.Closes the docs half of #106 and #109, and #99. Tracking: #110.
🤖 Generated with Claude Code
https://claude.ai/code/session_01DwQrz9VbFrbAD7uh2LTgzh