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.