itsual Deprecation and Migration
Overview
Removing things is often harder than adding them. Do it deliberately with communication, dual-running, and clear timelines.
When to Use
- Deprecating an API, feature, or configuration
- Major version upgrades with breaking changes
- Migrating data or traffic from an old system to a new one
- Cleaning up legacy code paths that still have callers
Core Process
- Inventory – Who/what still depends on the old path?
- Announce – Communicate deprecation with timeline and migration guide.
- Dual-run – Support both old and new during a transition window when possible.
- Migrate – Provide tools, docs, or automated migration where feasible.
- Monitor – Track remaining usage of the old path.
- Remove – Only after usage is near zero or the deadline is enforced.
- Clean up – Delete code, docs, and feature flags related to the old path.
Principles
- Prefer soft deprecation + warnings before hard removal
- Make the new path strictly better or clearly necessary
- Automate migration when the cost is justified
- Never surprise production users with sudden breakage
Verification
- Migration path is documented and tested
- Remaining usage is measurable
- Rollback or extension of the timeline is possible if needed