[Document] Document branch strategy and merge policies

[Junyi-99]

Description

We currently lack documented policies for our branching strategy and PR workflow. This came up in #110 where team members were unsure about:

Whether PRs to staging require review or can be merged freely
When to target staging vs main for PRs
What our branch protection and versioning policies are

Proposed Solution
Create a CONTRIBUTING.md file that documents our branch structure, merge policies, and versioning scheme.

Branch Structure

Protected Branches

• main - Production-ready code

  • Each commit increases the minor version (e.g., 2.1.9 → 2.2.0)
  • Must be stable and deployable at any commit
  • Any commit should compile and run without issues

• staging - Pre-production testing environment

  • Each commit increases the patch version (e.g., 2.1.9 → 2.1.10)
  • Used for integration testing before promoting to main

• development (optional) - Development environment

  • Free to push without PR review
  • Commits do not affect version numbering
  • Used for rapid iteration and experimentation

Working Branches

• feat/* - Feature development branches

  • Example: feat/tab-completion, feat/user-auth

• fix/* - Bug fix and patch branches

  • Example: fix/token-expiration, fix/citation-parsing

---

Merge Workflow

Standard Flow (for substantial changes)

feat/* or fix/* → staging → main
                    ↓         ↓
              (integration  (production
                testing)     release)

1. Create feature/fix branch from staging (or development)
2. Develop and test locally
3. PR to staging: Merge for integration testing
   • Review optional for small changes
   • Required for complex/risky changes
4. PR from staging to main: After successful testing
   • Review required
   • All CI checks must pass
   • Version bump (minor)

Fast-track Flow (for small, low-risk changes)

feat/* or fix/* → main
                   ↓
            (direct to production)

• When to use: Small, well-tested changes that don't require integration testing
• Review still required
• All CI checks must pass
• Version bump (minor)

Decision Criteria

Use staging when:

• Changes are substantial or touch multiple components
• Need integration testing with other recent changes
• Uncertain about production impact
• Want to test in a prod-like environment first

Use main directly when:

• Changes are small and isolated (e.g., typo fixes, minor refactors)
• Confident in local testing
• Want to accelerate delivery

---

Branch Protection Rules

main branch (done)

• ✅ Require pull request before merging
• ✅ Require at least 1 approving review
• ✅ Require status checks to pass
• ✅ Require linear history (no merge commits)
• ✅ Do not allow force pushes
• ✅ Do not allow deletions

staging branch (done)

• ✅ Require pull request before merging (except for rapid iteration)
• ⚠️ Review optional but recommended for complex changes
• ✅ Require status checks to pass
• ✅ Allow force pushes (for rebasing during development)

development branch (if used) (done)

• ⚠️ No restrictions - free to push
• ⚠️ No review required
• ⚠️ No CI requirements (optional)

---

Version Numbering

We follow semantic versioning with these rules:

• Major version (X.0.0): Manual, breaking changes
• Minor version (2.X.0): Auto-increment on merge to main
• Patch version (2.1.X): Auto-increment on merge to staging

Example progression:

feat/new-feature → staging (2.1.9 → 2.1.10)
staging → main (2.1.10 → 2.2.0)

---

Code Stability Guarantee

Critical requirement: Every commit on main must:

• ✅ Compile without errors
• ✅ Pass all tests
• ✅ Be deployable to production
• ✅ Have no known breaking bugs

This ensures we can safely checkout any commit from main for debugging, rollback, or deployment.

---

Benefits

1. Clarity: New contributors understand the workflow immediately
2. Consistency: Team follows the same practices
3. AI-friendly: Claude, Copilot, and other tools can learn project conventions
4. Safety: Clear rules prevent accidental breaking changes
5. Flexibility: Supports both careful testing and fast iteration

---

Tasks

• Create CONTRIBUTING.md with branching strategy section
• Configure branch protection rules in GitHub settings
• Set up automated version bumping (if not already configured)
• Document this in README.md or link to CONTRIBUTING.md
• Announce new policy to team

---

Related

• Discussion in [#110 (comment)](feat: tab completion for citation keys #110 (comment))