--- title: "Aligning Cross-SDK Changes" url: https://develop.sentry.dev/sdk/getting-started/playbooks/coordination/aligning-cross-sdk-changes/ --- # Aligning Cross-SDK Changes 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/coordination/aligning-cross-sdk-changes.md#changelog) ## [Overview](https://develop.sentry.dev/sdk/getting-started/playbooks/coordination/aligning-cross-sdk-changes.md#overview) 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](https://develop.sentry.dev/sdk/getting-started/standards/coordination-maintenance.md#cross-sdk-coordination) — coordination requirements and process * [Managing Linear Projects](https://develop.sentry.dev/sdk/getting-started/playbooks/coordination/managing-linear-projects.md) — how to set up and run each per-SDK project created in step 5 * [Planning and Scoping standard](https://develop.sentry.dev/sdk/getting-started/standards/planning-scoping.md) — design-first gate, risk identification, and project naming requirements * [Semantic conventions process](https://develop.sentry.dev/sdk/getting-started/standards/api-architecture.md#semantic-conventions-process) — process for new attributes * [Deprecating an API](https://develop.sentry.dev/sdk/getting-started/playbooks/sdk-lifecycle/deprecating-an-api.md) — related playbook for API changes * [Deprecating an SDK](https://develop.sentry.dev/sdk/getting-started/playbooks/sdk-lifecycle/deprecating-an-sdk.md) — related playbook for full SDK deprecation *** ## [Steps](https://develop.sentry.dev/sdk/getting-started/playbooks/coordination/aligning-cross-sdk-changes.md#steps) #### [1. Write a proposal](https://develop.sentry.dev/sdk/getting-started/playbooks/coordination/aligning-cross-sdk-changes.md#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 * Timeline * Open questions An RFC or initiative proposal is a design document and triggers the [Design-First Gate](https://develop.sentry.dev/sdk/getting-started/standards/planning-scoping.md#design-first-gate) standard. It **MUST** also include a risk section per the [Risk Identification](https://develop.sentry.dev/sdk/getting-started/standards/planning-scoping.md#risk-identification) standard. #### [2. Allow cross-SDK review period](https://develop.sentry.dev/sdk/getting-started/playbooks/coordination/aligning-cross-sdk-changes.md#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 #### [3. Land semantic conventions first (if needed)](https://develop.sentry.dev/sdk/getting-started/playbooks/coordination/aligning-cross-sdk-changes.md#3-land-semantic-conventions-first-if-needed) If the change involves new attributes, you **MUST** land the sentry-conventions PR first ([Semantic conventions process](https://develop.sentry.dev/sdk/getting-started/standards/api-architecture.md#semantic-conventions-process)). After the conventions PR is approved, you **MUST** wait 3 business days before implementing in any SDK. This grace period allows teams to review the final conventions and raise concerns. #### [4. Agree on sequencing](https://develop.sentry.dev/sdk/getting-started/playbooks/coordination/aligning-cross-sdk-changes.md#4-agree-on-sequencing) 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 The choice **SHOULD** be documented in the proposal and agreed upon by all teams. #### [5. Create a Linear sub-initiative for SDK alignment](https://develop.sentry.dev/sdk/getting-started/playbooks/coordination/aligning-cross-sdk-changes.md#5-create-a-linear-sub-initiative-for-sdk-alignment) Any change or enhancement requiring alignment across multiple SDKs **MUST** be tracked as a sub-initiative in Linear, even if the change is small. 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](https://develop.sentry.dev/sdk/getting-started/standards/planning-scoping.md#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 * Each project **MUST** contain at least one issue with the **same title and description** as the project * Additional issues **MAY** be added as needed but **SHOULD** remain within the scope of the alignment effort This approach ensures accurate per-team progress tracking while maintaining visibility of the overall alignment effort. ##### [If the change affects SDK users: Create a public issue](https://develop.sentry.dev/sdk/getting-started/playbooks/coordination/aligning-cross-sdk-changes.md#if-the-change-affects-sdk-users-create-a-public-issue) 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 #### [6. Implement in each SDK independently](https://develop.sentry.dev/sdk/getting-started/playbooks/coordination/aligning-cross-sdk-changes.md#6-implement-in-each-sdk-independently) Each team **MUST** follow their own PR process ([Opening a PR](https://develop.sentry.dev/sdk/getting-started/playbooks/development/opening-a-pr.md), [Reviewing a PR](https://develop.sentry.dev/sdk/getting-started/playbooks/development/reviewing-a-pr.md)). The Linear projects provide visibility, but each SDK maintains its own standards and timeline. You **SHOULD** use the [`sentry-sdk-skills:sdk-feature-implementation`](https://github.com/getsentry/sdk-skills?tab=readme-ov-file#available-skills) skill to spawn parallel agents that create draft PRs across all target SDK repos. The skill uses the Linear context gathered in step 5 and handles CI monitoring across repos. If not using the skill, each SDK team implements independently. #### [7. Coordinate documentation](https://develop.sentry.dev/sdk/getting-started/playbooks/coordination/aligning-cross-sdk-changes.md#7-coordinate-documentation) 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)](https://develop.sentry.dev/sdk/getting-started/playbooks/coordination/aligning-cross-sdk-changes.md#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 * Process refinements This helps improve future cross-SDK coordination. ## [Referenced Standards](https://develop.sentry.dev/sdk/getting-started/playbooks/coordination/aligning-cross-sdk-changes.md#referenced-standards) * [Cross-SDK Coordination standard](https://develop.sentry.dev/sdk/getting-started/standards/coordination-maintenance.md#cross-sdk-coordination) — coordination process and requirements * [Design-First Gate](https://develop.sentry.dev/sdk/getting-started/standards/planning-scoping.md#design-first-gate) — RFC/proposal triggers this gate; must be complete before implementation * [Risk Identification](https://develop.sentry.dev/sdk/getting-started/standards/planning-scoping.md#risk-identification) — risk section required in the proposal; high risks block implementation start * [Project Naming](https://develop.sentry.dev/sdk/getting-started/standards/planning-scoping.md#project-naming) — `[Effort name] [SDK name]` format required for per-SDK projects * [Managing Linear Projects](https://develop.sentry.dev/sdk/getting-started/playbooks/coordination/managing-linear-projects.md) — how to set up and run each per-SDK project * [Semantic conventions process](https://develop.sentry.dev/sdk/getting-started/standards/api-architecture.md#semantic-conventions-process) — process for landing new attribute conventions *** | Version | Date | Summary | | ------- | ---------- | --------------------------------------------------------------------------------------------------------------------- | | `1.0.0` | 2026-02-23 | Initial playbook — cross-SDK coordination with Linear sub-initiatives, review periods, and documentation coordination |