docs(branching): add branching strategy and update CONTRIBUTING

[parth0025]

Summary

Adds BRANCHING.md — a comprehensive branching-strategy doc that captures AlianHub's two-branch model (main + staging) and aligns CONTRIBUTING.md with reality (it previously told contributors to branch off main, but we've been branching off staging all along).

Step 2 of the open-source repo maintenance baseline initiative (Step 1 — license relicense to AGPL-3.0).

Why this matters

Right now, a new contributor reading CONTRIBUTING.md would create a branch off main and open a PR against main. That PR would either be wildly out of date (staging is 235 commits ahead) or rejected. This PR fixes that gap and gives contributors a single source of truth for branch conventions.

Files changed (3)

File	Change
BRANCHING.md (new, 327 lines)	Two-branch model, 11 topic-branch types, PR/hotfix/release workflows, protected branch rules, gh-api setup commands, cheatsheet, FAQ
CONTRIBUTING.md	Fixed base branch (main → staging), updated branch naming examples to Conventional-Commits style (feature/ → feat/, etc.), added link to BRANCHING.md
.claude/REFERENCES.md	Added BRANCHING.md to the Contributing & Community docs index

The model (captured, not invented)

main (stable, releases only)  ◄── promoted from staging at release time
  ▲
staging (active dev)  ◄── all topic-branch PRs land here
  ▲
feat|fix|chore|... topic branches  ◄── branch off staging, PR back to staging

hotfix/* branches from main, PR to main, backport to staging
release/v* branches from staging, PR to main, tag

Model choices documented (reviewers — push back if any feel wrong)

Choice	Set to
Reviews required on main PRs	1 approval
Merge style on main	Linear history (squash or rebase)
Reviewer requirement on staging PRs	0 (maintainer self-merge OK)
Promotion cadence	On-demand (typically every 1–4 weeks)
Conventional Commits in PR titles	Required
Hotfix backport method	Cherry-pick to staging

⚠️ Important — what this PR does NOT do

Branch protection rules are documented but NOT yet applied to GitHub. The ready-to-run gh api commands are in BRANCHING.md § How to enable branch protection.

We will run those commands after this PR merges — applying them now would block the very PR that introduces them.

Test plan

• BRANCHING.md renders correctly on GitHub (tables, mermaid-like ASCII flow, code blocks)
• Internal anchor links in BRANCHING.md (#topic-branches, #how-to-enable-branch-protection-one-time-setup) work
• CONTRIBUTING.md no longer mentions main as the base branch
• Link from CONTRIBUTING.md → BRANCHING.md works
• Link from .claude/REFERENCES.md → BRANCHING.md works

After merge

1. Run the gh api branch-protection commands from BRANCHING.md (admin-only)
2. Verify protections show up in repo Settings → Branches
3. Move on to step 3 — PR & branch name formats (templates, commitlint)

🤖 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: 59614b19-e984-4757-9db6-e092311679df

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/branching-strategy

---

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