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!