---
title: "Deprecating an API"
url: https://develop.sentry.dev/sdk/getting-started/playbooks/sdk-lifecycle/deprecating-an-api/
---

# Deprecating an API

This document uses key words such as "MUST", "SHOULD", and "MAY" as defined in

<!-- -->

[RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) to indicate requirement levels.

Statuscandidate

Version`1.0.0`[(changelog)](https://develop.sentry.dev/sdk/getting-started/playbooks/sdk-lifecycle/deprecating-an-api.md#changelog)

## [Overview](https://develop.sentry.dev/sdk/getting-started/playbooks/sdk-lifecycle/deprecating-an-api.md#overview)

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](https://develop.sentry.dev/sdk/getting-started/standards/api-architecture.md#breaking-and-deprecation) — deprecation timeline and requirements
* [Breaking change process](https://develop.sentry.dev/sdk/getting-started/standards/api-architecture.md#breaking-and-deprecation) — process for eventual API removal
* [Aligning Cross-SDK Changes](https://develop.sentry.dev/sdk/getting-started/playbooks/coordination/aligning-cross-sdk-changes.md) — coordinating deprecations across multiple SDKs

***

## [Steps](https://develop.sentry.dev/sdk/getting-started/playbooks/sdk-lifecycle/deprecating-an-api.md#steps)

#### [1. If this is a multi-SDK deprecation](https://develop.sentry.dev/sdk/getting-started/playbooks/sdk-lifecycle/deprecating-an-api.md#1-if-this-is-a-multi-sdk-deprecation)

If the deprecation affects multiple Sentry SDKs, you **MUST** follow the [Aligning Cross-SDK Changes](https://develop.sentry.dev/sdk/getting-started/playbooks/coordination/aligning-cross-sdk-changes.md) process first to coordinate timing and approach across SDK teams.

#### [2. Announce in a minor release](https://develop.sentry.dev/sdk/getting-started/playbooks/sdk-lifecycle/deprecating-an-api.md#2-announce-in-a-minor-release)

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](https://develop.sentry.dev/sdk/getting-started/standards/repository-docs.md#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

#### [3. Maintain the deprecated API](https://develop.sentry.dev/sdk/getting-started/playbooks/sdk-lifecycle/deprecating-an-api.md#3-maintain-the-deprecated-api)

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.

#### [4. Remove in the next major version only](https://develop.sentry.dev/sdk/getting-started/playbooks/sdk-lifecycle/deprecating-an-api.md#4-remove-in-the-next-major-version-only)

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](https://develop.sentry.dev/sdk/getting-started/standards/api-architecture.md#breaking-and-deprecation))
* Update the migration guide to reference the major version that removes it

#### [5. Communicate](https://develop.sentry.dev/sdk/getting-started/playbooks/sdk-lifecycle/deprecating-an-api.md#5-communicate)

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.

## [Referenced Standards](https://develop.sentry.dev/sdk/getting-started/playbooks/sdk-lifecycle/deprecating-an-api.md#referenced-standards)

* [Deprecation lifecycle](https://develop.sentry.dev/sdk/getting-started/standards/api-architecture.md#breaking-and-deprecation) — deprecation timeline requirements
* [Breaking change process](https://develop.sentry.dev/sdk/getting-started/standards/api-architecture.md#breaking-and-deprecation) — process for API removal in major versions
* [Documentation-with-Code](https://develop.sentry.dev/sdk/getting-started/standards/repository-docs.md#documentation-with-code) — copy-pastable migration examples requirement
* [Cross-SDK Coordination standard](https://develop.sentry.dev/sdk/getting-started/standards/coordination-maintenance.md#cross-sdk-coordination) — 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 |