# 🚀 Safe Push to Main Branch Guide

**IMPORTANT**: This guide ensures you don't break production when merging to main.

## ⚠️ Pre-Flight Checklist

Before even thinking about pushing to main, verify ALL of these:

### 1. Code Quality ✅
```bash
# Run all checks
npm run build          # Must pass with 0 errors
npm run lint           # Must pass with 0 errors
npx tsc --noEmit       # TypeScript must be clean
npx prisma format      # Database schema must be valid
```

### 1b. Automated Testing ✅
```bash
# Run comprehensive test suite (RECOMMENDED)
npm run test:all       # Runs all tests including E2E

# Or run individually:
npm run test           # Unit tests
npm run test:critical  # Critical path E2E tests
npm run test:hydration # Hydration tests
npm run test:email     # Email API tests
```

### 2. Testing ✅
```bash
# Automated testing (RECOMMENDED)
npm run test:all       # Runs all automated tests

# Manual testing (if needed)
npm run dev
# Test these critical paths:
# - Home page loads
# - Projects page works
# - Admin dashboard accessible
# - API endpoints respond
# - No console errors
# - No hydration errors
```

### 3. Database Changes ✅
```bash
# If you changed the database schema:
# 1. Create migration
npx prisma migrate dev --name your_migration_name

# 2. Test migration on a copy of production data
# 3. Document migration steps
# 4. Create rollback plan
```

### 4. Environment Variables ✅
- [ ] All new env vars documented in `env.example`
- [ ] No secrets committed to git
- [ ] Production env vars are set on server
- [ ] Optional features have fallbacks

### 5. Breaking Changes ✅
- [ ] Documented in CHANGELOG
- [ ] Backward compatible OR migration plan exists
- [ ] Team notified of changes

---

## 📋 Step-by-Step Push Process

### Step 1: Ensure You're on Dev Branch
```bash
git checkout dev
git pull origin dev  # Get latest changes
```

### Step 2: Final Verification
```bash
# Clean build
rm -rf .next node_modules/.cache
npm install
npm run build

# Should complete without errors
```

### Step 3: Review Your Changes
```bash
# See what you're about to push
git log origin/main..dev --oneline
git diff origin/main..dev

# Review carefully:
# - No accidental secrets
# - No debug code
# - No temporary files
# - All changes are intentional
```

### Step 4: Create a Backup Branch (Safety Net)
```bash
# Create backup before merging
git checkout -b backup-before-main-merge-$(date +%Y%m%d)
git push origin backup-before-main-merge-$(date +%Y%m%d)
git checkout dev
```

### Step 5: Merge Dev into Main (Local)
```bash
# Switch to main
git checkout main
git pull origin main  # Get latest main

# Merge dev into main
git merge dev --no-ff -m "Merge dev into main: [describe changes]"

# If conflicts occur:
# 1. Resolve conflicts carefully
# 2. Test after resolving
# 3. Don't force push if unsure
```

### Step 6: Test the Merged Code
```bash
# Build and test the merged code
npm run build
npm run dev

# Test critical paths again
# - Home page
# - Projects
# - Admin
# - APIs
```

### Step 7: Push to Main (If Everything Looks Good)
```bash
# Push to remote main
git push origin main

# If you need to force push (DANGEROUS - only if necessary):
# git push origin main --force-with-lease
```

### Step 8: Monitor Deployment
```bash
# Watch your deployment logs
# Check for errors
# Verify health endpoints
# Test production site
```

---

## 🛡️ Safety Strategies

### Strategy 1: Feature Flags
If you're adding new features, use feature flags:
```typescript
// In your code
if (process.env.ENABLE_NEW_FEATURE === 'true') {
  // New feature code
}
```

### Strategy 2: Gradual Rollout
- Deploy to staging first
- Test thoroughly
- Then deploy to production
- Monitor closely

### Strategy 3: Database Migrations
```bash
# Always test migrations first
# 1. Backup production database
# 2. Test migration on copy
# 3. Create rollback script
# 4. Run migration during low-traffic period
```

### Strategy 4: Rollback Plan
Always have a rollback plan:
```bash
# If something breaks:
git revert HEAD
git push origin main

# Or rollback to previous commit:
git reset --hard <previous-commit-hash>
git push origin main --force-with-lease
```

---

## 🚨 Red Flags - DON'T PUSH IF:

- ❌ Build fails
- ❌ Tests fail
- ❌ Linter errors
- ❌ TypeScript errors
- ❌ Database migration not tested
- ❌ Breaking changes not documented
- ❌ Secrets in code
- ❌ Debug code left in
- ❌ Console.logs everywhere
- ❌ Untested features
- ❌ No rollback plan

---

## ✅ Green Lights - SAFE TO PUSH IF:

- ✅ All checks pass
- ✅ Tested locally
- ✅ Database migrations tested
- ✅ No breaking changes (or documented)
- ✅ Documentation updated
- ✅ Team notified
- ✅ Rollback plan exists
- ✅ Feature flags for new features
- ✅ Environment variables documented

---

## 📝 Pre-Push Checklist Template

Copy this and check each item:

```
[ ] npm run build passes
[ ] npm run lint passes
[ ] npx tsc --noEmit passes
[ ] npx prisma format passes
[ ] npm run test:all passes (automated tests)
[ ] OR manual testing:
  [ ] Dev server starts without errors
  [ ] Home page loads correctly
  [ ] Projects page works
  [ ] Admin dashboard accessible
  [ ] API endpoints respond
  [ ] No console errors
  [ ] No hydration errors
[ ] Database migrations tested (if any)
[ ] Environment variables documented
[ ] No secrets in code
[ ] Breaking changes documented
[ ] CHANGELOG updated
[ ] Team notified (if needed)
[ ] Rollback plan exists
[ ] Backup branch created
[ ] Changes reviewed
```

---

## 🔄 Alternative: Pull Request Workflow

If you want extra safety, use PR workflow:

```bash
# 1. Push dev branch
git push origin dev

# 2. Create Pull Request on Git platform
# - Review changes
# - Get approval
# - Run CI/CD checks

# 3. Merge PR to main (platform handles it)
```

---

## 🆘 Emergency Rollback

If production breaks after push:

### Quick Rollback
```bash
# 1. Revert the merge commit
git revert -m 1 <merge-commit-hash>
git push origin main

# 2. Or reset to previous state
git reset --hard <previous-commit>
git push origin main --force-with-lease
```

### Database Rollback
```bash
# If you ran migrations, roll them back:
npx prisma migrate resolve --rolled-back <migration-name>

# Or restore from backup
```

---

## 📞 Need Help?

If unsure:
1. **Don't push** - better safe than sorry
2. Test more thoroughly
3. Ask for code review
4. Use staging environment first
5. Create a PR for review

---

## 🎯 Best Practices

1. **Always test locally first**
2. **Use feature flags for new features**
3. **Test database migrations on copies**
4. **Document everything**
5. **Have a rollback plan**
6. **Monitor after deployment**
7. **Deploy during low-traffic periods**
8. **Keep main branch stable**

---

**Remember**: It's better to delay a push than to break production! 🛡️