Deprecation
Marking a feature as discouraged and scheduled for removal, while it keeps working for a transition period so its users have time to move away.
Also known as: Deprecated, Deprecation Policy, Sunsetting, End of Life, Feature Deprecation
Category: Software Development
Tags: software-development, software-engineering, maintainability, compatibility, api-design, change-management
Explanation
Deprecation is the polite way to remove something. Instead of deleting a feature overnight, you announce that it's on its way out, you point to the replacement, and you leave it working for a defined period. Users get time to migrate. Maintainers get a path to remove old code.
**A good deprecation has**:
- **A clear signal**: An annotation in the code, a compiler or runtime warning, a notice in the documentation, a response header in an API
- **A replacement**: Tell people what to use instead. A deprecation with no alternative is just a threat
- **A migration path**: A guide, or better, a tool that does the migration
- **A timeline**: A removal date or version. "Deprecated" with no date means "here forever"
- **Usage data**: Know who still uses the feature, and contact them
- **A real removal**: The last step is the one that most often never happens
**Techniques**:
- **Warnings**: At compile time or at run time. Useful, but people learn to ignore them
- **HTTP headers**: The `Deprecation` and `Sunset` response headers announce the status and the end date of an API
- **Brownouts**: Switch the feature off for short planned periods before the final date. It finds the users who missed every announcement
- **Advisory vs. compulsory**: Advisory deprecation asks users to migrate. Compulsory deprecation sets a deadline, and works best when the team that deprecates also does most of the migration work
**Why it's hard**:
- Migration costs the users and benefits the maintainers. The incentives point in opposite directions
- With enough users, somebody depends on every behavior (see Hyrum's Law). Some will only find out on the day of removal
- Features that stay deprecated for years teach everyone that deprecation warnings don't mean anything
- Removing too fast, or too often, destroys trust in the platform
**Why it's worth it**:
Code is a liability. Every old feature you keep costs maintenance, security exposure and complexity in every future change. A system that can't remove anything ends up unable to change at all. Planning for removal when you design a feature makes the future deprecation much cheaper.
Related Concepts
← Back to all concepts