docs: Phase 0 — modernise the theme release & distribution setup#54
Merged
Conversation
Reframe Phase 0 from "deploy hygiene" to modernising the theme's release and distribution setup, based on how the theme is actually consumed (a direct GitHub zip URL in each lecture's myst.yml). - Decision: collapse the two-repo source/build split into a single repo distributing versioned GitHub Release zips, with rationale from upstream (jupyter-book/myst-theme is a monorepo + named registry — neither applies here — and is itself moving to release-zip assets per myst-enhancement-proposals#34). - Target architecture: rename to quantecon-theme.mystmd (matching the org's project.tool suffix style, e.g. QuantEcon.py/.jl, Bookshelf.theme); vX.Y.Z tag + GitHub Release + theme zip per version; lectures pin a direct zip URL. Caveat captured: no template registry / myst-cli resolution needed — direct GitHub links only. - Task groups: repo consolidation & rename, release pipeline (adapted from upstream theme-assets.yml), versioning & changelog (folds in the tagging task that resolves the CHANGELOG footer-link issue), cut 1.2.0 as the first release on the new flow, and carried-over hygiene. - Records open decisions (Changesets vs manual, pinned vs rolling consumer URL, 1.2.0 sequencing) and updated Effort/Risk/Deps. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Replace the vague "~no lecture references the theme" note with the concrete finding from an org-wide search: the theme has exactly one current consumer, lecture-wasm. - Add a "Consumer migration" checklist: repoint lecture-wasm's site.template to the new pinned release URL, with explicit ordering (pipeline -> publish v1.2.0 -> repoint consumer -> archive old build repo) so the live consumer never breaks. - Note the flagship lecture repos are still on the Sphinx quantecon-book-theme and get repointed per-repo as they cut over to MyST/JB>=2, not in this phase. - Note workflow-backups only carries a repo-name glob (no action). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Convert the Phase 0 "open decisions" into resolved ones now that they are agreed: - Versioning: drop Changesets, use a manual Keep a Changelog + git tags (single non-npm artifact + small team; matches other QuantEcon repos). Documenting the bump -> changelog -> tag flow in CONTRIBUTING.md is a task under "Versioning & changelog". - Consumer URL: pinned per-lecture tag URLs. - 1.2.0: quick `make deploy` now to unstick v1.1.1, then re-release via the new pipeline. - Execution split: maintainer renames/archives the repos; tags and GitHub Releases via gh; all code/workflow/docs as PRs first. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
Updates PLAN.md Phase 0 to shift from “deploy hygiene” into a concrete, decision-backed plan for modernizing the theme’s release/distribution approach (single-repo, tag-triggered GitHub Release zip assets, and a safe consumer migration path).
Changes:
- Rewrites Phase 0 into an explicit target architecture for releases (tag + GitHub Release + attached zip) and repo consolidation/rename steps.
- Documents versioning/release decisions (manual changelog + tags; drop Changesets) and outlines a staged migration plan for the sole current consumer.
- Carries forward existing maintenance “hygiene” tasks while adding release-pipeline specifics aligned with upstream direction.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| and attaches it to the GitHub Release for that tag. Upstream's `theme-assets.yml` is a | ||
| near-verbatim reference — drop its `for THEME in book article` loop (one theme). | ||
| - [ ] Verify `myst start` resolves `site.template: <release-asset-url>` once (a release zip | ||
| is just an HTTPS zip — the same mechanism today's `heads/main.zip` uses — so low risk). |
Contributor
Author
There was a problem hiding this comment.
Fixed in 9b06a37 — now uses the full archive/refs/heads/main.zip path, matching the rest of the section.
Treat the @myst-theme 0.14 -> 1.x upgrade as a major release: it carries backwards-incompatible changes for consumers (v1.0.0's new notebook output-node AST; raised runtime requirement Node >=14 -> >=18). - CHANGELOG [Unreleased]: propose 2.0.0 with the SemVer rationale. - PLAN Phase 0: update all 1.2.0 references to 2.0.0. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Copilot consistency fixes: - Clarify the execution split: `gh` pushes the vX.Y.Z tag; the tag-triggered workflow creates the GitHub Release and uploads the zip asset. - Use the full `archive/refs/heads/main.zip` path. - "nothing points at the theme" -> "only lecture-wasm points at the theme". Refresh now-stale items (since #55-59 merged): - 2.0.0 scope now reflects @myst-theme 1.3.0 + Node 24 + consolidated dependency/security updates (all merged to main). - Mark the Dependabot triage done (consolidated via #55-58; audit 68->45). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
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.
Docs-only. Rewrites Phase 0 of
PLAN.mdfrom "deploy hygiene" into a concrete plan to modernise how the theme is released and distributed, and records the decisions agreed during review. Follows #53.What changed
jupyter-book/myst-theme→myst-templates/book-theme), which only needs it because it's a monorepo of many npm packages + themes feeding a named registry — neither applies here (one theme, consumed by a direct URL). Upstream is itself moving to release-zip assets (myst-enhancement-proposals#34).quantecon-theme.mystmd(orgproject.toolsuffix style —QuantEcon.py/.jl,Bookshelf.theme);vX.Y.Ztag + GitHub Release + theme zip per version; lectures pin a direct zip URL. No template registry /myst-cliresolution needed — direct GitHub links only.lecture-wasm. Checklist repoints it with explicit ordering (pipeline → publish v1.2.0 → repoint consumer → archive old build repo) so the live consumer never breaks. Flagship lecture repos are still on the Sphinx theme and migrate per-repo at MyST cutover.Decisions recorded
make deploynow to unstick v1.1.1, then re-release via the new pipeline.gh; code/workflow/docs as PRs first.No code or workflow changes in this PR — those land as follow-ups per the plan.
🤖 Generated with Claude Code