325 lines
6.7 KiB
Markdown
325 lines
6.7 KiB
Markdown
# 🚀 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! 🛡️
|