Skip to content

Branching Strategies (GitHub Flow)

Branching Strategies (GitHub Flow Focus)

Effective branching lets teams ship fast without breaking main. For this course: prefer one protected main + short-lived feature branches + Pull Requests (PRs). Heavyweight multi-branch release flows add overhead without benefit here.

1. Core Lifecycle (GitHub Flow)

sequenceDiagram
  participant Dev as Developer
  participant Origin as Remote (origin)
  Dev->>Dev: git switch -c feat/login
  Dev->>Dev: code + commits
  Dev->>Origin: push branch
  Dev->>Origin: Open Draft PR
  Origin-->>Dev: CI feedback / review comments
  Dev->>Origin: Update commits (amend or new)
  Origin-->>Dev: Approved
  Dev->>Origin: Squash & merge
  Dev->>Dev: git pull origin main

2. Strategy Comparison (When You Might Deviate)

Strategy Branches Use Case Pros Cons
GitHub Flow main + feature Most web/services projects Simple, low cognitive load No long-lived staging branch
GitFlow (Classic) develop, release, hotfix Complex timed releases Structured release cadence Heavy for small teams
Trunk + Feature Flags main always deployable High-frequency deploys Continuous integration enforced Requires robust flag system
Release Branches (temporary) release/x.y + patches Hardening before milestone Isolate stabilization Overhead if misused

For capstone scale, GitHub Flow (maybe with occasional short release branch) is enough.

3. Branch Naming Conventions

Purpose Pattern Example
Feature feat/<short-desc> feat/login-form
Bugfix fix/<issue-id>-<desc> fix/134-null-pointer
Hotfix hotfix/<critical> hotfix/token-leak
Chore/Infra chore/<area> chore/upgrade-deps
Experiment (throwaway) exp/<idea> exp/vector-cache

Document final choice in CONTRIBUTING.md so new contributors align quickly.

4. Merge Methods (Decision Matrix)

Method History Shape Good For Caution
Squash & Merge One commit on main Small, linear history Lose per-commit granularity
Merge Commit Preserves branch topology Large multi-commit features Can get noisy if overused
Fast-Forward Pure linear Single new commit branches Only if branch never diverged
Rebase + Merge Linear + per-commit Cleaning local history pre-PR Don’t rebase shared branches

Default recommendation: Squash & merge for focused feature branches. Use merge commit for broad refactors requiring context.

5. Conflict Avoidance & Resolution Flow

flowchart LR
  A[Start Feature Branch] --> B[Commit Work]
  B --> C[Fetch/Rebase main]
  C --> D{Conflicts?}
  D -- Yes --> E[Resolve + Test]
  E --> C
  D -- No --> F[Push & Open PR]
  F --> G[Review]
  G --> H[Squash & Merge]

Tips: * Rebase (or merge) daily if main is active. * Keep PRs under ~400 lines changed where possible (review fatigue threshold).

6. Anti-Patterns (Avoid These)

Anti-Pattern Why Harmful Safer Alternative
Long-lived mega branch (feature/semester) Massive conflicts; stale context Break into vertical slices
Rebasing publicly shared branch Others’ history rewritten Merge from main instead
Force push without --force-with-lease Potentially overwrites teammate commits Always use --force-with-lease
Huge “grab bag” PR (code + formatting + refactor) Hard to review & revert Split into atomic PRs
Mixing unrelated changes in one branch Hard revert risk One logical concern per branch

7. Keeping main Green

Practice Effect
CI required before merge Prevents broken builds entering main
Draft PR early Early feedback; reduced rework
Pre-commit hooks Consistent formatting & linting
Small commits & PRs Faster review cycle

Add branch protection: required reviews, disallow force pushes, require status checks.

8. Rebase Guidance (Local Only)

Local cleanup before sharing: 

git switch feat/login
git fetch origin
git rebase origin/main
# resolve conflicts
git push --force-with-lease
Never rebase a branch after teammates have based work on it.

9. Release Branch (Optional Pattern)

Use sparingly when you need to freeze features and only accept high-priority fixes: 

git switch main
git switch -c release/1.2.0
# Only bug fixes & docs
After tagging and deploying: 
git switch main
git merge --ff-only release/1.2.0
git tag v1.2.0
git branch -d release/1.2.0

10. Automation Opportunities

Task Automation
Branch name lint CI regex (feat
PR size label Auto-label large PRs
Stale branch cleanup PRs inactive >30 days
Conventional commit check commitlint

11. Checklist

  • Branch naming convention adopted
  • PR template in place
  • Branch protection (CI + 1 review) enabled
  • Default merge strategy chosen & documented
  • No long-lived unmerged branches > 1 week
  • Rebase only local unpublished branches
  • Force push uses --force-with-lease

12. Further Resources