Repository navigation
Closed
Labels
documentationImprovements or additions to documentationImprovements or additions to documentation
Description
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
mainand targetmain(unchanged for the common case). - Releases happen from
release/vN, not frommain. - Hotfixes for older majors land on
mainfirst, then cherry-pick torelease/vN-1(with the explicitgit switch+git cherry-pickrecipe). - Direct PR against a release branch needs
hotfix-directlabel + maintainer sign-off (exceptional case).
2. docs/agents/release-and-versioning.md
Extend 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.- Release pipeline section gets the tag-triggered + multi-channel walkthrough.
- NB.GV behaviour per branch (output of issue Validate Nerdbank.GitVersioning behaviour on release/vN branches #275 / equivalent).
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
-
CONTRIBUTING.mdupdated, with## Mergingreflecting the new flow. -
docs/agents/release-and-versioning.mdextended. -
docs/branching-and-release.mdexists. - AGENTS.md "Where to look next" section links the new doc.
- CHANGELOG entry under
[Unreleased] — 11.0→### Process. - No dead links; cross-references between the three docs check out.
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.
Metadata
Metadata
Assignees
Labels
documentationImprovements or additions to documentationImprovements or additions to documentation
Activity
ci: tag-triggered + multi-channel fan-out for release.yml (#274) (#288)
docs: release-branch model — CONTRIBUTING + branching-and-release run…