portfolio/SAFE_PUSH_TO_MAIN.md

🚀 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 ✅

# 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 ✅

# 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 ✅

# 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 ✅

# 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

git checkout dev
git pull origin dev  # Get latest changes

Step 2: Final Verification

# Clean build
rm -rf .next node_modules/.cache
npm install
npm run build

# Should complete without errors

Step 3: Review Your Changes

# 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)

# 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)

# 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

# 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)

# 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

# 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:

// 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

# 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:

# 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:

# 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

# 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

# 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! 🛡️