Development
Deprecation and Migration
Manages deprecation and migration. Use when removing old systems, APIs, or features, or when migrating users from one implementation to another.
Manages deprecation and migration. Use when removing old systems, APIs, or features, or when migrating users from one implementation to another.
Code is a liability, not an asset. Every line of code has ongoing maintenance cost.
Every line of code has ongoing cost: tests, documentation, security patches, dependency updates, and mental overhead. When the same functionality can be provided with less code — the old code should go.
With enough users, every observable behavior becomes depended on — including bugs, timing quirks, and undocumented side effects. Deprecation requires active migration, not just announcement.
When building something new, ask: "How would we remove this in 3 years?"
Before deprecating anything, answer these questions:
1. Does this system still provide unique value?
→ If yes, maintain it. If no, proceed.
2. How many users/consumers depend on it?
→ Quantify the migration scope.
3. Does a replacement exist?
→ If no, build the replacement first. Don't deprecate without an alternative.
4. What's the migration cost for each consumer?
→ If trivially automated, do it. If manual and high-effort, weigh against maintenance cost.
5. What's the ongoing maintenance cost of NOT deprecating?
→ Security risk, engineer time, opportunity cost of complexity.
| Type | When to Use | Mechanism | |------|-------------|-----------| | Advisory | Migration is optional, old system is stable | Warnings, documentation, nudges | | Compulsory | Old system has security issues, blocks progress | Hard deadline with migration tooling |
Default to advisory. Use compulsory only when the maintenance cost or risk justifies forcing migration.
Don't deprecate without a working alternative. The replacement must:
## Deprecation Notice: OldService
**Status:** Deprecated as of 2025-03-01
**Replacement:** NewService (see migration guide below)
**Removal date:** Advisory — no hard deadline yet
**Reason:** OldService requires manual scaling and lacks observability.
### Migration Guide
1. Replace `import { client } from 'old-service'` with `import { client } from 'new-service'`
2. Update configuration (see examples below)
3. Run the migration verification script: `npx migrate-check`
Migrate consumers one at a time, not all at once:
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
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.
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.
class LegacyTaskService implements OldTaskAPI {
constructor(private newService: NewTaskService) {}
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:
function getTaskService(userId: string): TaskService {
if (featureFlags.isEnabled('new-task-service', { userId })) {
return new NewTaskService();
}
return new LegacyTaskService();
}
Zombie code is code that nobody owns but everybody depends on. Signs:
Response: Either assign an owner and maintain it properly, or deprecate it with a concrete migration plan.
After completing a deprecation: