docs: release-branch model — CONTRIBUTING + branching-and-release runbook + ADR#295
Merged
Merged
Conversation
…book + ADR (#276, #277) Closes #276 and #277. Captures the full milestone #13 outcome in three places now that all the moving parts are in production: CONTRIBUTING.md - "Where to start" updated: PRs target main, releases ship from release/vN, hotfix flow noted. - "After opening a PR" updated to reflect ubuntu-latest now firing on release/v* PRs too (post #291/#292), with the windows/macos parity follow-up linked (#293). - New "Releases" section pointing contributors at the maintainer runbook. docs/branching-and-release.md (new) - Maintainer reference: branches at a glance, channel taxonomy, full step-by-step for cutting a release (gh release create + the env approval-gate prompt), hotfix workflow (cherry-pick recipe), workflow_dispatch fallback for re-running partial publishes, cutting a new release/vN, deprecating an old one, tag-protection ruleset. docs/adr/0001-release-branch-model.md (new — seeds docs/adr/) - Architecture Decision Record covering Context (consumer-facing noise from auto-release; no hotfix path), Decision (the model), and Consequences (positive + negative + neutral). Includes the four alternatives we considered and rejected. - Cites the consumer-pain-first principle (saved as agent memory) that drove the cutover timing. - Status: Accepted. Implementation already shipped. AGENTS.md - "Where to look next" links the new branching-and-release.md doc and the docs/adr/ directory so AI agents reading the brief discover them. CHANGELOG.md - Umbrella entry for milestone #13 under [Unreleased] — 11.0 → Process, summarising all sub-issues that landed: #269, #270, #272, #273, #274, #275, #291, #292. Per the pattern set in #269's closing comment — one consolidated entry rather than nine fragmented per-sub-issue entries. Refs milestone #13, RFC #267. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
ChrisonSimtian
added
documentation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #276 and #277. Captures the full milestone #13 outcome now that all the moving parts are in production.
What changes
CONTRIBUTING.mdmain, releases ship fromrelease/vN, hotfix flow noted.ubuntu-latestfires onrelease/v*PRs too (post-ci: extend PR-validation triggers to release/v* branches #291/ci: propagate PR-validation triggers to release/v11 (cherry-pick #291) #292), with the windows/macos parity follow-up linked to Extend windows-latest + macos-latest post-merge triggers to release/v* #293.docs/branching-and-release.md(new)Maintainer reference:
gh release create --target release/vN --generate-notes)hotfix-directexception)workflow_dispatchfallback for re-running partial publishesrelease/vN(incl. thepublicReleaseRefSpecper-branch tweak)release/vNdocs/adr/0001-release-branch-model.md(new — seedsdocs/adr/)Architecture Decision Record:
publicReleaseRefSpecAGENTS.md"Where to look next" links the new branching-and-release.md doc and the new
docs/adr/directory.CHANGELOG.mdUmbrella entry under
[Unreleased] — 11.0→Processsummarising every sub-issue that landed (#269 #270 #272 #273 #274 #275 #291 #292) plus the deferred items (#271) and the Tier 3 work (#279/#287). Per the pattern set in #269's closing comment — one consolidated entry vs nine fragmented ones.What this PR does NOT do
docs/agents/release-and-versioning.md— already updated in Branch protection on release/v11 (and future release/vN) #270 (branch protection policy) and Refactor release.yml: tag-triggered, multi-channel via environments #274 (release pipeline section). Consistent with reality.Test plan
🤖 Generated with Claude Code