Add PROJECT-OPTIMIZE-PREVIEWS.md: fast preview builds research and roadmap - #93
Merged
Conversation
…admap Design notes for making PR preview builds as fast as possible, tracked in #92. Grounded in measured step-level timings from real consumer runs: a warm lecture-dp preview spends 75% of its 2.7 min pulling the container; lecture-python.myst spends ~8.3 of its 17 min building PDF and notebook formats previews never show; the 40-minute cold builds were a silent cache-freshness failure (see #83), not inherent cost. The doc covers: measured baseline + container layer analysis (1.2GB of every pull is TeX an HTML preview never uses), target architecture per repo class, before/after time budgets, a three-phase roadmap with verified savings estimates, rejected alternatives with refutations (single-page builds, Sphinx -j, CPU migration of the GPU repo, conda cache instead of containers), and open questions. Every recommendation was adversarially verified against the code in this repo, the consumer workflows, and platform behavior. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a project-level research/design document that captures measured baseline timings and a phased roadmap for speeding up PR preview builds across QuantEcon lecture repositories, and links it from the repo README so contributors can discover it.
Changes:
- Add
PROJECT-OPTIMIZE-PREVIEWS.mddocumenting preview build timing analysis, target architecture, and a three-phase optimization plan (tracking issue #92). - Add a README documentation index entry pointing to the new project document.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
| README.md | Adds a documentation index link to the new preview-optimization project doc (with tracking issue #92). |
| PROJECT-OPTIMIZE-PREVIEWS.md | New research/design/roadmap document for optimizing PR preview build speed across repo classes. |
This was referenced Jul 22, 2026
Merged
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds the research and design document behind tracking issue #92: how to make PR preview builds as fast as possible across the lecture repos, using a mix of caching, container, and workflow strategies. Also adds a README pointer line. (References to #92 are intentionally non-closing — the tracking issue stays open while phases land.)
What's in the doc
Measured baseline — step-level timings from real consumer runs: a warm
lecture-dppreview spends 75% of its 2.7 min pulling the container (the build itself is 22s);lecture-python.mystspends ~8.3 of its 17 min building PDF/notebook formats previews never show; the 40-minute cold builds were a silent cache-freshness failure (#83), not inherent cost. Container layer analysis shows 1,233 MB of the 2,741 MB lean-image pull is TeXLive, unused by HTML-only previews.Target architecture — per repo class: a TeX-free
quantecon-previewimage + three cache planes (weekly anchor, cache-on-merge, PR-scoped save) for container repos; HTML-only previews + AMI-baked environment + shallow checkout for the GPU repo; instant placeholder PR comments, concurrency cancellation, and paths filters for both.Three-phase roadmap with verified savings per item — Phase 1 alone (all small, independently shippable changes) takes
lecture-python.mystfrom ~17 min to ~8–9 min and makes the 40-min cold class ~10× rarer, loud, and once-per-PR.Rejected alternatives with refutations (single-page draft builds, Sphinx
-j, dropping containers for a conda cache, migrating the GPU repo to CPU, and more) so they aren't re-litigated, plus open questions and pilot gates.Expected results
lecture-dpsmall editlecture-dpcold misslecture-python.mystPRVerification
Every recommendation was adversarially verified against the action sources in this repo, the live consumer workflows (
lecture-dp,lecture-python.myst), and platform behavior; savings estimates were corrected where verification tightened them (e.g. zstd saves ~20–35s, not the naive 45s; parallel execution gives 1.5–2.5×, not 4×).Tracking issue: #92 · Related: PLAN.md backlog (this includes its P0), QuantEcon/meta#327 (preview unification).
🤖 Generated with Claude Code