docs: branching/merging guide + branch protection on main#28
Merged
Conversation
- New docs/contributing/branching.md explains trunk-based development: one long-lived `main`, short-lived feature branches (`<type>/<slug>`), squash-merge PRs, releases as tags on main (no release branches). - mkdocs.yml: add the new page to the Contributing nav. - release-process.md: cross-link the branching doc and clarify that release prep itself goes through a `chore/release-X.Y.Z` PR before the tag is cut. - CLAUDE.md / AGENTS.md: add a short Branching section so AI agents default to feature branches instead of pushing to `main`. Companion change: enable branch protection on `main` (require PR, require CI, no direct push, no force-push, no admin bypass) — applied via `gh api` once this PR is open so the policy can be exercised on this very merge. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
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.
Establishes a documented branching convention and protects `main` from
direct pushes.
Why
Until now, work has sometimes landed directly on `main`. We want every
change to go through a PR (CI gate + audit trail), but until this PR
that was a soft convention rather than an enforced rule.
Changes
with short-lived `/` feature branches; squash-merge into
`main`; releases are tags on `main`, not branches; we don't maintain
long-lived release branches until v2.x ships.
release prep itself goes through a `chore/release-X.Y.Z` PR before
tagging.
default to feature branches instead of pushing to `main`.
Companion (out of band, applied via `gh api`)
Branch protection on `main`:
The protection is applied once this PR is open, so this very PR
exercises the new policy on its merge.
Test plan
should be rejected.
(PR-route is allowed; only direct pushes are blocked).
🤖 Generated with Claude Code