Skip to content

docs: 2026.06 baseline, measured image sizes, and READMEs reconciled with the shipped code (#106, #109, #99) - #175

Merged
mmcky merged 13 commits into
mainfrom
claude/106-109-docs
Sep 23, 2026
Merged

mmcky merged 13 commits into
mainfrom
claude/106-109-docs

Conversation

@quantecon-services

@quantecon-services quantecon-services commented Sep 23, 2026 •

Copy link
Copy Markdown
Collaborator

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):

    Image Compressed (cold pull) On disk
    quantecon (full) 3.33 GB 8.60 GB
    quantecon-build (lean) 2.93 GB 7.32 GB
    • These replace the round "~8GB / ~3GB" pair at every site, and refresh the older 8.3/7.1 and 3.2/2.9 figures.
    • "~60% smaller" is deleted, and "faster pull" becomes "a modestly smaller pull": about 12% compressed, and about 15% on disk.
    • The unmeasured "pull time" and "package count" rows are removed.
    • The earlier branch run (35856865426) read 7.33 GB for the lean image. The deps: bump the conda group across 2 directories with 1 update #162 rebuild trimmed about 5 MB, which moved the second decimal, and 242981f updates all eleven sites.
  • "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) and graphviz (lean only).

  • PLAN.md:

    • The August triage table is refreshed to 2026-09-23 and gains a Release gating: a gate.yml in the canary tests the candidate before v0 moves #135 row. It already had rows for the other listed issues.
    • The consumers table shows every exact pin on @v0.11.1: eight call sites across six repos.
      • That includes lecture-python-programming.fr, which the August audit missed and which Dependabot moved from @v0.8.0 today. It was added in d1b8fb1.
      • The counts elsewhere in PLAN.md follow it (878356d).
    • Item 10 records that the size propagation is done; the trim stays open.
    • The "Last updated" line is refreshed.
  • CONTRIBUTING.md: the doc-update matrix gains a PLAN.md row.

#109 docs half and #99

  • Missing permissions: blocks. Every job example that calls a preview action now grants contents: read and pull-requests: write. That covers both preview READMEs, the root quick start, QUICK-REFERENCE (two examples), MIGRATION-GUIDE and both ARCHITECTURE workflows. The actions call issues.listComments, createComment and updateComment with github.token.
  • actions/checkout: all 29 @v4 and 2 @v5 references move to @v7. In build-jupyter-cache/README.md and publish-gh-pages/README.md, which fix(actions): #107 correctness batch and #109 code items #173 also edits, only the checkout lines change.
  • QUICK-REFERENCE:
    • The fictional alias: recipe becomes a one-line "Preview URL" note: the alias is fixed at pr-{number}, and the URL comes from deploy-url.
    • The setup-environment cache key and path now match action.yml.
    • The invented log block is replaced with lines the actions actually print.
    • docs: QUICK-REFERENCE "Pages 404?" snippet recommends the wrong permissions #99: the "Pages 404?" snippet now lists contents: read, pages: write and id-token: write, with contents: write needed only for create-release-assets.
  • MIGRATION-GUIDE:
    • The collab.yml snippet uses real inputs: restore-jupyter-cache@v0, then build-lectures with builder: 'html' and source-dir: 'lectures'.
    • The claim that LaTeX is cached is gone.
    • The cname line now points to Settings → Pages.
    • docs: QUICK-REFERENCE "Pages 404?" snippet recommends the wrong permissions #99's second item: the build-jupyter-cache key reads build-{env-hash}-{update-hash}-{run-id}, here and in ARCHITECTURE.
  • build-lectures/README.md: setup-latex becomes setup-environment with install-latex: 'true', and the failure-artifact-name row is added.
  • "Never saves" becomes "read-only by default, with an optional PR-scoped save-cache" in README.md and ARCHITECTURE.
  • setup-environment/README.md: the cache key and path now match action.yml:133-134.
  • templates/publish.yml (comments only):
    • The release-asset block lists the three things it needs: a tag trigger, contents: write, and allowing the tag under the github-pages environment's deployment rules.
    • The cname mentions point to Settings → Pages.
    • templates/README.md is updated to match.
  • New templates/latex-requirements.txt: the 11 TeX packages and build tools both images share, for standard-runner pdflatex builds. It includes make, because jupyter-book's pdflatex builder runs make all-pdf. It is linked from templates/cache.yml and templates/README.md.
  • Small fixes:
  • Release instructions: README defers to CONTRIBUTING. CONTRIBUTING's "Creating a Release" gains the staged-release procedure from decision 4 on Tracking: July 2026 maintenance audit (83 verified findings) #110, with its known limits.
  • CHANGELOG.md: one documentation entry.

Validation

Merge notes

Closes the docs half of #106 and #109, and #99. Tracking: #110.

🤖 Generated with Claude Code

https://claude.ai/code/session_01DwQrz9VbFrbAD7uh2LTgzh

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

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.

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 Low severity

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, bumps checkout to @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 in CONTRIBUTING.md, refreshes PLAN.md, and records the sweep in CHANGELOG.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.

Comment thread templates/latex-requirements.txt Resolved
claude and others added 6 commits September 23, 2026 21:44
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
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>
@mmcky

mmcky commented Sep 23, 2026

Copy link
Copy Markdown
Contributor

Answering the open point: yes, add lecture-python-programming.fr. It pins preview-netlify (ci.yml) and publish-gh-pages with create-release-assets (publish.yml) at @v0.11.1, and Dependabot moved both from @v0.8.0 today, so it was not in the August audit's count.

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

Copy link
Copy Markdown
Collaborator Author

Thanks. d1b8fb1 checks out. Follow-up in 878356d: two other counts in PLAN.md still predated the .fr row, and now match it.

  • The "Last updated" line said "all six exact pins". It now reads eight pins across six repos.
  • The lecture-progress note had publish-gh-pages at 7/7 with five on exact pins. It is now 8/8 with six on exact pins.

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
@mmcky
mmcky merged commit 0e514bf into main Sep 23, 2026
17 checks passed
@mmcky
mmcky deleted the claude/106-109-docs branch September 23, 2026 23:13
mmcky added a commit that referenced this pull request Sep 24, 2026
…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>
@mmcky mmcky mentioned this pull request Sep 24, 2026
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.

4 participants