feat(mdbook): switch versioning from git tags to versions/ directories
Replace the git-tag-based snapshot model with frozen-directory
snapshots. Each released spec version is its own subtree under
./versions/vX.Y.Z/ — a literal copy of ./src/ taken at release time.
Why: tagging the whole repo conflated *spec content* with *site
infrastructure* (book.toml, theme, picker JS, workflow, build
scripts). Improving any of those required cherry-picking the change
back to every old tag. With directory snapshots, content is frozen
but every deploy renders every version with TODAY's infrastructure
— site fixes propagate everywhere for free.
Changes:
- scripts/build-site.sh now iterates ./versions/v* directories
instead of `git tag --list 'v*'`. Each per-version build sets
MDBOOK_BOOK__SRC to the snapshot dir and MDBOOK_OUTPUT__HTML__SITE_URL
to /meshcore-spec/<version>/. The root book.toml, theme, and
picker JS apply uniformly.
- justfile gains `cut-version vX.Y.Z` — validates the name, refuses
to overwrite, runs `cp -R src versions/<version>`, prints next-
step hints. Cutting a release is now `just cut-version v0.1.0`,
then a commit; optionally tag the commit for provenance, but
tags no longer drive CI.
- .github/workflows/mdbook.yml drops the `tags: ['v*']` trigger
and `fetch-depth: 0` (no longer iterating git history). Triggers
on push to main and PRs.
- src/00-overview.md: "Spec Versions" section rewritten to describe
the directory-snapshot model and the deliberate content-vs-
infrastructure split.
Smoke-tested locally: `just build-site` with no versions/ produces
`_site/{latest/, versions.json=["latest"], index.html}`.
`just cut-version v0.0.1` + rebuild produces both `latest/` and
`v0.0.1/`, versions.json=`["latest","v0.0.1"]`.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
4 files changed
+69
-40
No files matched your search
+10
-2
@@ -42,8 +42,16 @@ The published site preserves prior spec versions alongside the rolling
|
||||
- `https://swaits.github.io/meshcore-spec/latest/` — built from the tip of
|
||||
`main`. May change between any two visits.
|
||||
- `https://swaits.github.io/meshcore-spec/v0.1.0/` (and likewise for any
|
||||
future `vX.Y.Z`) — a frozen snapshot built from the matching git tag.
|
||||
Suitable for citing or for certifying an implementation against.
|
||||
future `vX.Y.Z`) — a frozen content snapshot. Suitable for citing or for
|
||||
certifying an implementation against.
|
||||
|
||||
Frozen versions live as their own directory in the repo
|
||||
(`versions/vX.Y.Z/`) — a literal copy of `src/` taken at release time.
|
||||
This deliberately separates **content** (versioned, frozen) from **site
|
||||
infrastructure** (theme, picker, build pipeline; lives at the repo root
|
||||
and is unversioned). Every deploy rebuilds every published version using
|
||||
today's infrastructure, so site improvements show up everywhere without
|
||||
backporting.
|
||||
|
||||
The version-picker in the top-right of every page lists every published
|
||||
version; switching keeps you on the same chapter where it exists in the
|
||||
|
||||
Reference in new issue
Block a user