Add repoint rule 3: publish before deleting, because the site lags main - #44
Merged
Conversation
There was a problem hiding this comment.
Pull request overview
Updates the repository’s repointing guidance to capture a newly observed ordering failure mode: lecture sites that publish from tags can lag main, creating reader-facing 404 windows even when repos/CI are green.
Changes:
- Expands
PLAN.md“Repoint rules” from three to four rules; adds a new Rule 3 (“repoint, publish, then delete”) and sharpens Rule 2 with a concrete observed failure case. - Updates
AGENTS.mdto reflect the additional ordering trap and to document the “publish before deleting” constraint for tag-published lecture sites.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| PLAN.md | Adds the new repoint ordering rule about publish lag and refines rule-2 guidance with an observed incident. |
| AGENTS.md | Updates the “repointing traps” section to include the publish-lag ordering constraint alongside existing repoint sequencing rules. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
…eleting Rules 1 and 2 protect the repositories. Neither protects the PUBLISHED SITE, and that gap is where the first real reader-facing breakage happened. lecture-python-intro publishes on a `publish*` tag, not on push to main. So merging a repoint does not refresh the live site -- the already-published notebooks keep the old URL, and if the same PR deleted the file, that URL 404s. Set 1 demonstrated it: after lecture-python-intro#823 merged, the notebook served at intro.quantecon.org still carried the deleted mpd2020.xlsx path, and stayed broken until a publish was tagged. What makes it nasty is that nothing reports it. The rendered HTML is fine -- figures are baked at build time, so the pages look correct -- and neither repo's CI exercises a published notebook. The breakage lands only on readers who download or open the lecture in Colab, which for a computational series is the audience that matters most. So a repoint set is two phases: repoint the URLs keeping the files, publish, then delete in a follow-up. Costs one extra PR per set; leaves no window. Publish triggers differ per repo and the table says which need the split -- lecture-wasm publishes on push to main and self-heals, and deleting a mirror-orphan nothing reads never needs it. Rule 2 is also sharpened. It was written as a constraint on the tracker flip, but 2026-08-06 showed it binds the lecture PRs equally: lecture-wasm#53 merged ahead of lecture-python-intro#824 and left main failing on both files until the second landed. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Three valid comments, all documentation defects introduced by the rule-3 commit. AGENTS.md said "three ordering traps" above a list of four bullets. Adding rule 3 pushed the count without updating the header. PLAN.md already had this right -- rules 1-3 are ordering, rule 4 is scope, numbered separately -- so AGENTS.md now matches that split rather than merely correcting the numeral: the scope rule gets its own subheading, because it is a different kind of rule and burying it in an ordering list was the actual mistake. "mirror-orphan" appeared in both files and was defined in neither. It now reads as what it is -- a copy no lecture reads in either repo, typically one a repo committed alongside its mirrored sources while the lecture fetches the other repo's copy by URL -- with the term kept parenthetically for anyone who has met it in the audit output. Checking that turned up slightly more than the comments flagged: plain "orphan" is not defined in AGENTS.md either, so a reader previously hit two undefined terms in one sentence. The rewrite removes the dependency on both. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
mmcky
force-pushed
the
rules/publish-lag
branch
from
August 6, 2026 07:46
51f53cf to
805f263
Compare
38 tasks
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.
Records the ordering constraint that produced this migration's first reader-facing breakage, and sharpens rule 2 with what today demonstrated.
Rule 3 — the published site lags
mainRules 1 and 2 protect the repositories. Neither protects the published site.
lecture-python-intropublishes on apublish*tag, not on push tomain. Merging a repoint therefore does not refresh the live site: the already-published notebooks keep the old URL, and if the same PR deleted the file, that URL 404s.Set 1 proved it rather than predicted it. After QuantEcon/lecture-python-intro#823 merged, the notebook served at
intro.quantecon.orgstill carried…/lecture-python-intro/raw/main/lectures/datasets/mpd2020.xlsx— verified returning 404 — and stayed that way until a publish was tagged. Last publish before that had been 2026-07-17, twenty days earlier, so the window was not short.What makes it nasty is that nothing reports it. The rendered HTML is unaffected, because figures are baked at build time — the pages look perfectly correct. Neither repo's CI exercises a published notebook. The damage lands only on readers who download the lecture or open it in Colab, which for a computational series is the audience that matters most.
So a repoint set becomes two phases: repoint the URLs keeping the files → publish → delete in a follow-up PR. One extra PR per set, and no window at any point.
Publish triggers differ per repo, so the rule includes a table rather than a blanket instruction.
lecture-wasmpublishes on push tomainand self-heals; deleting a mirror-orphan nothing reads never needs the split either.Rule 2, sharpened
It was written as a constraint on the tracker flip. Today showed it binds the lecture PRs equally: QuantEcon/lecture-wasm#53 merged ahead of QuantEcon/lecture-python-intro#824, partially repointing both datasets and leaving
mainfailing on each until the second lands.Documentation only — no data, manifests or scripts touched.
Part of #8. Set 2's QuantEcon/lecture-python-intro#824 is already restructured to phase 1 under this rule.