Deprecating an API
This playbook guides SDK maintainers through deprecating an API in a way that minimizes user disruption. It covers deprecation announcements, migration guide creation, maintenance periods, and eventual removal. By following these steps, users will have clear migration paths and sufficient time to adapt.
Related resources:
- Deprecation lifecycle — deprecation timeline and requirements
- Breaking change process — process for eventual API removal
- Aligning Cross-SDK Changes — coordinating deprecations across multiple SDKs
If the deprecation affects multiple Sentry SDKs, you MUST follow the Aligning Cross-SDK Changes process first to coordinate timing and approach across SDK teams.
In the minor release where the API is deprecated, you MUST:
- Add a deprecation warning in code that includes:
- What to use instead (replacement API)
- A code example of the migration
- A link to documentation
- Add a changelog entry explaining the deprecation and the migration path
- Open a docs PR with a migration guide containing copy-pastable before/after examples (Documentation-with-Code)
- Test the migration guide by having an AI tool follow it — if the tool can't complete the migration, rewrite the guide
The deprecated API MUST stay functional for at least one full minor release cycle. Tests for the deprecated code path MUST remain and continue to pass during this period.
This gives users time to migrate without breaking their applications immediately.
When removing the deprecated API in a major version, you MUST:
- Remove the API and its tests
- Include
BREAKING CHANGE:in the commit footer (Breaking change process) - Update the migration guide to reference the major version that removes it
You MUST provide:
- Changelog entry documenting the removal
- Docs update referencing the version where removal occurred
For high-impact deprecations, you SHOULD consider a blog post or announcement to reach users who may not regularly check changelogs.
- Deprecation lifecycle — deprecation timeline requirements
- Breaking change process — process for API removal in major versions
- Documentation-with-Code — copy-pastable migration examples requirement
- Cross-SDK Coordination standard — coordinating multi-SDK changes
| Version | Date | Summary |
|---|---|---|
1.0.0 | 2026-02-23 | Initial playbook — API deprecation lifecycle with migration guides and multi-SDK coordination |
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").