deprecation-and-migration

Every line of code has ongoing cost: it needs tests, documentation, security patches, dependency updates, and mental overhead for anyone working nearby. The value of code is the functionality it provides, not the code itself. When the same functionality can be provided with less code, less complexity, or better abstractions — the old code should go.

With enough users, every observable behavior becomes depended on — including bugs, timing quirks, and undocumented side effects. This is why deprecation requires active migration, not just announcement. Users can't "just switch" when they depend on behaviors the replacement doesn't replicate.

When building something new, ask: "How would we remove this in 3 years?" Systems designed with clean interfaces, feature flags, and minimal surface area are easier to deprecate than systems that leak implementation details everywhere.

Don't deprecate without a working alternative. The replacement must:

• Cover all critical use cases of the old system
• Have documentation and migration guides
• Be proven in production (not just "theoretically better")

Migrate consumers one at a time, not all at once. For each consumer:

1. Identify all touchpoints with the deprecated system
2. Update to use the replacement
3. Verify behavior matches (tests, integration checks)
4. Remove references to the old system
5. Confirm no regressions

The Churn Rule: If you own the infrastructure being deprecated, you are responsible for migrating your users — or providing backward-compatible updates that require no migration. Don't announce deprecation and leave users to figure it out.

Only after all consumers have migrated:

1. Verify zero active usage (metrics, logs, dependency analysis)
2. Remove the code
3. Remove associated tests, documentation, and configuration
4. Remove the deprecation notices
5. Celebrate — removing code is an achievement

Run old and new systems in parallel. Route traffic incrementally from old to new. When the old system handles 0% of traffic, remove it.

Phase 1: New system handles 0%, old handles 100%
Phase 2: New system handles 10% (canary)
Phase 3: New system handles 50%
Phase 4: New system handles 100%, old system idle
Phase 5: Remove old system

Create an adapter that translates calls from the old interface to the new implementation. Consumers keep using the old interface while you migrate the backend.

// Adapter: old interface, new implementation
class LegacyTaskService implements OldTaskAPI {
  constructor(private newService: NewTaskService) {}

  // Old method signature, delegates to new implementation
  getTask(id: number): OldTask {
    const task = this.newService.findById(String(id));
    return this.toOldFormat(task);
  }
}

Use feature flags to switch consumers from old to new system one at a time:

function getTaskService(userId: string): TaskService {
  if (featureFlags.isEnabled('new-task-service', { userId })) {
    return new NewTaskService();
  }
  return new LegacyTaskService();
}

A schema change is the riskiest migration because the data is the one thing you cannot roll back by reverting a deploy. The failure mode is coupling the schema change to the code change: rename a column in the same release that starts using the new name, and during the rollout window — when old and new code run at once — one of them is querying a column that doesn't exist. The fix is to never change a column in place. Migrate in additive phases so old and new code are both valid at every step.

EXPAND ──────────────→ MIGRATE ──────────────→ CONTRACT
add the new column,    backfill existing rows,  once no code reads the
nullable, alongside    dual-write old+new from  old column, drop it in
the old one            the app                  a later, separate deploy

Worked example — renaming name to full_name:

1. Expand. Add full_name as nullable. Deploy. (Old code ignores it; nothing breaks.)
2. Dual-write. App writes both name and full_name on every insert/update. Deploy.
3. Backfill. Copy name → full_name for existing rows, in batches, so you don't lock the table.
4. Switch reads. Point the app at full_name, keep writing both. Deploy and bake.
5. Contract. Stop writing name, then — in a separate, later deploy — drop the column.

Each step is independently deployable and reversible: if step 4 misbehaves, roll the code back and full_name is still being populated. Treat each phase as a thin vertical slice — see the incremental-implementation skill.

Rules:

• Additive first, destructive last and alone. Adds (new nullable column, new table, new index) are safe in any deploy; drops and renames get their own deploy after no code references the old shape.
• Every migration has a tested down path. A migration you can't reverse is a deploy you can't roll back. Write and run the down before merging.
• Backfill in batches, off the hot path. A single UPDATE over millions of rows locks the table; chunk it and throttle.
• Build large indexes without blocking writes (e.g. Postgres CREATE INDEX CONCURRENTLY).
• Decouple from code by feature flag when the cutover is risky, exactly as in the Feature Flag Migration pattern above.