cut-release -PostReleaseOnly always opens a patch SNAPSHOT, so every minor needs a manual re-open

[DemchaAV]

What happens

Get-NextSnapshotVersion increments the patch, unconditionally:

if ($version -match '^(\d+)\.(\d+)\.(\d+)$') {
    return "$($Matches[1]).$($Matches[2]).$([int]$Matches[3] + 1)-SNAPSHOT"
}

A GA of X.Y.Z therefore always opens X.Y.(Z+1)-SNAPSHOT. When the next release is a minor — which it has been for both 2.x releases so far — the line is numbered wrong from the moment it opens, and stays wrong until someone notices.

develop is on 2.1.1-SNAPSHOT right now. If 2.2.0 is next, this repeats.

It already cost two corrective PRs

After v2.0.0 the script opened the 2.0.1 line. The next release was 2.1.0, so:

• #398 docs(changelog): drop the premature v2.0.1 Planned entry — deleted an 11-line ## v2.0.1 — Planned heading that should never have existed.
• #436 chore(release): open the 2.1 development line — bumped every train pom by hand, rewrote 72 lines of CHANGELOG, and corrected @since tags in LineBuilder from 2.0.0 to 2.1.0.

That last one is the part worth caring about. @since is a public API contract: it tells a consumer which release they need. When the pom says one thing and the real target is another, the tags get guessed, and the guesses drift — here they landed on the shipped version rather than the upcoming one, because the in-flight number offered no useful hint.

Why nothing catches it

The runbook documents it as a manual note (release-process.md §2.G, the "Post-GA -SNAPSHOT naming" blockquote), and VersionConsistencyGuardTest only asserts the train poms agree with each other and with the README — it has no opinion on whether 2.1.1-SNAPSHOT or 2.2.0-SNAPSHOT is the right next line. Both states are internally consistent, so the guard passes either way.

A note in a doc is the weakest possible protection for something a script does automatically and silently.

Options

1. Ask. Add -NextLine patch|minor to -PostReleaseOnly (default patch, preserving today's behaviour). One flag at the one moment the answer is known.
2. Derive it. Read the next ## vX.Y.Z — Planned heading from CHANGELOG.md and open that line. Self-correcting, and it makes the CHANGELOG the single source for "what's next" — but it needs the heading to exist before the post-release step runs.
3. Guard it. Assert the pom SNAPSHOT matches the open CHANGELOG heading. Catches the drift instead of preventing it, and would have turned both docs(changelog): drop the premature v2.0.1 Planned entry #398 and chore(release): open the 2.1 development line #436 into a red build on the first commit rather than a cleanup later.

1 and 3 compose well: pick the line deliberately, then hold it.

Related

The japicmp baseline (<japicmp.baseline>2.0.0</japicmp.baseline>, core/pom.xml:101) is likewise hand-pinned and wants a decision each time the major floor moves — not the same bug, but the same class of hand-maintained release constant, and worth settling in the same pass.

[DemchaAV]

Option 3 has landed in #521 (61fbdef8). Options 1 and 2 are untouched, so this stays
open — the script still picks the next line by incrementing the patch.

What is now held

VersionConsistencyGuardTest.theOpenChangelogEntryNamesTheVersionUnderDevelopment fails the
build when the entry left open in CHANGELOG.md and the working pom version name different
releases. Alongside it: a second open entry fails as ambiguous, an undated entry below a
shipped one fails as a leftover, and a ## heading that names no release fails rather than
being skipped — leaving the check with nothing to compare must not look like agreement.

An entry counts as open because it carries no date, not because of the word after the
version. That distinction is the whole difference between this working and not, and the
reason is in this repository's own history rather than in theory — see below.

The wording is then held separately to the exact — Planned the cut replaces, em dash
included, since an ASCII hyphen is as invisible to that replacement as another word would be.
Getting it wrong does not ship an undated entry: Assert-ReleaseMetadata stops the cut on the
missing date. It stops the release instead of the commit that caused it, which is the
smaller thing the wording check actually buys.

A correction to the option as written above

would have turned both #398 and #436 into a red build on the first commit

Half of that holds. Checked against the tree at each point:

• docs(changelog): drop the premature v2.0.1 Planned entry #398 — not caught, and could not be. Immediately before 2f80193c, core/pom.xml read
  2.0.1-SNAPSHOT and the changelog read ## v2.0.1 — Planned. The two agree, so the check
  passes; after the entry is deleted there is no open entry, which also passes. Nothing in the
  tree says 2.0.1 was the wrong answer — that knowledge lived only in the intended release
  date. A pom and an entry that are wrong together remain outside what any cross-check of
  these two sources can see.
• chore(release): open the 2.1 development line #436 — caught, 31 commits earlier than it actually was. 70c8016b (2026-07-16, feat(core): select fixed-layout render backends by format #404)
  introduced ## v2.1.0 — in progress while the poms still said 2.0.1-SNAPSHOT. That commit
  fails the check. e7a54958 — the by-hand bump of every train pom, the 72-line changelog
  rewrite and the LineBuilder @since corrections — is what happens when it does not.

Note the wording there: in progress, not Planned. A check keyed on the marker word
would have watched that entire line go past. Four spellings have opened a line here —
Planned, in progress, Unreleased, unreleased — which is why openness is decided by the
absence of a date.

What the @since argument turned out to be

The claim above is that the in-flight number offers no useful hint and the tags get guessed.
The guessing is real; the direction is worth recording, because no tag ever took the pom's
answer. Across 70c8016b..e7a54958, nine commits wrote @since 2.1.0 — the open entry's
answer — and four wrote @since 2.0.0, the last shipped release; those four are the ones
e7a54958 had to correct. @since 2.0.1 has never been written on any branch. So the value of
holding the two sources together is that there is one answer available rather than two, not
that the pom's answer propagates.

What is left

Option 1 (-NextLine patch|minor) is still the half that makes the choice deliberate, and
it also unlocks a stricter version of this check. Having no open entry currently has to pass:
-PostReleaseOnly bumps the poms at Step 3 and runs this very test at Step 3b before committing
at Step 4, without writing a heading, so demanding one would fail the release script's own
commit. If that step wrote the — Planned heading for the line it opens, the empty case would
stop being legitimate and the check could require an open entry outright — closing the window
between a GA and the cycle's first changelog entry, which is the one stretch still unguarded.

The japicmp.baseline pin noted above is untouched.