docs: render the current version from git tags, and deploy on every merge - #637
Open
oyvindberg wants to merge 1 commit into
Open
docs: render the current version from git tags, and deploy on every merge#637oyvindberg wants to merge 1 commit into
oyvindberg wants to merge 1 commit into
Conversation
…erge
Six pages told people to write `$version: 1.0.0-M9` in their build. That
was three releases stale, and it was stale in the way documentation
usually goes stale: nothing was wrong, so nobody looked.
The version is now derived from the newest `v*` git tag at site-build
time and substituted into a `BLEEP_LATEST_VERSION` token. Releases are
cut by pushing a tag, so the tags already are the release history and
there is no second place to keep in sync.
Done as a remark plugin rather than a find-and-replace over the sources
because the docs are checked in: rewriting files in place would mean a
commit on every release and a dirty tree for anyone who built locally.
MDX does not interpolate inside fenced code blocks, which is exactly
where `$version:` lives, so operating on the parsed tree is the only
thing that reaches it.
Deliberately a single explicit token rather than rewriting anything
version-shaped. Two pages name specific past releases on purpose
("the machine-wide accounting arrived after 1.0.0-M10"), and a blanket
rewrite would silently turn true statements into false ones.
`latest-version.mjs` throws when it finds no tag instead of guessing.
The realistic cause is a shallow clone, and a guessed version would be
published as documentation pointing at a release that may not exist —
worse than a failed build. So the workflow gains `fetch-depth: 0`,
since actions/checkout fetches no tags at depth 1.
Deploy triggers change to match. The path filter on master is gone: the
output can now change without any watched path changing, so filtering on
paths would leave the site advertising the previous version until
someone happened to touch a doc. And `v*` tags now deploy too, because
cutting a release changes what every example renders as without moving
master at all.
Verified by building the site: the rendered mill page reads
`$version: 1.0.0-M11`, and BLEEP_LATEST_VERSION appears nowhere in the
build output.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
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
1 participant
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.
Six pages told people to write
$version: 1.0.0-M9. Three releases stale, and stale in the way docs usually go stale: nothing was wrong, so nobody looked.Version from tags
The version is now derived from the newest
v*git tag at site-build time and substituted into aBLEEP_LATEST_VERSIONtoken. Releases are cut by pushing a tag, so the tags already are the release history — no second place to keep in sync, and no step to forget.bleep-site/scripts/latest-version.mjs— resolves it. Uses--sort=-v:refname, git's version sort, which ordersM10aboveM9numerically (lexical sort does not) and orders a final release above its own prereleases, so a futurev1.0.0will correctly win overv1.0.0-M11.bleep-site/scripts/remark-bleep-version.mjs— substitutes it.customFields.bleepVersiontoo, for the React pages undersrc/pages/which are not MDX and never reach remark.Why a remark plugin, not a find-and-replace over the sources. The docs are checked in. Rewriting them in place would mean a commit on every release and a dirty working tree for anyone who built the site locally. And MDX does not interpolate inside fenced code blocks — which is exactly where
$version:lives — so operating on the parsed tree is the only approach that reaches it at all.Why one explicit token, not "replace anything version-shaped". Two pages name specific past releases deliberately (
resource-management.mdx: "the machine-wide accounting arrived after1.0.0-M10"). A blanket rewrite would silently turn true statements into false ones. Those are untouched.Why it throws when there is no tag. The realistic cause is a shallow clone. A guessed or stale version would be published as documentation telling people to depend on a release that may not exist — worse than a failed build. Hence
fetch-depth: 0on the checkout, sinceactions/checkoutfetches no tags at depth 1.Deploy triggers
v*tags now deploy. Cutting a release changes what every$version:example renders as, without moving master at all — previously the site would not have picked it up.Verification
Built the site locally (
npm ci && npm run build, clean):$version: 1.0.0-M11BLEEP_LATEST_VERSIONappears nowhere inbuild/Note the initial grep for this looked like a failure — Prism splits code into per-token
<span>s, so the string is not contiguous in the HTML. Confirmed by stripping tags and matching the visible text.🤖 Generated with Claude Code