feat(release-script): re-render the previews a cut publishes - #488
Merged
Conversation
The committed previews record the version they were rendered at, and nothing moved it. A cut bumped every pom, regenerated the showcase site at the new version, and left assets/readme on the release before — with the drift gate comparing both sides at the recorded version and staying green through it. The figures README and the site show would have gone one release out of date at every tag, invisibly, which is the drift the gate was written to end. The cut now moves that property with the tag and re-renders the previews from the same catalogue the site is built from. It runs before the verify step, because that is where the gate compares them: scheduled after it, a cut would fail on exactly the files it was about to bring up to date. Generating the catalogue and syncing the site were one function, so skipping the site skipped the render as well. They are separate now, and -SkipShowcase skips only what it names — the published tree under web/. The previews ship in the repository and are refreshed either way; -PostReleaseOnly leaves them alone, since they belong to the tag rather than to the branch it opens. The two halves — the refresh and the staging list that carries it into the release commit — sit in different parts of the script and neither fails without the other, so a guard holds them together, and holds the refresh before the step that checks it. Dry-run in all three modes: a plain cut bumps the property, renders, refreshes 67 previews and stages them; -SkipShowcase does the same without touching web/; -PostReleaseOnly touches neither.
…where else Bumping it inside Update-PomVersion put it on every pom that pass touches, in every mode that calls it. The post-release step carries the train to X.Y.(Z+1)-SNAPSHOT and would have carried this with it; surefire hands the value to the examples module as a display version, and ExampleVersion accepts a released X.Y.Z and nothing else, so the next build would have thrown before comparing a single preview. A pre-release cut is the same defect with a different value: X.Y.Z-rc.N is rejected too, and its qualifier-stripped form names a release that does not exist — the previews would have advertised it. Neither showed in a dry run. This tree is already on a -SNAPSHOT, so the post-release bump finds nothing to do and never reaches the property, and a dry run writes no pom, so an -rc cut had nothing to inspect. The check is the branch that ran rather than the file that changed, and the release-script workflow now asserts all three: a final cut moves it, a pre-release and the post-release pass leave it alone. The move lives in its own step, called only for a final tag, and the README assets follow it there — a pre-release leaves the previews and the property on the last published version and stages neither. It also stands outside Update-PomVersion's early return: a cut interrupted after the version bump left the property behind, and re-running reported nothing to do.
The committed folder is flat, so a file name is the whole address. Two rendered documents sharing one left whichever the directory walk reached first deciding what a preview was refreshed from — the same silence CommittedAssetDriftTest refuses, and it refuses it a step later, so an ordinary cut would have caught this at verify. Not a cut run with -SkipVerify: there the wrong document ships under the right name, and nothing says so.
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.
Last of the three changes for #461, and the one that makes the gate in #487 survive a release. This should land before the next cut — #487 alone leaves the previews a version behind at every tag.
Why
The committed previews record the version they were rendered at, and nothing moved it. A cut bumped every pom, regenerated
web/showcaseat the new version, and leftassets/readme/**on the release before. The drift gate could not notice: it renders and compares both sides at the recorded version, so it stayed green while the figures README and the site show fell a release out of date — at every tag, invisibly. That is the same drift the gate was written to end, arriving through the one door it does not watch.What
The version moves with the tag — and only a final one.
Update-AssetVersionis deliberately separate from the generic pom bump: the post-release step carries the train toX.Y.(Z+1)-SNAPSHOTand a pre-release cut carriesX.Y.Z-rc.N, and the examples module rejects both as display versions — the-rcform's qualifier-stripped version names a release that does not exist yet. It also stands outside the generic bump's early return, so a cut interrupted after the version bump can be re-run to finish the job.The previews are re-rendered from the catalogue the site is built from. A new step renders the catalogue at
$Versionand copies each committed preview's counterpart over it. Which previews are published is the folder itself — every file already there is refreshed and nothing new is added, so the refresh and the gate cannot disagree about what is published. A committed preview no example renders fails the step by name rather than reaching the gate as a puzzle.A pre-release leaves the README assets alone, on the last published version, and stages neither them nor the property.
It runs before
mvnw verify, because that is where the gate compares them. Scheduled after, a cut would fail on exactly the files it was about to bring up to date.-SkipShowcaseskips only what it names. Generating the catalogue and syncing the site were one function, so skipping the site skipped the render too. They are separate now:Build-ExampleCatalogueandSync-ShowcaseSite. The previews ship in the repository and are refreshed either way;-PostReleaseOnlyleaves them alone, since they belong to the tag rather than to the branch it opens.assets/readme/examplesjoins the staging allow-list, so the refresh reaches the release commit.The refresh and the staging list sit in different parts of the script and neither fails without the other — a refresh that is not staged tags the previous release's figures, a staged path nothing refreshes commits whatever is in the working tree.
ReleaseAssetStepGuardTestholds them together, and holds the refresh before the step that checks it.Tests
core426 tests,examples71 andqa688, green locally. The script parses clean, and was dry-run in all three modes:assetVersionweb/showcase9.9.99.9.9-SkipShowcase9.9.92.1.0-rc.1-PostReleaseOnlyexamples.jsonThe three modes are also exercised for real in
release-script-check.yml, asserting the branch that ran rather than the file a dry run does not write: a final cut moves the version, a pre-release and the post-release pass do not.Out of scope