swaitsandClaude Opus 4.7
74864761fa
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>
59 lines
1.7 KiB
Makefile
59 lines
1.7 KiB
Makefile
# meshcore-spec — task runner.
|
|
#
|
|
# Every recipe runs under `mise exec sh -c …`, so mise-pinned tools
|
|
# (see mise.toml) are on PATH and we never accidentally use a system
|
|
# mdbook of the wrong version. `sh` is intentional — keep recipes
|
|
# POSIX-compatible.
|
|
|
|
set shell := ["mise", "exec", "--", "sh", "-c"]
|
|
|
|
# Show the available recipes.
|
|
_default:
|
|
@just --list
|
|
|
|
# Install / refresh tools pinned in mise.toml.
|
|
setup:
|
|
mise install
|
|
|
|
# Build the spec into ./book/ (single-version; for local dev).
|
|
build:
|
|
mdbook build
|
|
|
|
# Build the full multi-version site into ./_site/ (latest + every v* tag).
|
|
# This is exactly what CI runs.
|
|
build-site:
|
|
sh scripts/build-site.sh
|
|
|
|
# Live-preview the spec at http://localhost:3000 with auto-reload.
|
|
serve:
|
|
mdbook serve --open --port 3000
|
|
|
|
# Remove all build outputs (single-version and multi-version).
|
|
clean:
|
|
rm -rf book _site
|
|
|
|
# Run the corpus validator.
|
|
validate:
|
|
python3 tools/validate.py corpus/
|
|
|
|
# Cut a frozen spec version: copy ./src/ to ./versions/<VERSION>/.
|
|
# Usage: just cut-version v0.2.0
|
|
cut-version VERSION:
|
|
#!/usr/bin/env sh
|
|
set -eu
|
|
case "{{VERSION}}" in
|
|
v[0-9]*.[0-9]*.[0-9]*) ;;
|
|
*) echo "Version must look like vX.Y.Z (got '{{VERSION}}')" >&2; exit 1 ;;
|
|
esac
|
|
if [ -e "versions/{{VERSION}}" ]; then
|
|
echo "versions/{{VERSION}} already exists; not overwriting." >&2
|
|
exit 1
|
|
fi
|
|
mkdir -p versions
|
|
cp -R src "versions/{{VERSION}}"
|
|
echo "Snapshotted src/ -> versions/{{VERSION}}"
|
|
echo
|
|
echo "Next steps:"
|
|
echo " - git add versions/{{VERSION}} && commit (e.g. \"release {{VERSION}}\")"
|
|
echo " - optionally tag the commit: git tag {{VERSION}}"
|