Sibling of milestone #13. RFC #267. Per Chris's direction, the docs need to land in both the contributor-facing file and under /docs.
What
Three docs updates, in one PR:
1. CONTRIBUTING.md
Rewrite the Pull requests + Merging sections to reflect:
- PRs branch from
main and target main (unchanged for the common case).
- Releases happen from
release/vN, not from main.
- Hotfixes for older majors land on
main first, then cherry-pick to release/vN-1 (with the explicit git switch + git cherry-pick recipe).
- Direct PR against a release branch needs
hotfix-direct label + maintainer sign-off (exceptional case).
2. docs/agents/release-and-versioning.md
Extend the PR-creation flow and Release pipeline sections:
3. New docs/branching-and-release.md
A maintainer reference for the full lifecycle:
- When to cut a new
release/vN (start of a major).
- How to cut one (
git switch -c release/vN main && git push -u origin release/vN + branch protection apply).
- How to tag a release (
gh release create vN.M.P --target release/vN --generate-notes).
- How to hotfix.
- How to deprecate / archive an old release branch.
Acceptance criteria
Depends on
- Final shape of all upstream sibling issues (cut, branch protection, env setup, workflow refactor, NB.GV validation). The docs land after the implementation so they describe what actually exists.
ADR
The retrospective ADR capturing the decision (and alternatives considered) is a separate sibling issue.
Sibling of milestone #13. RFC #267. Per Chris's direction, the docs need to land in both the contributor-facing file and under
/docs.What
Three docs updates, in one PR:
1.
CONTRIBUTING.mdRewrite the Pull requests + Merging sections to reflect:
mainand targetmain(unchanged for the common case).release/vN, not frommain.mainfirst, then cherry-pick torelease/vN-1(with the explicitgit switch+git cherry-pickrecipe).hotfix-directlabel + maintainer sign-off (exceptional case).2.
docs/agents/release-and-versioning.mdExtend the PR-creation flow and Release pipeline sections:
target/vNlabels now correspond to whichrelease/vNbranch the change targets, not just which CHANGELOG section it appears under.3. New
docs/branching-and-release.mdA maintainer reference for the full lifecycle:
release/vN(start of a major).git switch -c release/vN main && git push -u origin release/vN+ branch protection apply).gh release create vN.M.P --target release/vN --generate-notes).Acceptance criteria
CONTRIBUTING.mdupdated, with## Mergingreflecting the new flow.docs/agents/release-and-versioning.mdextended.docs/branching-and-release.mdexists.[Unreleased] — 11.0→### Process.Depends on
ADR
The retrospective ADR capturing the decision (and alternatives considered) is a separate sibling issue.