docs(branching): merge-commit promotions so release-please auto-cuts releases

[parth0025]

Permanent fix for "release tag not cut after promotion"

Root cause: the staging → main promotion was squash-merged, collapsing every feat/fix into a single chore(release) commit. release-please reads Conventional Commits on main, saw only a chore, and cut nothing — so every release (through v14.4.0) needed a manual tag + changelog.

Fix (Option 1 — chosen): merge the promotion with a merge commit instead of squashing. Then:

• release-please sees the real commits → auto-opens its Release PR → tag + GitHub Release are created automatically. No more manual cuts.
• main stays an ancestor of staging, so back-merges stop conflicting on release files — a second recurring pain gone.

This PR updates BRANCHING.md:

• Merge-method rule: promotions must use a merge commit (hotfixes may still squash).
• Rewritten release steps (head = staging, merge commit, release-please cuts the tag).
• A documented manual fallback for if a promotion ever gets squashed by mistake.

⚠️ One settings change needed (admin)

On GitHub → Settings → Branches → main (or the equivalent Ruleset): turn OFF "Require linear history" and ensure "Allow merge commits" is enabled. Without that, GitHub won't offer the merge-commit option for the promotion. Docs-only change here; the setting is what activates it.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: bc298c47-1187-45f7-a35a-b4c1810415e7

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/release-merge-commit-promotion

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}