Git Branching Workflow

Branch Model

main        ← production, always deployable, tagged on release
staging     ← pre-production, mirrors prod environment
development ← integration branch, all features land here first
feature/*   ← one branch per feature, branched off development

Feature Development Cycle

# 1. Start from an up-to-date development branch
git checkout development
git pull origin development

# 2. Create feature branch
git checkout -b feature/my-feature

# 3. Work and commit
git add -p
git commit -m "feat: description of change"
git push origin feature/my-feature

# 4. Keep feature branch current while working
git pull origin development   # from the feature branch — resolve conflicts early

Promoting Changes

Prefer Pull Requests at each stage for code review and CI. If merging directly:

# feature → development
git checkout development && git pull origin development
git merge feature/my-feature
git push origin development

# development → staging
git checkout staging && git pull origin staging
git merge development
git push origin staging

# staging → main (after staging sign-off)
git checkout main && git pull origin main
git merge staging
git push origin main

# Tag the release
git tag -a v1.2.0 -m "Release v1.2.0"
git push origin v1.2.0

Key Rules

• main must always be deployable — never commit broken code directly
• Feature branches should be short-lived (merge within days, not weeks)
• Always pull the target branch before merging to minimize conflicts
• Tag every production release in main