Documentation

GIT_FLOW

docs/GIT_FLOW.md

Petunia Git Flow Documentation

🌊 Our Git Flow: Feature β†’ Development β†’ Preview β†’ Main

Visual Flow Diagram

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”     β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”     β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”     β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ feature/login   β”‚ ──> β”‚                 β”‚     β”‚                 β”‚     β”‚                 β”‚
β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€     β”‚                 β”‚     β”‚                 β”‚     β”‚                 β”‚
β”‚ feature/api     β”‚ ──> β”‚   development   β”‚ ──> β”‚     preview     β”‚ ──> β”‚      main       β”‚
β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€     β”‚                 β”‚     β”‚                 β”‚     β”‚                 β”‚
β”‚ fix/bug-123     β”‚ ──> β”‚                 β”‚     β”‚                 β”‚     β”‚                 β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜     β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜     β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜     β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
   Your Work          Integration Branch      Staging Testing      Production Release

Branch Hierarchy

main (production)
  ↑
preview (staging)  
  ↑
development (latest integrated features)
  ↑
feature/branches (individual work)

πŸš€ Important: We DO NOT merge directly with main!

The Complete Flow:

  1. Create feature branches from β†’ development
  2. Feature branches merge back into β†’ development
  3. Development merges into β†’ preview (for staging tests)
  4. Preview merges into β†’ main (production release)

Branch Purposes:

  • Feature branches = Your individual work (feature/, fix/, etc.)
  • development = Integration branch where all features come together
  • preview = Staging environment for final testing
  • main = Production code that customers use

πŸ“ Creating Pull Requests

ALWAYS create PRs against the correct branch:

# ❌ WRONG - Creating feature branch from main
git checkout main
git checkout -b feature/my-feature
# ... make changes ...
git push origin feature/my-feature
# Create PR: feature/my-feature β†’ main  ❌ NO!

# βœ… CORRECT - Creating feature branch from development
git checkout development
git pull origin development  # Always get latest
git checkout -b feature/my-feature
# ... make changes ...
git push origin feature/my-feature
# Create PR: feature/my-feature β†’ development βœ… YES!

πŸ”„ Resolving Merge Conflicts

When you see "This branch has conflicts"

  1. First, check which branch you should merge with:

    # For feature branches going to development:
    git fetch origin
    git merge origin/development  # NOT origin/main!
    
  2. Resolve conflicts:

    # Fix conflicts in your editor
    git add .
    git commit -m "fix: merge with development branch"
    git push
    

🎯 Quick Reference Commands

Starting new work:

# Step 1: Switch to development and get latest
git checkout development
git pull origin development

# Step 2: Create your feature branch FROM development
git checkout -b feature/my-new-feature
# OR for bug fixes:
git checkout -b fix/bug-description

While working:

# Make your changes
# Commit frequently with clear messages
git add .
git commit -m "feat: add new functionality"

Before creating a PR:

# Sync with latest development (not main!)
git fetch origin
git merge origin/development
# Fix any conflicts if they exist
git push origin feature/my-new-feature

Creating the PR:

# Push your branch
git push origin feature/my-new-feature

# Then on GitHub:
# Create PR from: feature/my-new-feature
# Target branch: development (NOT main!)

Checking PR target:

# View PR details
gh pr view YOUR_PR_NUMBER

# If targeting wrong branch, update it:
gh pr edit YOUR_PR_NUMBER --base development

⚠️ Common Mistakes to Avoid

  1. Creating PRs against main

    • Always target development for feature work
  2. Merging with main to resolve conflicts

    • Merge with development instead
  3. Working directly on main or preview

    • Always create feature branches

🏷️ Branch Naming Conventions

  • Feature branches: feature/description or claude/issue-XXX-timestamp
    • Examples: feature/social-proof, feature/add-analytics, claude/issue-1371-20250701
  • Bugfix branches: fix/description
    • Examples: fix/auth-loop, fix/payment-validation
  • Hotfix branches: hotfix/description (only for critical production fixes)
    • Examples: hotfix/security-patch, hotfix/payment-critical

πŸ“– Real-World Examples

Example 1: Adding a new feature

# Start fresh
git checkout development
git pull origin development

# Create feature branch
git checkout -b feature/revenue-calculator

# Work on your feature
# ... edit files ...
git add .
git commit -m "feat: add revenue impact calculator component"
git commit -m "feat: integrate calculator with onboarding flow"

# Before creating PR, sync with development
git fetch origin
git merge origin/development

# Push and create PR
git push origin feature/revenue-calculator
# On GitHub: Create PR from feature/revenue-calculator β†’ development

Example 2: Fixing a bug

# Start from development
git checkout development  
git pull origin development

# Create fix branch
git checkout -b fix/onboarding-infinite-loop

# Fix the bug
# ... edit files ...
git add .
git commit -m "fix: resolve infinite loop in onboarding wizard"

# Sync and push
git fetch origin
git merge origin/development
git push origin fix/onboarding-infinite-loop
# On GitHub: Create PR from fix/onboarding-infinite-loop β†’ development

πŸ“Š Release Process

  1. When development is stable β†’ Create PR to preview
  2. Test in staging environment
  3. When preview passes all tests β†’ Create PR to main
  4. Deploy to production

πŸ†˜ Quick Help

"Which branch should I merge with?"

  • For feature work β†’ merge with development
  • For preview testing β†’ merge with preview
  • Almost never merge directly with main

"My PR shows conflicts"

git fetch origin
git merge origin/development  # or origin/preview if going to preview
# Resolve conflicts
git push

"I accidentally created a PR against main"

gh pr edit PR_NUMBER --base development

πŸ“‹ Git Flow Cheat Sheet

Daily Workflow

# Morning: Start fresh
git checkout development && git pull

# Create feature
git checkout -b feature/my-work

# Work work work...
git add . && git commit -m "feat: description"

# Before PR: Sync up
git fetch && git merge origin/development

# Push it
git push origin feature/my-work

# PR Target: development βœ…

Quick Checks

  • βœ… Created branch from development?
  • βœ… PR targets development?
  • βœ… Merged latest development before pushing?
  • ❌ Never touched main directly?

Remember: development is our latest and greatest, not main!