build(release-script): documentation install snippets move with the release - #492
Merged
Conversation
…elease The version guard covered the README, the module READMEs and the showcase site, and stopped there. The troubleshooting page carries the two snippets a reader copies at the worst possible moment — when a session already refuses to start — and both had sat on 2.0.0 since the module install matrix landed in #306, handing out a render backend one minor behind the engine that reader was running. The guard now walks docs/, skipping the trees that pin an old version on purpose by path prefix rather than by a list someone has to remember to extend. A second check closes the same gap one step earlier: a page carrying such a snippet must be named in both of the release script's lists, the one that rewrites the version and the one that stages the file. The bumper no longer leans on a file naming a single coordinate either — it skips graph-compose-fonts and graph-compose-emoji wherever they appear, since those ship on their own release lines. ./mvnw -B -ntp clean verify — BUILD SUCCESS. VersionConsistencyGuardTest 13 -> 15; both new tests confirmed red against a deliberately stale version and a deliberately missing staging entry.
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.
Why
The version guard covers the root README, the eight module READMEs and the showcase site, and stops there.
docs/troubleshooting.mdcarries the two snippets a reader copies at the worst possible moment — when a session already refuses to start — and both had sat on2.0.0since the module install matrix landed in #306, handing out a render backend one minor behind the engine that reader was running. Nothing would have caught it at the next cut either:cut-release.ps1rewrites a hand-maintained list of files, and that page was not on it.What changed
docs/troubleshooting.md— thegraph-compose-render-pdfandgraph-compose-render-docxsnippets read2.1.0.VersionConsistencyGuardTest.documentationInstallSnippetsMatchTheProjectVersionwalksdocs/and checks every versioned GraphCompose coordinate against the same target set the README snippets use. Trees that pin an old version on purpose —migration/,roadmaps/,archive/,templates/v1-classic/,private/— are excluded by path prefix, so a new migration guide is covered the day it is written rather than the day someone remembers to extend a list. A companion coordinate (graph-compose-fonts,graph-compose-emoji) is checked against its own pom, never the engine train's.VersionConsistencyGuardTest.documentationPagesWithInstallSnippetsAreBumpedByTheReleaseScriptcloses the gap one step earlier: a page carrying such a snippet must appear in both of the release script's$docPagelists — the one that rewrites the version and the one that stages the file. Bumping a file the commit never stages leaves the tag carrying the old text.cut-release.ps1gains those two lists, andUpdate-ModuleReadmeInstallVersionstops leaning on "one file, one coordinate": its Maven and Gradle regexes now exclude-fonts/-emojiexplicitly, so a future "font not found → addgraph-compose-fonts:1.0.0" block on a docs page cannot be rewritten to the engine version mid-cut.Verification
./mvnw -B -ntp clean verify—BUILD SUCCESS, exit 0.VersionConsistencyGuardTest13 → 15 tests. Both new tests were confirmed to fail for the right reason before being accepted:docs/troubleshooting.md:54to2.0.0→docs/troubleshooting.md:53 graph-compose-render-pdf advertises 2.0.0, expected one of [2.1.0]docs/troubleshooting.mdfrom the staging list →docs/troubleshooting.md is bumped by cut-release.ps1, so the release commit must stage itThe companion-exclusion regexes were exercised against a sample carrying
graph-compose-render-pdf,graph-compose,graph-compose-fontsandgraph-compose-emoji: the two train coordinates bump, the two companions are left alone.Lane: build/CI + docs. No production code, no public API.