Found while implementing #9018 (the check:docs-image-tag gate). Filing rather than fixing: adding a version-time rewriter is new release machinery, well beyond that card's "add a gate" scope, and it deserves its own review.
The measurement
check:docs-image-tag (landing via #9018) pins the docs' concrete image tags to packages/cli/package.json's version, so a version bump turns it red until the doc surfaces move in the same change. That is the intended mechanism. The problem is where the red lands.
Three facts, all measured on main at e449ee1f4:
The root version script is changeset version && node scripts/sync-protocol-version.mjs && node scripts/sync-template-versions.mjs. changeset version is what rewrites packages/cli/package.json's version.
Neither sync script touches any of the doc surfaces.grep -n 'Dockerfile\|content/docs\|docker/README\|ghcr' scripts/sync-template-versions.mjs scripts/sync-protocol-version.mjs returns zero hits. So the release PR bumps the version and leaves docker/README.md, content/docs/deployment/self-hosting.mdx and content/docs/upgrading.mdx pinned to the previous one.
The gate cannot fire on that PR.scripts/sync-template-versions.mjs's own header states the reason, and it is the repo's own finding, not mine:
release PRs opened by changesets/action with the default GITHUB_TOKEN do not trigger CI, so fixing the file at version time is the only spot that cannot be skipped
So the sequence is: release PR bumps the version with no CI - it merges green - and the gate goes red on the next ordinary PR, whoever opens it, about files that author never touched. The obligation is real but lands on the wrong person, one merge late.
Why this shape is already solved once in this repo
sync-template-versions.mjs exists for the identical drift class (#2907: the blank template froze at ^6.0.0 while the registry published 14.x). Its conclusion was that the scaffold-time rewrite and the ratchet test both guard it, but neither runs on the release PR, so the fix had to happen at version time. The docs image tags are the same problem with no version-time step.
Options
- A
sync-docs-image-tags.mjs in the root version script, rewriting the concrete pins on the surfaces check-docs-image-tag.mjs already enumerates. The gate becomes the backstop rather than the notifier, and the two share one surface list so they cannot disagree. This is the shape the repo already chose for the template. - Leave it as a manual release-checklist item. Cheapest, and the failure mode is exactly what the checklist forgetting looks like today.
- Accept the one-merge-late red. It is self-diagnosing (the gate names every
file:line and the expected value), just mis-addressed.
Recommendation: option 1, reusing SURFACES and PATTERNS exported from scripts/check-docs-image-tag.mjs so the rewriter and the gate cannot drift apart. That is the whole reason those two are exported.
Not this issue
The :latest tag in the create-objectstack blank template Dockerfile is already filed as #9017 and is not restated here.
Related: #9018, #8961, #8911, #2907.
Generated by Claude Code
Found while implementing #9018 (the
check:docs-image-taggate). Filing rather than fixing: adding a version-time rewriter is new release machinery, well beyond that card's "add a gate" scope, and it deserves its own review.The measurement
check:docs-image-tag(landing via #9018) pins the docs' concrete image tags topackages/cli/package.json's version, so a version bump turns it red until the doc surfaces move in the same change. That is the intended mechanism. The problem is where the red lands.Three facts, all measured on
mainate449ee1f4:The root
versionscript ischangeset version && node scripts/sync-protocol-version.mjs && node scripts/sync-template-versions.mjs.changeset versionis what rewritespackages/cli/package.json's version.Neither sync script touches any of the doc surfaces.
grep -n 'Dockerfile\|content/docs\|docker/README\|ghcr' scripts/sync-template-versions.mjs scripts/sync-protocol-version.mjsreturns zero hits. So the release PR bumps the version and leavesdocker/README.md,content/docs/deployment/self-hosting.mdxandcontent/docs/upgrading.mdxpinned to the previous one.The gate cannot fire on that PR.
scripts/sync-template-versions.mjs's own header states the reason, and it is the repo's own finding, not mine:So the sequence is: release PR bumps the version with no CI - it merges green - and the gate goes red on the next ordinary PR, whoever opens it, about files that author never touched. The obligation is real but lands on the wrong person, one merge late.
Why this shape is already solved once in this repo
sync-template-versions.mjsexists for the identical drift class (#2907: the blank template froze at^6.0.0while the registry published 14.x). Its conclusion was that the scaffold-time rewrite and the ratchet test both guard it, but neither runs on the release PR, so the fix had to happen at version time. The docs image tags are the same problem with no version-time step.Options
sync-docs-image-tags.mjsin the rootversionscript, rewriting the concrete pins on the surfacescheck-docs-image-tag.mjsalready enumerates. The gate becomes the backstop rather than the notifier, and the two share one surface list so they cannot disagree. This is the shape the repo already chose for the template.file:lineand the expected value), just mis-addressed.Recommendation: option 1, reusing
SURFACESandPATTERNSexported fromscripts/check-docs-image-tag.mjsso the rewriter and the gate cannot drift apart. That is the whole reason those two are exported.Not this issue
The
:latesttag in thecreate-objectstackblank template Dockerfile is already filed as #9017 and is not restated here.Related: #9018, #8961, #8911, #2907.
Generated by Claude Code