Skip to main content

Development Workflow Guide

Overview​

This guide outlines the proper development workflow: Local → Staging → Production (Main)

🎯 Workflow Principles​

  1. Never push directly to main - Always test in staging first
  2. Test locally first - Catch errors before deploying
  3. Deploy to staging - Verify in staging environment
  4. Merge to main - Only after staging is verified

📋 Development Workflow​

Step 1: Local Development​

# 1. Create a feature branch from staging (or main if staging doesn't exist)
git checkout staging  # or main
git pull origin staging
git checkout -b feature/my-feature-name

# 2. Make your changes
# ... edit files ...

# 3. Test locally
cd toto-app  # or toto-bo
npm install
npm run dev

# 4. Run tests and linting
npm test
npm run lint
npm run build  # Verify build succeeds

# 5. Commit changes
git add .
git commit -m "feat: Description of changes"

Step 2: Deploy to Staging​

# 1. Push feature branch
git push origin feature/my-feature-name

# 2. Merge to staging branch
git checkout staging
git pull origin staging
git merge feature/my-feature-name
git push origin staging

# 3. Deploy to staging (automatic via GitHub Actions, or manual)
# Manual deployment:
cd toto-app
firebase use toto-f9d2f-stg  # or toto-bo-stg for toto-bo
firebase deploy --only apphosting

# 4. Verify deployment
# - Check Firebase Console for rollout status
# - Test the application in staging
# - Check logs for errors

Step 3: Test in Staging​

  1. Check Deployment Status

    • Go to Firebase Console → App Hosting → Rollouts
    • Verify rollout succeeded
    • Check for any errors

  2. Test Functionality

    • Test the new features
    • Verify existing features still work
    • Check for console errors
    • Test on different devices/browsers

  3. Check Logs

    # View recent logs
    firebase functions:log --project toto-f9d2f-stg

    # Or via GCP Console
    # Cloud Run → Logs

  4. Run Smoke Tests (if available)

    npm run test:smoke:staging

Step 4: Merge to Main (Production)​

Only proceed if staging is fully verified!

# 1. Merge staging to main
git checkout main
git pull origin main
git merge staging
git push origin main

# 2. Deployment to production happens automatically via GitHub Actions
# Or deploy manually:
cd toto-app
firebase use toto-f9d2f  # or toto-bo for toto-bo
firebase deploy --only apphosting

# 3. Monitor deployment
# - Check Firebase Console for rollout status
# - Monitor logs for errors
# - Verify production application works

🚨 Handling Failed Deployments​

If Staging Deployment Fails​

  1. Check Deployment Logs

    # List recent rollouts
    firebase apphosting:rollouts:list --project toto-f9d2f-stg

    # Get rollout details
    firebase apphosting:rollouts:get ROLLOUT_ID --project toto-f9d2f-stg

  2. Fix Issues Locally

    • Reproduce the error locally
    • Fix the issue
    • Test locally
    • Commit and push again

  3. Redeploy to Staging

    • After fixes are verified locally
    • Push to staging again
    • Verify deployment succeeds

If Production Deployment Fails​

  1. Immediate Actions

    • Check if previous version is still running
    • Review deployment logs
    • Check Firebase Console for errors

  2. Rollback if Needed

    # List previous rollouts
    firebase apphosting:rollouts:list --project toto-f9d2f

    # Rollback to previous version
    firebase apphosting:rollouts:rollback ROLLOUT_ID --project toto-f9d2f

  3. Fix and Retry

    • Fix the issue in staging first
    • Verify staging deployment succeeds
    • Then merge to main again

📝 Branch Strategy​

main (production)
  └── staging (staging environment)
      └── feature/my-feature (feature branches)

Branch Naming Conventions​

  • Feature branches: feature/description or fix/description
  • Staging branch: staging
  • Production branch: main

🔍 Pre-Deployment Checklist​

Before deploying to staging:

  • Code builds successfully (npm run build)
  • All tests pass (npm test)
  • Linting passes (npm run lint)
  • No TypeScript errors
  • Application runs locally without errors
  • Environment variables are configured
  • Secrets are set in Firebase Console
  • apphosting.yaml is correct

Before merging to main:

  • Staging deployment succeeded
  • Staging functionality verified
  • No errors in staging logs
  • Smoke tests pass (if available)
  • Team review completed (if required)

🛠️ Useful Commands​

Local Development​

# Start development server
npm run dev

# Run tests
npm test
npm run test:coverage

# Lint code
npm run lint
npm run lint:fix

# Build for production
npm run build

# Test production build locally
npm start

Deployment​

# Check current Firebase project
firebase use

# List available projects
firebase projects:list

# Switch to staging
firebase use toto-f9d2f-stg

# Switch to production
firebase use toto-f9d2f

# Deploy
firebase deploy --only apphosting

# Check deployment status
firebase apphosting:rollouts:list

Debugging​

# View logs
firebase functions:log

# Check rollout status
firebase apphosting:rollouts:list --limit 5

# Get rollout details
firebase apphosting:rollouts:get ROLLOUT_ID

📚 Related Documentation​