Deprecation
dep-reh-KAY-shun
The process of phasing out a feature, API, or product version with advance notice so users can migrate to alternatives.
Deprecation is the planned retirement of a feature, API version, or product. When something is deprecated, it still works but is no longer recommended. Users get advance notice and a migration path to the replacement.
Deprecation is how responsible software companies manage change. Instead of removing a feature overnight and breaking customer workflows, they announce the deprecation, provide documentation for migrating, maintain the deprecated feature for a transition period, and then remove it.
The deprecation timeline matters. API deprecations in the developer tool world typically provide 6-12 months of notice. Shorter timelines anger customers. Longer timelines slow down the team. The right timeline depends on how deeply integrated the deprecated feature is in customer workflows. Announcements go out through release notes and direct outreach.
Examples
A company deprecates an API version.
API v1 is deprecated. The changelog announces: 'v1 will continue to work for 12 months. v2 is available today. Migration guide: [link]. After March 2027, v1 endpoints will return 410 Gone.' The team emails every customer using v1.
A feature is deprecated in favor of a new approach.
The old dashboard builder is deprecated. The new one has better performance and more features. Existing dashboards continue to work but show a banner: 'This dashboard uses the legacy builder. Click here to migrate.' The team tracks migration progress weekly.
A customer pushes back on a deprecation timeline.
An enterprise customer relies heavily on the deprecated API. They need 18 months to migrate, not 12. The PM extends the deadline for enterprise customers while keeping the 12-month timeline for everyone else.
In practice
Read more on the blog
Frequently asked questions
How much notice should you give before deprecating a feature?
Minimum 6 months for major features or APIs. 12 months is standard for heavily-used APIs. Minor features may only need 3 months. The timeline should reflect how much work migration requires for your customers.
What is the difference between deprecated and removed?
Deprecated means it still works but is no longer recommended or actively developed. Removed means it no longer works at all. Deprecation is the warning period before removal.
Related terms
The official release of a product or feature to all customers, indicating it is production-ready and fully supported.
The second major version of a product or feature, typically a significant overhaul that incorporates learnings from V1.
A pre-release version of a product or feature made available to a limited audience for testing and feedback before general availability.
Want the complete playbook?
Picks and Shovels is the definitive guide to developer marketing. Amazon #1 bestseller with practical strategies from 30 years of marketing to developers.