Git Flow

# ===== Branches in GitFlow =====
# main         release-ready code; tagged at each release
# develop      ongoing integration branch
# feature/*    short-lived branches off develop
# release/*    stabilisation branch off develop, merged to main + develop
# hotfix/*     emergency fix off main, merged to main + develop

# ===== Typical lifecycle =====

# 1) Start a feature
git switch develop && git pull --rebase
git switch -c feature/cart-quantity-stepper

# 2) Work + commit
git commit -m 'feat: cart quantity stepper'
git push -u origin feature/cart-quantity-stepper

# 3) Merge feature into develop (via PR)
# Reviewers approve; merge.

# 4) Cut a release when develop is ready
git switch develop && git pull --rebase
git switch -c release/1.4.0
# Only stabilisation commits go here: version bumps, copy fixes, docs.
# When green:
git switch main && git pull --rebase
git merge --no-ff release/1.4.0
git tag -a v1.4.0 -m 'Release 1.4.0'
git push origin main --tags
# Sync back to develop:
git switch develop
git merge --no-ff release/1.4.0
git push origin develop
git branch -d release/1.4.0

# 5) Hotfix
git switch main && git pull --rebase
git switch -c hotfix/1.4.1
# Fix + commit
git switch main
git merge --no-ff hotfix/1.4.1
git tag -a v1.4.1 -m 'Hotfix 1.4.1'
git push origin main --tags
git switch develop
git merge --no-ff hotfix/1.4.1
git push origin develop
git branch -d hotfix/1.4.1

# ===== git-flow tooling (optional) =====
# brew install git-flow-avh
# git flow init
# git flow feature start cart-stepper
# git flow feature finish cart-stepper
# git flow release start 1.4.0
# git flow release finish 1.4.0

# ===== Pros =====
# - Clear branch per concern (feature, release, hotfix)
# - Parallel maintained versions (release/1.x while 2.x in develop)
# - Stabilisation period maps to QA cycles
# - Big-bang releases align with regulated / mobile / on-prem timelines

# ===== Cons =====
# - More merge work + more branches alive at once
# - Slows continuous deployment
# - Hotfixes need careful sync to develop
# - Many small teams adopted GitFlow without needing it (and paid for it)

# ===== Modern alternative — GitHub Flow + tags =====
# main is always deployable
# Short-lived feature branches off main
# PR + CI + squash merge
# Tags on main mark releases
# Hotfixes are just normal PRs (because main is always deployable anyway)
# No develop, no release/, no hotfix/

# Add release-please / changesets to automate tagging + changelog.

# ===== Decision tree =====
# - Continuous deployment, web app                       -> GitHub Flow
# - Multiple supported versions (open source SDKs)        -> GitFlow OR trunk + release branches
# - Mobile app with store review gating                   -> trunk + release tag + a short stabilisation branch
# - Strict QA gates + staged rollouts                     -> GitFlow OR trunk + release/* during stabilisation
# - On-prem enterprise software                           -> GitFlow shines here

# ===== Common pitfalls =====
# - GitFlow with continuous deployment -> long branches, more conflicts
# - GitHub Flow without branch protection -> main breaks
# - Hotfixes that skip the develop sync -> regress on the next release
# - 'Release' branches that live for weeks -> by definition stop being short-lived

# ===== Quick comparison =====
# GitFlow     more branches, more rigor, clearer release windows
# GitHub Flow simpler, requires green main, ships faster
# Trunk-Based one branch, feature flags, ships fastest
# Pick by your release cadence, not by tradition.

# Heavyweight: develop + main + feature + release + hotfix branches.
# Rarely needed today.