docs(develop-docs): Add SDK deprecation playbook (#17137)

## DESCRIBE YOUR PR

Add a new "Deprecating an SDK" playbook to the SDK Lifecycle section of
develop-docs. This covers the full lifecycle of deprecating an entire
SDK — from impact analysis through repo archival and post-EOL
documentation cleanup.

The playbook is organized into 3 phases with 13 steps:
- **Phase 1: Build the Case** — Assess industry/usage, quantify revenue
impact, identify migration paths, get approval
- **Phase 2: Execute the Deprecation** — Final release, public
announcement, close backlog, update README/docs, deprecate on package
registry, archive repo, notify stakeholders
- **Phase 3: Post-EOL Cleanup** — Documentation cleanup (noindex, draft,
redirects)

Derived from real-world Cordova and Xamarin deprecation processes,
incorporating lessons learned from both.

Also updates 5 existing pages with cross-links:
- `api-architecture.mdx` — Links the existing one-liner about SDK
deprecation to the new playbook
- `sdk-lifecycle/index.mdx` — Updated description
- `breaking-changes.mdx`, `dropping-platform-support.mdx`,
`aligning-cross-sdk-changes.mdx` — Added to Related resources

**Note:** Some files have whitespace-only changes (blank lines added
before bullet lists). These are Prettier auto-formatting corrections
applied when the files were edited — not manual changes.

## IS YOUR CHANGE URGENT?

- [ ] Urgent deadline (GA date, etc.):
- [ ] Other deadline:
- [x] None: Not urgent, can wait up to 1 week+

## 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>

Author: christophaigner

develop-docs/sdk/getting-started/playbooks/coordination/aligning-cross-sdk-changes.mdx

@@ -23,11 +23,13 @@ spec_changelog:
 This playbook guides SDK teams through coordinating changes that affect multiple Sentry SDKs. It covers proposal writing, cross-team review, semantic conventions coordination, sequencing decisions, progress tracking, and documentation coordination. By following these steps, multi-SDK rollouts will be coordinated, predictable, and minimize surprises for users.
 
 Related resources:
+
 - [Cross-SDK Coordination standard](/sdk/getting-started/standards/coordination-maintenance#cross-sdk-coordination) — coordination requirements and process
 - [Managing Linear Projects](/sdk/getting-started/playbooks/coordination/managing-linear-projects) — how to set up and run each per-SDK project created in step 5
 - [Planning and Scoping standard](/sdk/getting-started/standards/planning-scoping) — design-first gate, risk identification, and project naming requirements
 - [Semantic conventions process](/sdk/getting-started/standards/api-architecture#semantic-conventions-process) — process for new attributes
 - [Deprecating an API](/sdk/getting-started/playbooks/sdk-lifecycle/deprecating-an-api) — related playbook for API changes
+- [Deprecating an SDK](/sdk/getting-started/playbooks/sdk-lifecycle/deprecating-an-sdk) — related playbook for full SDK deprecation
 
 ---
 
@@ -36,6 +38,7 @@ Related resources:
 #### 1. Write a proposal
 
 You **MUST** create an RFC or Linear initiative describing:
+
 - What's changing and why
 - Which SDKs are affected
 - Proposed rollout order
@@ -47,6 +50,7 @@ An RFC or initiative proposal is a design document and triggers the [Design-Firs
 #### 2. Allow cross-SDK review period
 
 You **MUST** allow a minimum of 1 week for all affected SDK teams to review and comment on the proposal. This ensures all teams have time to:
+
 - Assess implementation complexity for their SDK
 - Identify platform-specific concerns
 - Propose alternative approaches if needed
@@ -62,12 +66,14 @@ After the conventions PR is approved, you **MUST** wait 3 business days before i
 Choose a rollout strategy:
 
 **Option A: By adoption/maturity (Recommended)**
+
 - Lower risk (learn from early implementations)
 - Longer timeline
 - Best for complex features or experimental changes
 - This is the default approach for most cross-SDK changes
 
 **Option B: All-at-once**
+
 - Clean story for users (feature arrives everywhere simultaneously)
 - Harder to coordinate across teams
 - Best for critical security fixes or simple changes
@@ -81,6 +87,7 @@ Any change or enhancement requiring alignment across multiple SDKs **MUST** be t
 You **SHOULD** use the [`sentry-sdk-skills:linear-initiative`](https://github.com/getsentry/sdk-skills?tab=readme-ov-file#available-skills) skill to automate the creation of the Linear sub-initiative and per-SDK projects.
 
 If not using the skill, you **MUST** manually:
+
 - Create a sub-initiative under the appropriate parent initiative in Linear
 - For each SDK team involved, create a separate **project** under this sub-initiative, named per the [Project Naming](/sdk/getting-started/standards/planning-scoping#project-naming) standard (`[Effort name] [SDK name]`)
 - You **MUST NOT** use a single project with multiple issues, as the project is only completed once **all** SDK teams finish their work
@@ -94,6 +101,7 @@ This approach ensures accurate per-team progress tracking while maintaining visi
 If the change or alignment is of interest to SDK users or customers, you **MAY** create one public GitHub issue to track community interest and questions.
 
 This public issue **MAY** be omitted for changes that are:
+
 - Too trivial to warrant public communication
 - Should not be disclosed to customers or the public yet
 - Internal implementation details without user-facing impact
@@ -111,13 +119,15 @@ If not using the skill, each SDK team implements independently.
 Documentation PRs **SHOULD** ship together or in clear sequence — not piecemeal. Users **MUST NOT** see docs for a change that hasn't reached their SDK yet.
 
 Options:
+
 - Hold all docs PRs until all SDKs ship
 - Use platform-specific content that only appears when the SDK supports it
 - Clearly label which SDK versions support the feature
 
 #### 8. Conduct async retro after full rollout (optional)
 
 After all SDKs have shipped, you **SHOULD** conduct an async retrospective documenting:
+
 - What worked well
 - What to improve for next time
 - Unexpected challenges

develop-docs/sdk/getting-started/playbooks/sdk-lifecycle/breaking-changes.mdx

@@ -23,9 +23,11 @@ spec_changelog:
 This playbook guides SDK maintainers through deciding whether a change is breaking and, if so, how to ship it with minimum friction for users. It covers classifying changes, estimating product impact, planning the release, and writing migration guidance. By following these steps, users will have clear migration paths and the SDK update experience will be as smooth as possible.
 
 Related resources:
+
 - [Breaking change process](/sdk/getting-started/standards/api-architecture#breaking-and-deprecation) — when a major release is required and what every breaking change must include
 - [Deprecation lifecycle](/sdk/getting-started/standards/api-architecture#breaking-and-deprecation) — the deprecation stages and timelines
 - [Deprecating an API](/sdk/getting-started/playbooks/sdk-lifecycle/deprecating-an-api) — step-by-step deprecation workflow
+- [Deprecating an SDK](/sdk/getting-started/playbooks/sdk-lifecycle/deprecating-an-sdk) — full SDK deprecation process
 - [Release and Versioning](/sdk/getting-started/standards/release-versioning) — SemVer requirements and release tooling
 
 ---
@@ -39,20 +41,23 @@ Determine whether the change is breaking. If the answer is unclear after reviewi
 There are four categories of changes that warrant scrutiny:
 
 **API surface changes** — changes users need to adapt their code to:
+
 - Dropping or renaming part of the public API
 - Dropping or renaming a function argument
 - Changing an argument's type without accepting the previous type
 
 When the public/private boundary is unclear, look for evidence of external usage. Check if the API appears in user-facing docs, search public repositories for usage (e.g., via GitHub code search), or recall if you have seen it used in issue reproduction examples.
 
 **Product impact changes** — changes that alter how data appears in Sentry without requiring code changes from the user:
+
 - **Grouping** — changes to event data used by the server's grouping algorithm
 - **Dashboards** — renaming or removing span attributes users may be filtering on
 - **Alerts** — attribute changes that could cause alerts to start or stop firing
 - **Insights** — changes to metrics surfaced in the Insights module (e.g., Web or Mobile Vitals)
 - **Issue detection** — changes to span emission that influence server-side issue detection
 
 **Behavior changes** — changes that don't require code changes but significantly affect user experience:
+
 - Changes that affect the user's event or span quota (e.g., auto-enabling an integration)
 - Changes that might result in events being dropped (e.g., modifying payload trimming limits)
 

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

@@ -0,0 +1,161 @@
+---
+title: Deprecating an SDK
+spec_id: sdk/playbooks/deprecating-an-sdk
+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/coordination-maintenance
+    version: ">=1.0.0"
+spec_changelog:
+  - version: 1.0.0
+    date: 2026-03-26
+    summary: Initial playbook — full SDK deprecation lifecycle from impact analysis through repo archival and documentation cleanup
+---
+
+<SpecRfcAlert />
+
+<SpecMeta />
+
+## Overview
+
+This playbook guides SDK maintainers through deprecating an entire SDK. Unlike [deprecating an API](/sdk/getting-started/playbooks/sdk-lifecycle/deprecating-an-api) or [dropping a platform version](/sdk/getting-started/playbooks/sdk-lifecycle/dropping-platform-support), deprecating an SDK means ending all active development and eventually archiving the repository. It covers impact analysis, approval, final release, public announcement, documentation updates, package registry deprecation, repo archival, and post-EOL cleanup.
+
+Related resources:
+
+- [Deprecation lifecycle](/sdk/getting-started/standards/api-architecture#breaking-changes-and-deprecations) — deprecation timeline and requirements
+- [Documenting decisions](/sdk/getting-started/standards/coordination-maintenance#documenting-decisions) — traceability requirement for decisions
+- [Cutting a Release](/sdk/getting-started/playbooks/sdk-lifecycle/cutting-a-release) — release process for the final release
+- [Deprecating an API](/sdk/getting-started/playbooks/sdk-lifecycle/deprecating-an-api) — related playbook for API-level deprecation
+- [Dropping Platform or Language Version Support](/sdk/getting-started/playbooks/sdk-lifecycle/dropping-platform-support) — related playbook for version-level support drops
+
+Two examples of this are [sentry-cordova](https://github.com/getsentry/sentry-cordova) (archived March 2026, users migrated to Capacitor, React Native, or Flutter) and [sentry-xamarin](https://github.com/getsentry/sentry-xamarin) (archived after Xamarin reached end of life, users migrated to .NET MAUI via `sentry-dotnet`).
+
+---
+
+## Steps
+
+### Phase 1: Build the Case
+
+Before committing to a deprecation, build a clear evidence-based case that justifies the decision and identifies alternatives for affected users.
+
+#### 1. Assess industry and usage
+
+Before proposing to deprecate an SDK, you **MUST** gather and document evidence covering:
+
+- **Upstream project health**: Has the platform reached end of life? Is it still actively maintained? Has corporate sponsorship been withdrawn?
+- **Usage data**: How many orgs, DSNs, and projects actively use the SDK? Is usage growing or declining?
+- **Package download trends**: Compare the SDK's download numbers against alternatives using registry-specific statistics (e.g., [npmtrends](https://npmtrends.com/), PyPI Stats, NuGet Gallery, Maven Central)
+
+Use internal data tools (analytics dashboards, usage queries) to gather org and DSN counts.
+
+#### 2. Quantify revenue impact
+
+You **MUST** calculate the true at-risk revenue, not the total ARR of orgs that happen to use the SDK:
+
+- Identify orgs that use the SDK exclusively (no other Sentry SDKs) — this is the true at-risk segment
+- Compare ongoing maintenance cost against the revenue the SDK protects
+- Document the opportunity cost — what could the same engineering time deliver if invested in higher-growth SDKs?
+
+#### 3. Identify migration paths
+
+You **MUST** confirm that affected users have a viable path forward:
+
+- List alternative SDKs (successor SDK, competing platforms with Sentry support)
+- Verify that an upstream migration path exists (e.g., framework-provided migration guides)
+- Determine whether Sentry-specific migration guidance is needed or if upstream guides are sufficient
+
+#### 4. Get approval
+
+Work with the engineering manager responsible for the SDK to get approval. The decision **MUST** be documented in Linear or GitHub per the [Documenting decisions](/sdk/getting-started/standards/coordination-maintenance#documenting-decisions) standard.
+
+---
+
+### Phase 2: Execute the Deprecation
+
+Once approved, execute these steps in sequence. The order matters — cut the final release before announcing, and announce before archiving.
+
+#### 5. Cut a final release
+
+You **SHOULD** cut a final release with up-to-date dependencies to give users a stable baseline. Follow the [Cutting a Release](/sdk/getting-started/playbooks/sdk-lifecycle/cutting-a-release) playbook. Even if the release contains no new features, a clean final release is better than leaving users on a months-old version. The changelog **SHOULD** note that this is the final planned release and that the SDK is entering deprecation.
+
+#### 6. Create a public deprecation announcement
+
+You **MUST** open a GitHub issue on the SDK repo explaining:
+
+- That the SDK is being deprecated
+- Why (upstream EOL, low usage, maintenance burden — keep it factual)
+- What alternatives users should migrate to, with links
+- Any remaining support timeline (e.g., security-only fixes for N months)
+
+Pin this issue so it's visible to anyone who visits the repo. This is the single canonical place for users to understand the deprecation and ask questions.
+
+#### 7. Close backlog with consistent messaging
+
+You **MUST** close all open issues and PRs with a uniform note that references the announcement issue and names the alternatives. Every issue and PR **MUST** get this note — don't leave some closed without explanation. Use `state_reason: not_planned` where supported by the platform.
+
+#### 8. Update the README
+
+You **MUST** add a prominent deprecation notice at the top of the README. On GitHub, use the `> [!IMPORTANT]` callout:
+
+```markdown
+> [!IMPORTANT]
+> This SDK is no longer maintained. We recommend migrating to
+> [Alternative A](link), [Alternative B](link), or [Alternative C](link).
+```
+
+The notice **MUST** name the successor SDKs with links.
+
+#### 9. Update documentation
+
+You **MUST** add a deprecation alert to **all** pages under the SDK's documentation tree on the docs site:
+
+```mdx
+<Alert level="warning" title="Deprecation Notice">
+  This SDK is no longer maintained. If you are starting a new project or
+  planning a migration, consider using [Alternative A](/path), [Alternative
+  B](/path), or [Alternative C](/path) instead.
+</Alert>
+```
+
+Don't delete documentation pages immediately — users on existing versions still need them.
+
+#### 10. Deprecate on the package registry
+
+You **MUST** mark the package as deprecated on its public registry so users see the notice at install time. The deprecation message **MUST** name the successor SDKs. Not every registry supports formal deprecation — where no mechanism exists, update the project description and README instead.
+
+#### 11. Archive the GitHub repo
+
+Archive the repository to make it read-only. Update the repo description to reflect the deprecation.
+
+#### 12. Notify internal stakeholders
+
+You **MUST** notify support, customer-facing, and go-to-market teams so they can proactively communicate with affected customers. High-impact deprecations **SHOULD** include a blog post or public announcement to reach users who don't regularly check changelogs.
+
+---
+
+### Phase 3: Post-EOL Cleanup
+
+After the SDK has been archived for a while, clean up the documentation footprint.
+
+#### 13. Clean up documentation
+
+After a grace period (6–12 months post-archival), you **SHOULD**:
+
+- Set `noindex: true` on the SDK's doc pages to remove them from search engine indexing
+- Set `draft: true` to hide them from site navigation
+- Keep content accessible via direct URL for users still on old versions
+- Consider adding redirects from the SDK's doc URLs to the successor SDK or a migration page
+
+---
+
+## Referenced Standards
+
+- [Deprecation lifecycle](/sdk/getting-started/standards/api-architecture#breaking-changes-and-deprecations) — deprecation timeline and stages
+- [Documenting decisions](/sdk/getting-started/standards/coordination-maintenance#documenting-decisions) — traceability requirement
+- [Cutting a Release](/sdk/getting-started/playbooks/sdk-lifecycle/cutting-a-release) — release process for the final release
+
+---
+
+<SpecChangelog />

develop-docs/sdk/getting-started/playbooks/sdk-lifecycle/dropping-platform-support.mdx

@@ -23,9 +23,11 @@ spec_changelog:
 This playbook guides SDK maintainers through dropping support for a platform or language version in a way that minimizes user disruption. It covers evidence gathering, deprecation announcements, maintenance periods, and eventual removal. By following these steps, users will have clear migration paths and sufficient notice before breaking changes occur.
 
 Related resources:
+
 - [Platform/language version support policy](/sdk/getting-started/standards/coordination-maintenance#platformlanguage-version-support-policy) — support policy and requirements
 - [Breaking change process](/sdk/getting-started/standards/api-architecture#breaking-and-deprecation) — process for removal in major versions
 - [Deprecation lifecycle](/sdk/getting-started/standards/api-architecture#breaking-and-deprecation) — deprecation timeline
+- [Deprecating an SDK](/sdk/getting-started/playbooks/sdk-lifecycle/deprecating-an-sdk) — when deprecating the entire SDK, not just a platform version
 
 ---
 

develop-docs/sdk/getting-started/playbooks/sdk-lifecycle/index.mdx

@@ -1,6 +1,6 @@
 ---
 title: SDK Lifecycle
-description: Releasing, deprecating APIs, dropping platform support, and introducing breaking changes.
+description: Releasing, deprecating APIs and SDKs, dropping platform support, and introducing breaking changes.
 sidebar_order: 4
 ---
 

develop-docs/sdk/getting-started/standards/api-architecture.mdx

@@ -101,7 +101,7 @@ Deprecations of public APIs, integrations, and supported platforms follow three
 2. **Keep it working** for at least one subsequent minor release (e.g., deprecated in X.Y, still functional in X.(Y+1)).
 3. **Remove** only in the next major release (X+1.0).
 
-Deprecating an entire SDK is a bigger deal — it requires customer impact analysis, a public announcement, updated documentation, a defined support timeline, and advance EOL notice.
+Deprecating an entire SDK follows a separate, more involved process — see the [Deprecating an SDK](/sdk/getting-started/playbooks/sdk-lifecycle/deprecating-an-sdk) playbook.
 
 ### Breaking changes