docs(sdk): deprecating-an-api playbook (#16510)

This playbook guides SDK maintainers through the complete API
deprecation lifecycle, covering:
- **Multi-SDK coordination**: Check if cross-SDK rollout process is
needed
- **Deprecation announcement requirements**:
- In-code warnings with replacement API, migration examples, and docs
links
- Changelog entries explaining migration path
- Migration guides with copy-pastable before/after examples
- AI tool validation to ensure migration guides are actionable
- **Maintenance period**: Deprecated APIs must remain functional for at
least one full minor release cycle with passing tests
- **Removal process**: APIs can only be removed in major versions with
`BREAKING CHANGE:` commit footer
- **Communication**: Changelog, docs updates, and optional blog posts
for high-impact deprecations
The playbook ensures users have clear migration paths and sufficient
time to adapt before breaking changes occur.
Part of the broader SDK playbooks migration initiative.
## IS YOUR CHANGE URGENT?
- [ ] Urgent deadline (GA date, etc.):
- [ ] Other deadline:
- [x] None: Not urgent, can wait up to 1 week+
## SLA
- Teamwork makes the dream work, so please add a reviewer to your PRs.
- Please give the docs team up to 1 week to review your PR unless you've
added an urgent due date to it.
Thanks in advance for your help!
## PRE-MERGE CHECKLIST
- [ ] Checked Vercel preview for correctness, including links
- [ ] PR was reviewed and approved by any necessary SMEs (subject matter
experts)
- [ ] PR was reviewed and approved by a member of the [Sentry docs
team](https://github.com/orgs/getsentry/teams/docs)
  Co-Authored-By: Claude <noreply@anthropic.com>

---------

Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Stephanie Anderson <stephanie.anderson@sentry.io>

Author: 3 people

develop-docs/sdk/getting-started/playbooks/cross-sdk-rollout.mdx

@@ -0,0 +1,54 @@
+---
+title: Cross-SDK Rollout
+spec_id: sdk/playbooks/cross-sdk-rollout
+spec_version: 1.0.0
+spec_status: draft
+spec_depends_on:
+  - id: sdk/getting-started/standards/coordination-maintenance
+    version: ">=1.0.0"
+  - id: sdk/getting-started/standards/api-architecture
+    version: ">=1.0.0"
+spec_changelog:
+  - version: 1.0.0
+    date: 2026-02-23
+    summary: Initial placeholder — detailed content to be added
+---
+
+<SpecRfcAlert />
+
+<SpecMeta />
+
+## Overview
+
+This playbook guides SDK teams through coordinating changes that affect multiple Sentry SDKs. It covers proposal writing, cross-team review, sequencing decisions, and coordinated rollout.
+
+**Note:** This playbook is currently a placeholder. Detailed content will be added in a future update.
+
+---
+
+## Steps
+
+#### 1. Write a proposal
+
+Create an RFC or issue describing the change, affected SDKs, rollout order, and timeline.
+
+#### 2. Cross-SDK review period
+
+Allow at least 1 week for all affected SDK teams to review and comment.
+
+#### 3. Implement with coordination
+
+Follow the [Cross-SDK Coordination Protocol](/sdk/getting-started/standards/coordination-maintenance#cross-sdk-coordination-protocol).
+
+#### 4. Track progress
+
+Create a tracking issue or project board to monitor implementation across SDKs.
+
+## Referenced Standards
+
+- [Cross-SDK Coordination Protocol](/sdk/getting-started/standards/coordination-maintenance#cross-sdk-coordination-protocol) — coordination process
+- [Semantic conventions process](/sdk/getting-started/standards/api-architecture#semantic-conventions-process) — conventions for new attributes
+
+---
+
+<SpecChangelog />

develop-docs/sdk/getting-started/playbooks/deprecating-an-api.mdx

@@ -0,0 +1,83 @@
+---
+title: Deprecating an API
+spec_id: sdk/playbooks/deprecating-an-api
+spec_version: 1.0.0
+spec_status: candidate
+spec_depends_on:
+  - id: sdk/getting-started/standards/api-architecture
+    version: ">=1.0.0"
+  - id: sdk/getting-started/standards/repository-docs
+    version: ">=1.0.0"
+  - id: sdk/getting-started/standards/coordination-maintenance
+    version: ">=1.0.0"
+spec_changelog:
+  - version: 1.0.0
+    date: 2026-02-23
+    summary: Initial playbook — API deprecation lifecycle with migration guides and multi-SDK coordination
+---
+
+<SpecRfcAlert />
+
+<SpecMeta />
+
+## 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](/sdk/getting-started/standards/api-architecture#deprecation-lifecycle) — deprecation timeline and requirements
+- [Breaking change process](/sdk/getting-started/standards/api-architecture#breaking-change-process) — process for eventual API removal
+- [Cross-SDK Rollout](/sdk/getting-started/playbooks/cross-sdk-rollout) — coordinating deprecations across multiple SDKs
+
+---
+
+## Steps
+
+#### 1. If this is a multi-SDK deprecation
+
+If the deprecation affects multiple Sentry SDKs, you **MUST** follow the [Cross-SDK Rollout](/sdk/getting-started/playbooks/cross-sdk-rollout) process first to coordinate timing and approach across SDK teams.
+
+#### 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](/sdk/getting-started/standards/repository-docs#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
+
+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
+
+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](/sdk/getting-started/standards/api-architecture#breaking-change-process))
+- Update the migration guide to reference the major version that removes it
+
+#### 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
+
+- [Deprecation lifecycle](/sdk/getting-started/standards/api-architecture#deprecation-lifecycle) — deprecation timeline requirements
+- [Breaking change process](/sdk/getting-started/standards/api-architecture#breaking-change-process) — process for API removal in major versions
+- [Documentation-with-Code](/sdk/getting-started/standards/repository-docs#documentation-with-code) — copy-pastable migration examples requirement
+- [Cross-SDK Coordination Protocol](/sdk/getting-started/standards/coordination-maintenance#cross-sdk-coordination-protocol) — coordinating multi-SDK changes
+
+---
+
+<SpecChangelog />