Migrating Code

Core Principles

1. Never break production - Backward compatible until fully rolled out
2. Small, reversible steps - Each step independently deployable
3. Test at every stage - Before, during, and after
4. Have rollback ready - Always

Migration Checklist

- [ ] Pre-Migration: Read changelog, identify breaking changes, ensure test coverage
- [ ] During: Small steps, test each, monitor errors, rollback ready
- [ ] Post: Verify tests, check metrics, remove scaffolding, update docs

Database Schema

Safe Patterns

API Migrations

Deprecation Process

1. Add deprecation warnings to old endpoints
2. Document migration path
3. Set and communicate sunset date
4. Monitor usage
5. Remove after usage drops

{
  "data": {},
  "_warnings": [{
    "code": "DEPRECATED_ENDPOINT",
    "message": "Use /api/v2/users instead",
    "sunset": "2025-06-01"
  }]
}

Framework Upgrades

1. Upgrade to latest minor first - Get deprecation warnings
2. Fix warnings - Before major upgrade
3. One major at a time - Don't batch
4. Test after each step

Adapter Pattern for Library Swaps

// Wrap library usage
// lib/date.ts
import moment from 'moment';
export const formatDate = (date: Date, format: string) =>
  moment(date).format(format);

// Migration: just change the adapter
import { format } from 'date-fns';
export const formatDate = (date: Date, fmt: string) =>
  format(date, fmt);

Gradual Rollout

if (featureFlags.useNewSystem) {
  return newService.process(order);
} else {
  return legacyService.process(order);
}

Common Pitfalls

• Big bang migrations
• No rollback plans
• Skipping dual-write phase
• Single large data transactions
• Removing old code before new is proven

• Small, reversible steps
• Test rollback procedures
• Batch large data migrations
• Keep old paths until new verified