docs: document hotfix backports and preview release versioning

[Corina (corinagum)]

Why

Shipping the channelData fix (#564) to both live release trains, as 2.0.16 and 2.1.0-alpha.2, surfaced several gaps in RELEASE.md.

The doc only describes cutting a new release from main: branch off main, bump version.json, git merge -s ours. There was no procedure for the more common case, where a fix has already landed on main and needs to ship on an existing release line. Following the documented flow for a hotfix would sweep all of main into the release branch, turning a one-line fix into an untested release.

Nothing documented how preview versions on release/v2.1 are numbered either. The 2.1.0-alpha.{height} scheme computes the version from commit height, so versionHeightOffset has to be set to a value that depends on a merge commit that does not exist yet. Getting it wrong republishes a version already on PyPI. Working that out required reverse-engineering the previous backport (#544) from git history.

What changed

• Branch Strategy now lists both live trains (release/v2.0 stable, release/v2.1 preview) with their PyPI dist-tags, and notes that a fix affecting both needs a separate backport and release for each.
• New section: Backporting a fix to a release branch. The cherry-pick flow, including how to find the commit by PR number.
• New section: Preview releases. The three height rules, the versionHeightOffset = target_alpha - final_merge_height formula, and a worked example using the real numbers from 2.1.0-alpha.2.
• New section: After a release. version.json stays as-is once a release ships. A stable branch keeps its literal version and the next release PR bumps it; a preview branch increments {height} on its own. Sitting on an already-published stable version is deliberate, since PyPI rejecting a duplicate upload is the only guard against an accidental publish.
• The merge-commit requirement. Backport PRs into release branches must not be squashed, unlike PRs into main. Squashing lowers the final height and makes the pipeline republish an existing version.
• Verification steps. nbgv get-version -v SemVer2 before triggering a Public run, and a post-publish check that a preview did not displace the latest tag. Plus a tip for confirming the number before merging by simulating the merge on a locally-named release/vX.Y branch, which matters because publicReleaseRefSpec matches on branch name.
• Corrections. The Tagging section claimed release PRs are squash-merged; they are not, and for the preview train they must not be. Replaced with an accurate explanation of why auto-generated notes usually need rewriting. Refreshed stale version examples and noted --prerelease for preview GitHub releases.

Notes

Docs-only. No code, dependency, or pipeline changes.

Claims here were verified against the repo rather than assumed: the height math was checked with nbgv against #544 and the 2.1.0-alpha.2 release, the squash-merge behavior by parent counts on main, and the dist-tag and duplicate-guard behavior by reading .azdo/publish.yml.

[Copilot]

Pull request overview

Updates the release process documentation to cover hotfix backports onto long-lived release branches and to explain preview (alpha) versioning/numbering for the release/v2.1 train, aligning the written process with how the repository’s NBGV + publish pipeline actually behave.

Changes:

• Documented a cherry-pick based backport workflow for releasing a fix already merged to main onto an existing release/vX.Y branch.
• Added a detailed “Preview releases” section explaining commit-height-derived alpha numbering and how to compute versionHeightOffset, including a worked example.
• Refreshed branch strategy/version examples and updated GitHub release guidance for preview releases.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.