swaitsandClaude Opus 4.7
c70ab07c32
The first version cut (v0.1.0) revealed a real gap: nothing in the
rendered book identified which release the reader was on. The
version-picker chip says "version: v0.1.0" when you're on /v0.1.0/,
but it's a small UI affordance — and on /latest/ it can't say
"v0.1.0" because /latest/ is the rolling main build, not the v0.1.0
release.
Two complementary fixes, both visible without JS:
1. **Body marker.** Top of every chapter-0 (overview) page now reads
`Spec version: <token>`. The token is `latest (main)` in src/, and
gets frozen to the actual version (`v0.1.0`) when cut-version
snapshots the directory. So /latest/ overview says "latest (main)"
and /v0.1.0/ overview says "v0.1.0".
2. **Per-build page title.** scripts/build-site.sh now sets
`MDBOOK_BOOK__TITLE` for each build:
- latest → "MeshCore Protocol Specification — latest (main)"
- vX.Y.Z → "MeshCore Protocol Specification — vX.Y.Z"
The browser tab and mdBook sidebar header reflect the version.
`just cut-version` updated to run a one-line sed on the snapshot's
00-overview.md replacing the `latest (main)` marker. Defensive grep
warns if the marker isn't found (e.g., src/ was edited away from
the expected line).
versions/v0.1.0/00-overview.md regenerated by re-running
`just cut-version v0.1.0` after the marker landed in src/ — so the
v0.1.0 snapshot now self-identifies correctly.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
67 lines
2.2 KiB
Makefile
67 lines
2.2 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}}"
|
|
# Freeze the version marker in the snapshot. src/ keeps the literal
|
|
# `latest (main)` so the rolling /latest/ build stays accurate.
|
|
sed -i 's|`latest (main)`|`{{VERSION}}`|' "versions/{{VERSION}}/00-overview.md"
|
|
if ! grep -q '`{{VERSION}}`' "versions/{{VERSION}}/00-overview.md"; then
|
|
echo "warning: expected version marker not found in 00-overview.md; the" >&2
|
|
echo "snapshot still says 'latest (main)'. Check that src/00-overview.md" >&2
|
|
echo "contains the marker line ('**Spec version:** \`latest (main)\`')." >&2
|
|
fi
|
|
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}}"
|