Validate Nerdbank.GitVersioning behaviour on release/vN branches

[ChrisonSimtian]

Sibling of milestone #13. RFC #267.

What

Verify that NB.GV produces the right versions on the new branch shape before any of the publish-workflow changes go live. NB.GV uses commit-height + the version.json version field; cherry-picks to release/vN will increment patch height; main going to 12.0 should immediately produce 12.0.0-… builds.

Acceptance criteria

• After cutting release/v11 and bumping main's version.json to 12.0:
  • nbgv get-version on release/v11 reports 11.0.N+1 where N is the patch height at cut.
  • nbgv get-version on main reports 12.0.0-… (or whatever pre-release suffix is configured).
  • A cherry-pick to release/v11 increments the patch.
  • A merge to main increments the v12 prerelease counter, not v11.
• If version.json needs pathFilters or cloudBuild tweaks for the branch model, those changes are made.
• Findings documented in the docs PR.

Depends on

• release/v11 exists.
• main's version.json bumped to 12.0.

Notes

• This is mostly investigation + a smoke test, not a code-heavy PR. May produce no diff if NB.GV "just works" — that's fine, the artifact is the documented confirmation.
• If we discover NB.GV needs a release config section per its docs ({"release": {"branchName": "release/v{version}"}}), wire that in.

[ChrisonSimtian]

NB.GV release-branch validation — findings

Investigation done in an isolated worktree on commits:

• origin/main @ 5e7b8532
• origin/release/v11 @ 4b19a8c1

nbgv global tool: 3.9.50.

version.json (identical on both branches — #271 still deferred)

{
  "version": "11.0",
  "publicReleaseRefSpec": ["^refs/heads/main$"],
  "pathFilters": [":/", ":!/tools"],
  "release": {
    "versionIncrement": "minor",
    "firstUnstableTag": "preview",
    "branchName": "release/v{version}"
  }
}

nbgv get-version (simulated by checking out the branches as real local refs in the worktree)

Branch	Version	NuGetPackageVersion	PublicRelease
main	11.0.20.24187	11.0.20	true
release/v11	11.0.19.19225	11.0.19-g4b19a8c144	false

Acceptance-criteria check:

• release/v11 reports 11.0.N (N=19, height at cut)
• main reports 11.0.X matching commit height (X=20); criterion adjusted because Bump main's version.json to 12.0 (next-major trunk) #271 deferred
• Cherry-pick to release/v11 increments patch — simulated the docs PR (5e7b8532) onto release/v11; height went 19 → 20, NuGet version became 11.0.20-g2b5f52a466
• Merge to main would advance main's own height (currently 20), not the v11 line — confirmed by the fact main and release/v11 already diverge cleanly on height

One real problem found — release/v11 is NOT a public release

publicReleaseRefSpec is locked to ^refs/heads/main$. NB.GV consequently appends -g<sha> to every build out of release/v11. Per the public-vs-stable docs:

If in addition to shipping out of main you also service past releases, you might name those branches with a convention of vMajor.Minor … each public release branch must have a unique version in version.json to prevent version collisions between branches.

So a v11 patch built from release/v11 today would publish as 11.0.20-g2b5f52a466, not the clean 11.0.20 we want.

What needs to change (when #271 lands, or sooner if we plan to ship a v11 patch first)

On release/v11 — edit version.json:

-  "publicReleaseRefSpec": ["^refs/heads/main$"],
+  "publicReleaseRefSpec": [
+    "^refs/heads/main$",
+    "^refs/heads/release/v11$"
+  ],

NB.GV's docs require unique version per public-release branch. That holds after #271: main = 12.0, release/v11 = 11.0. Until #271 lands they collide, so this edit must either (a) ship together with #271, or (b) ship on release/v11 only and have #271 carry the main half.

pathFilters and cloudBuild need no changes — the :!/tools filter behaved correctly across the cherry-pick test. The release block (branchName: "release/v{version}") is already correct and is what nbgv prepare-release would consume; no changes needed there either.

Recommendation

Leave this issue open. The branch model itself works (height computes correctly, cherry-picks advance patch), but to actually publish a clean 11.0.X patch out of release/v11 we need the publicReleaseRefSpec addition above. Cleanest sequencing:

1. Land Bump main's version.json to 12.0 (next-major trunk) #271 (bump main to 12.0) when v12 work starts.
2. In the same PR (or immediately after on release/v11), add ^refs/heads/release/v11$ to publicReleaseRefSpec on both branches.

If a v11 servicing patch needs to ship before #271, do the publicReleaseRefSpec edit on release/v11 only — the collision risk is moot until main actually moves to 12.0.

[ChrisonSimtian]

Done — landed in PR #290 (merged 2026-05-29T07:16:38Z). release/v11 added to publicReleaseRefSpec in version.json. nbgv get-version on release/v11 now produces clean 11.0.X versions instead of git-sha-suffixed. Targeted release/v11 only (not main) to avoid the patch-height collision until #271 lands and main moves to 12.0.