Skip to content

Document the release-branch model in CONTRIBUTING.md and /docs #276

Description

@ChrisonSimtian

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

  • CONTRIBUTING.md updated, with ## Merging reflecting the new flow.
  • docs/agents/release-and-versioning.md extended.
  • docs/branching-and-release.md exists.
  • 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

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions