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:
swaitsandClaude Opus 4.7 committed 2026-05-12 10:03:46 -06:00
1 parent da00e46570
commit 74864761fa
4 files changed
+69 -40

No files matched your search

+10 -2
View File
@@ -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