docs: close out PLAN.md, moving its lasting guidance to CONTRIBUTING - #230
Conversation
The plan is finished, so rewriting its gap table row by row would only polish a finished document. It gets a closing note instead and keeps its detail as the planning record it is; the file stays, because issues link to its lines. Three things in it are guidance rather than plan, and had no other home: - the architecture constraint -- the theme is a Remix server over pre-built page JSON and never sees the source repository, so anything derived from it must arrive as data from a plugin, from mystmd itself or from CI. That is why a feature can look impossible here; - upstream first: check jupyter-book/myst-theme before building anything custom, then build here rather than wait, recording candidates in UPSTREAM-CANDIDATES.yml; - how the visual gate and the PR previews work, including that the preview's static `myst build --html` exercises the export path the Playwright suite never reaches, and that its `myst init` step doubles as a migration-readiness check. All three are now sections of CONTRIBUTING.md, beside the material they belong with. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UZLpDVYu1YBZHQfwkRRJj7
|
🎭 Visual regression results
Details
Skipped testsmobile-chrome › theme.spec.ts › QuantEcon theme — visual regression › without JavaScript › drawer-opens-without-javascript |
There was a problem hiding this comment.
🟡 Changes recommended
The CHANGELOG entry links only to the issue rather than the PR required by CONTRIBUTING.md, plus a minor em-dash inconsistency in CONTRIBUTING.md.
Get a fresh assessment by requesting another Copilot review.
Pull request overview
This documentation-only PR closes out PLAN.md (the book-theme parity planning document) now that the #147 cutover gate is complete. Rather than rewriting the finished plan, it adds a closing note marking the file as a no-longer-maintained snapshot, and relocates the three pieces of still-useful guidance out of PLAN.md into CONTRIBUTING.md so they live beside the material they belong with. It is the last item on the #147 gate and is intended to merge after the docs review (#229).
Changes:
- Add a "Closed" note at the top of
PLAN.mdpointing readers todocs/, issue #147, and the moved guidance, while leaving the rest of the file untouched. - Add three sections to
CONTRIBUTING.md: the architecture constraint (theme never sees the source repo), upstream-first guidance, and the CI visual-tests/PR-previews description; also reclassifyPLAN.mdin the code-comments prose-docs list. - Record the change in the
## [Unreleased]section ofCHANGELOG.md.
File summaries
| File | Description |
|---|---|
| PLAN.md | Adds a closing note flagging the plan as a complete, unmaintained snapshot and redirecting to current docs/records; rest unchanged. |
| CONTRIBUTING.md | Adds Architecture, Upstream-first, and CI/PR-previews sections; moves PLAN.md to a trailing clause in the prose-docs list. |
| CHANGELOG.md | Adds an Unreleased Changed entry describing the PLAN.md close-out and the moved guidance. |
Review details
- Files reviewed: 3/3 changed files
- Comments generated: 2
- Review effort level: Balanced
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Eight PRs landed `[Unreleased]` entries while this was open. This branch adds a `### Changed` entry, so it folds into the Changed section main already had (the breaking launch change) rather than opening a second one, and it gains its PR link beside the issue link. Nothing else conflicted: main has not touched `CONTRIBUTING.md` or `PLAN.md` since this branch forked. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The clause added beside the prose-documentation list used a double hyphen where the surrounding prose uses em dashes -- including the sentence it continues, and the one above it. The `--` form belongs to this repo's code comments; CONTRIBUTING.md is prose. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Closes #218. Documentation only. This is the last item on the #147 gate, and it should merge last.
Moved out first
Three things in
PLAN.mdare guidance rather than plan, and had no other home. Each is now a section ofCONTRIBUTING.md, placed beside the material it belongs with:jupyter-book/myst-themebefore building anything custom, then build here rather than wait, recording candidates inUPSTREAM-CANDIDATES.yml(ported, not cherry-picked — this repo is not a fork)preview.ymlbuildslecture-python-programmingwith the PR's theme through a staticmyst build --html, deploys underpr-preview/pr-<n>/, and itsmyst initstep doubles as a migration-readiness checkI kept the reason each one matters, not just the fact: the architecture section ends by saying that when a feature looks impossible in the theme, this is usually why; the previews section says the static export is the path Playwright's live
myst startnever exercises, which is what makes the preview worth having.The closing note
PLAN.mdopens with a note saying the plan is complete as of the release that closes #147, that everything below is the planning snapshot it was written as and is no longer maintained — the gap table especially — and where to look instead:docs/for current behaviour, #147 and the 2026-09-11 validation study for the item-level record. It also says where the moved guidance went, and that the file is kept because issues link to its lines.The rest of
PLAN.mdis untouched — the diff is the 19 added lines and nothing else.The "no file outside CHANGELOG.md" criterion
I grepped for every remaining
PLAN.mdreference:CHANGELOG.md— four references, all historical entries. Explicitly exempted by the criterion.CONTRIBUTING.md— the code-comments rule still forbidsPLAN.mditems as comment labels, which stays correct; and its list of prose docs that keep their history now saysPLAN.mdis a closed planning record rather than a live one.docs/index.md:45— this said the parity work is tracked inPLAN.md, and the issue assigned that line to the docs review. docs: correct the user docs against what the theme actually does #229 has since merged and removed it, so the criterion is now satisfied. Re-checked against main: the only remaining references are the four historicalCHANGELOG.mdentries the criterion exempts, and two inCONTRIBUTING.md— the code-comments rule forbiddingPLAN.mditems as comment labels, which stays correct, and the prose-docs list, which this PR rewrites to callPLAN.mda closed record.Merged with main
Eight PRs landed
[Unreleased]entries while this was open. This branch adds a### Changedentry, so it folds into the Changed section main already had (the breaking launch change) rather than opening a second one, leaving the section ordered Added ×5, Changed ×2, Fixed ×3. Merged atea6ea3bdd; nothing butCHANGELOG.mdconflicted, since main has not touchedCONTRIBUTING.mdorPLAN.mdsince this branch forked.Review
Copilot raised two comments, both valid and both applied.
CONTRIBUTING.md:203). Correct, and inconsistent inside its own paragraph — the sentence it continues reads "in code — including the comments in YAML, shell and fixture files". The--form is this repo's convention for code comments;CONTRIBUTING.mdis prose. Fixed in74b8125b9.ea6ea3bdd). Its line citation (CONTRIBUTING.md:289-291) is accurate for this branch — on main that text sits at line 227, and this PR inserts about sixty lines above it. Its broader claim that every entry in the file carries apull/NNNlink is not accurate (ten entries carry only an issue link, across five released versions), which the reply records; the cited[2.7.0]section is the part where the practice is uniform.Two claims of my own were also checked rather than assumed: the closing note does not overstate the gate's status — it says "complete as of the release that closes #147", a forward reference, since that release has not been cut — and the rest of
PLAN.mdis genuinely untouched.Note on the version
The closing note deliberately says "the release that closes #147" rather than naming a version: that release has not been cut. If you'd rather it named the version, that is a one-line edit at release-prep time — same for #229's outstanding README
vX.Y.ZURLs.🤖 Generated with Claude Code
https://claude.ai/code/session_01UZLpDVYu1YBZHQfwkRRJj7
Generated by Claude Code