From a1de82284bf0aed6a3b750c3446f8625d9e6e1a0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Johannes=20Daxb=C3=B6ck?= Date: Wed, 18 Feb 2026 14:09:47 +0100 Subject: [PATCH 01/10] add api-architecture.mdx --- .../standards/api-architecture.mdx | 122 ++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 develop-docs/sdk/getting-started/standards/api-architecture.mdx diff --git a/develop-docs/sdk/getting-started/standards/api-architecture.mdx b/develop-docs/sdk/getting-started/standards/api-architecture.mdx new file mode 100644 index 00000000000000..f2185e93692c69 --- /dev/null +++ b/develop-docs/sdk/getting-started/standards/api-architecture.mdx @@ -0,0 +1,122 @@ +--- +title: API and Architecture +sidebar_order: 4 +--- + +## Public API change approval gate + +#### Rule + +Any change to public API surface (add, change, deprecate, remove) requires senior/lead approval. "Public API" = anything a user can call, import, or reference. If in doubt, search public repos for usage. + +#### Enforcement + +CI API surface snapshot diffs (where feasible). Human review gate (senior approval). + +#### Suggested skill(s) + +- [`sentry-skills:code-review`](https://github.com/getsentry/skills?tab=readme-ov-file#available-skills) — flags API changes for escalation. + +#### Per-SDK override + +Yes — detection mechanisms are language-specific. Approval requirement is universal. + +--- + +## Server-side vs. SDK-side decision gate + +#### Rule + +New processing/transformation logic defaults to server-side. SDK-side requires justification: must happen before network, requires platform API, latency sensitivity, offline scenarios. + +#### Enforcement + +Human review. AGENTS.md instruction. + +#### Suggested skill(s) + +— + +#### Per-SDK override + +No — the default is universal. Justifications are SDK-specific. + +--- + +## Semantic conventions process + +#### Rule + +New attributes must first be defined in sentry-conventions. Process: PR to sentry-conventions → code owner approval → 3 business day wait → SDK implementation. + +#### Enforcement + +CI validation where feasible. Human review. + +#### Suggested skill(s) + +— + +#### Per-SDK override + +No. + +--- + +## Breaking change process + +#### Rule + +Breaking changes follow the [breaking changes playbook](../playbooks/breaking-changes): accumulate in next major version only, require deprecation period in prior version, migration guide with copy-pastable examples, changelog with `BREAKING CHANGE:` notation. Test migration guide with an LLM. + +#### Enforcement + +Commit footer `BREAKING CHANGE:` triggers CI checks. Human review. Breaking changes in non-major branches are CI-blocked. + +#### Suggested skill(s) + +- [`sentry-skills:code-review`](https://github.com/getsentry/skills?tab=readme-ov-file#available-skills) + +#### Per-SDK override + +Deprecation period timelines can vary. Process is universal. + +--- + +## Deprecation lifecycle + +#### Rule + +Standardized stages: 1) Announce: deprecation warning + changelog + docs + migration guide (minor release), 2) Maintain: deprecated API works for at least one minor release cycle, 3) Remove: next major version only. Deprecation warnings must include: replacement, code example, docs link. + +#### Enforcement + +Human review. CI checks deprecated APIs still have passing tests. + +#### Suggested skill(s) + +— + +#### Per-SDK override + +Minimum period can be extended. Stages are universal. + +--- + +## SDK-side logic must not break on server changes + +#### Rule + +SDKs must be resilient to unexpected server responses: unknown fields, missing fields, new enum values, rate limiting. Ignore unknown categories/dimensions rather than erroring. + +#### Enforcement + +Integration tests for degraded-server scenarios. Human review. + +#### Suggested skill(s) + +— + +#### Per-SDK override + +Specific tests vary. Principle is universal. \ No newline at end of file From 5e027e4d7b721fbbfd7e055ca15790f4e62094ca Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Johannes=20Daxb=C3=B6ck?= Date: Wed, 18 Feb 2026 16:01:49 +0100 Subject: [PATCH 02/10] update standard - Created new StatusBadge component (Yes/No indicators) - Expanded all rules with detailed requirements and rationale - Converted process descriptions to bullet lists and numbered steps - Reordered sections to prioritize architectural decisions first - Added links to related documentation (commit message standards, sentry-conventions) - Wording clarity tweaks --- .../standards/api-architecture.mdx | 88 +++++++++++++------ src/components/statusBadge/index.tsx | 14 +++ src/components/statusBadge/style.module.scss | 26 ++++++ src/mdxComponents.ts | 2 + 4 files changed, 102 insertions(+), 28 deletions(-) create mode 100644 src/components/statusBadge/index.tsx create mode 100644 src/components/statusBadge/style.module.scss diff --git a/develop-docs/sdk/getting-started/standards/api-architecture.mdx b/develop-docs/sdk/getting-started/standards/api-architecture.mdx index f2185e93692c69..5c46bc719bba58 100644 --- a/develop-docs/sdk/getting-started/standards/api-architecture.mdx +++ b/develop-docs/sdk/getting-started/standards/api-architecture.mdx @@ -3,35 +3,41 @@ title: API and Architecture sidebar_order: 4 --- -## Public API change approval gate +## Server-side (Relay) vs. SDK-side decision gate #### Rule -Any change to public API surface (add, change, deprecate, remove) requires senior/lead approval. "Public API" = anything a user can call, import, or reference. If in doubt, search public repos for usage. +New processing or transformation logic must default to server-side (Relay). + +Logic should only be implemented in the SDK if it must run before data leaves the customer's application (e.g., user-controlled filtering like `before_send_*`), requires access to platform-specific APIs, is strictly latency-sensitive, or must function in offline scenarios. + +Transformations of data that has already been collected should be handled in Relay. This ensures consistency across SDK versions and avoids duplicating logic in clients that may remain in use indefinitely. #### Enforcement -CI API surface snapshot diffs (where feasible). Human review gate (senior approval). +* AGENTS.md instruction +* Human review #### Suggested skill(s) -- [`sentry-skills:code-review`](https://github.com/getsentry/skills?tab=readme-ov-file#available-skills) — flags API changes for escalation. +— #### Per-SDK override -Yes — detection mechanisms are language-specific. Approval requirement is universal. + The default is universal. Justifications are SDK-specific. --- -## Server-side vs. SDK-side decision gate +## SDK-side logic must not break on server changes #### Rule -New processing/transformation logic defaults to server-side. SDK-side requires justification: must happen before network, requires platform API, latency sensitivity, offline scenarios. +SDKs typically outlive individual API versions, so forward compatibility is essential to prevent ecosystem breakage. They must remain resilient to evolving server responses, including additional fields, missing optional fields, new enum values, and rate limiting. They must not fail due to additive changes. Unknown fields, categories, or dimensions should be safely ignored rather than causing errors. #### Enforcement -Human review. AGENTS.md instruction. +* Integration tests for degraded-server scenarios +* Human review #### Suggested skill(s) @@ -39,79 +45,105 @@ Human review. AGENTS.md instruction. #### Per-SDK override -No — the default is universal. Justifications are SDK-specific. + Specific tests vary. Principle is universal. --- -## Semantic conventions process +## Public API change approval gate #### Rule -New attributes must first be defined in sentry-conventions. Process: PR to sentry-conventions → code owner approval → 3 business day wait → SDK implementation. +Any change to public API surface (add, change, deprecate, remove) requires @sdk-leads approval. Public API includes anything a user can call, import, configure, subclass, or otherwise reference. If there is any doubt whether something is public, check for usage in public repositories. When still unsure, treat it as public. #### Enforcement -CI validation where feasible. Human review. +* CI API surface snapshot diffs (where feasible) +* Human review gate (senior approval) #### Suggested skill(s) -— +* [`sentry-skills:code-review`](https://github.com/getsentry/skills/blob/main/plugins/sentry-skills/skills/code-review/SKILL.md) — flags API changes for escalation. #### Per-SDK override -No. + Detection mechanisms are language-specific. Approval requirement is universal. --- -## Breaking change process +## Semantic conventions process #### Rule -Breaking changes follow the [breaking changes playbook](../playbooks/breaking-changes): accumulate in next major version only, require deprecation period in prior version, migration guide with copy-pastable examples, changelog with `BREAKING CHANGE:` notation. Test migration guide with an LLM. +New attributes must first be defined in [sentry-conventions](https://github.com/getsentry/sentry-conventions). +Process: +1. PR to sentry-conventions +2. code owner approval +3. 3 business day minimum wait +4. SDK implementation #### Enforcement -Commit footer `BREAKING CHANGE:` triggers CI checks. Human review. Breaking changes in non-major branches are CI-blocked. +* CI validation where feasible +* Human review #### Suggested skill(s) -- [`sentry-skills:code-review`](https://github.com/getsentry/skills?tab=readme-ov-file#available-skills) +— #### Per-SDK override -Deprecation period timelines can vary. Process is universal. + --- -## Deprecation lifecycle +## Breaking change process #### Rule -Standardized stages: 1) Announce: deprecation warning + changelog + docs + migration guide (minor release), 2) Maintain: deprecated API works for at least one minor release cycle, 3) Remove: next major version only. Deprecation warnings must include: replacement, code example, docs link. +Breaking changes must follow the [breaking changes playbook](../playbooks/breaking-changes). + +Breaking changes may only ship in a major version. They must not ship in minor versions. Opt-in previews are allowed in minor versions. + +A deprecation period is required in a prior minor version, during which dual behavior is allowed to support migration. + +Every breaking change must include: +* A migration guide with copy-pastable examples +* A changelog entry using the BREAKING CHANGE: notation +* Validation of the migration guide using an LLM to ensure it is clear and complete #### Enforcement -Human review. CI checks deprecated APIs still have passing tests. +* [Commit footer BREAKING CHANGE:](../../../engineering-practices/commit-messages/#footer) triggers CI checks +* Breaking changes in non-major branches are CI-blocked +* Human review. #### Suggested skill(s) -— +* [`sentry-skills:code-review`](https://github.com/getsentry/skills?tab=readme-ov-file#available-skills) #### Per-SDK override -Minimum period can be extended. Stages are universal. + Deprecation period timelines can vary. Process is universal. --- -## SDK-side logic must not break on server changes +## Deprecation lifecycle #### Rule -SDKs must be resilient to unexpected server responses: unknown fields, missing fields, new enum values, rate limiting. Ignore unknown categories/dimensions rather than erroring. +All deprecations of public APIs, user-facing integrations, and supported platform or framework versions follow three stages: + +1. Announce the deprecation in a minor release with a runtime warning (where possible), updated changelog and documentation, and a migration guide. Warnings must include the replacement, a code example, and a link to the migration docs. +2. The deprecated surface must remain fully functional for at least one subsequent minor release (e.g., deprecated in X.Y, still supported in X.(Y+1)). +3. Removal may occur only in the next major release (X+1.0). + +Dropping support for platforms or frameworks requires announcement in a minor release and removal in the next major release. +Deprecating an entire SDK is never silent. It requires sound reasoning about customer impact, a public announcement, updated documentation, a clear support timeline and advance EOL notice . #### Enforcement -Integration tests for degraded-server scenarios. Human review. +* CI checks deprecated APIs still have passing tests +* Human review #### Suggested skill(s) @@ -119,4 +151,4 @@ Integration tests for degraded-server scenarios. Human review. #### Per-SDK override -Specific tests vary. Principle is universal. \ No newline at end of file + Minimum period can be extended. Stages are universal. diff --git a/src/components/statusBadge/index.tsx b/src/components/statusBadge/index.tsx new file mode 100644 index 00000000000000..cf8a49ef39e446 --- /dev/null +++ b/src/components/statusBadge/index.tsx @@ -0,0 +1,14 @@ +import styles from './style.module.scss'; + +type StatusType = 'yes' | 'no'; + +interface StatusBadgeProps { + type: StatusType; +} + +export function StatusBadge({type}: StatusBadgeProps) { + const label = type === 'yes' ? 'Yes' : 'No'; + const typeClass = type === 'yes' ? styles.yesBadge : styles.noBadge; + + return {label}; +} diff --git a/src/components/statusBadge/style.module.scss b/src/components/statusBadge/style.module.scss new file mode 100644 index 00000000000000..d8a4f2d4775600 --- /dev/null +++ b/src/components/statusBadge/style.module.scss @@ -0,0 +1,26 @@ +// Base badge styles +.yesBadge, +.noBadge { + display: inline-block; + font-weight: 600; + line-height: 1; + white-space: nowrap; + padding: 0.25rem 0.5rem; + font-size: 0.875rem; + border-radius: 0.25rem; + margin-right: 0.5rem; +} + +// Yes variant - green +.yesBadge { + background-color: rgb(220, 252, 231); + color: rgb(22, 101, 52); + border: 1px solid rgb(134, 239, 172); +} + +// No variant - subtle red +.noBadge { + background-color: rgb(254, 226, 226); + color: rgb(153, 27, 27); + border: 1px solid rgb(252, 165, 165); +} diff --git a/src/mdxComponents.ts b/src/mdxComponents.ts index e19489ab366408..508cc8c9b14448 100644 --- a/src/mdxComponents.ts +++ b/src/mdxComponents.ts @@ -55,6 +55,7 @@ import { SplitSectionCode, SplitSectionText, } from './components/splitLayout'; +import {StatusBadge} from './components/statusBadge'; import {StepComponent, StepConnector} from './components/stepConnector'; import {TableOfContents} from './components/tableOfContents'; import {VersionRequirement} from './components/version-requirement'; @@ -118,6 +119,7 @@ export function mdxComponents( SplitSection, SplitSectionText, SplitSectionCode, + StatusBadge, StepComponent, StepConnector, VimeoEmbed, From 21acc5478b33a8608108e9bf0965abc9eedfbfef Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Johannes=20Daxb=C3=B6ck?= Date: Wed, 18 Feb 2026 16:01:52 +0100 Subject: [PATCH 03/10] Update .gitignore --- .gitignore | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index 99a60f5573c75f..b4a772505d0062 100644 --- a/.gitignore +++ b/.gitignore @@ -98,4 +98,5 @@ yalc.lock /public/doctree-dev.json # Claude Code local files -.claude/settings.local.json \ No newline at end of file +.claude/settings.local.json +mise.toml From 71f255bc80f9f3f33083c8295117b64609ec9e63 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Johannes=20Daxb=C3=B6ck?= Date: Wed, 18 Feb 2026 16:10:57 +0100 Subject: [PATCH 04/10] simplify deprecation policy --- .../getting-started/standards/api-architecture.mdx | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/develop-docs/sdk/getting-started/standards/api-architecture.mdx b/develop-docs/sdk/getting-started/standards/api-architecture.mdx index 5c46bc719bba58..4b558bd6053b85 100644 --- a/develop-docs/sdk/getting-started/standards/api-architecture.mdx +++ b/develop-docs/sdk/getting-started/standards/api-architecture.mdx @@ -131,14 +131,12 @@ Every breaking change must include: #### Rule -All deprecations of public APIs, user-facing integrations, and supported platform or framework versions follow three stages: +All deprecations of public APIs, user-facing integrations, and supported platforms or frameworks follow three stages: +1. Announce in a minor release with a runtime warning (where possible), updated changelog and documentation, and a migration guide. Warnings must include the replacement, a code example, and a link to the migration docs. +2. Keep the deprecated surface fully functional for at least one subsequent minor release (e.g., deprecated in X.Y, still supported in X.(Y+1)). +3. Remove only in the next major release (X+1.0). -1. Announce the deprecation in a minor release with a runtime warning (where possible), updated changelog and documentation, and a migration guide. Warnings must include the replacement, a code example, and a link to the migration docs. -2. The deprecated surface must remain fully functional for at least one subsequent minor release (e.g., deprecated in X.Y, still supported in X.(Y+1)). -3. Removal may occur only in the next major release (X+1.0). - -Dropping support for platforms or frameworks requires announcement in a minor release and removal in the next major release. -Deprecating an entire SDK is never silent. It requires sound reasoning about customer impact, a public announcement, updated documentation, a clear support timeline and advance EOL notice . +Deprecating an entire SDK must never be silent. It requires clear customer impact analysis, a public announcement, updated documentation, a defined support timeline, and advance EOL notice. #### Enforcement From 5d888009d54332ac516f589bd02b0c541cde7634 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Johannes=20Daxb=C3=B6ck?= Date: Wed, 18 Feb 2026 16:14:50 +0100 Subject: [PATCH 05/10] Fix code review skill link --- develop-docs/sdk/getting-started/standards/api-architecture.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/develop-docs/sdk/getting-started/standards/api-architecture.mdx b/develop-docs/sdk/getting-started/standards/api-architecture.mdx index 4b558bd6053b85..3dc031daf0ea1d 100644 --- a/develop-docs/sdk/getting-started/standards/api-architecture.mdx +++ b/develop-docs/sdk/getting-started/standards/api-architecture.mdx @@ -119,7 +119,7 @@ Every breaking change must include: #### Suggested skill(s) -* [`sentry-skills:code-review`](https://github.com/getsentry/skills?tab=readme-ov-file#available-skills) +* [`sentry-skills:code-review`](https://github.com/getsentry/skills/blob/main/plugins/sentry-skills/skills/code-review/SKILL.md) #### Per-SDK override From 87aae540a56fd7f0a0d337744c8622845fb0d302 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Johannes=20Daxb=C3=B6ck?= Date: Wed, 18 Feb 2026 16:15:37 +0100 Subject: [PATCH 06/10] re-fix skill link . link to overview in case file location changes --- .../sdk/getting-started/standards/api-architecture.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/develop-docs/sdk/getting-started/standards/api-architecture.mdx b/develop-docs/sdk/getting-started/standards/api-architecture.mdx index 3dc031daf0ea1d..7c560d25bb6613 100644 --- a/develop-docs/sdk/getting-started/standards/api-architecture.mdx +++ b/develop-docs/sdk/getting-started/standards/api-architecture.mdx @@ -62,7 +62,7 @@ Any change to public API surface (add, change, deprecate, remove) requires @sdk- #### Suggested skill(s) -* [`sentry-skills:code-review`](https://github.com/getsentry/skills/blob/main/plugins/sentry-skills/skills/code-review/SKILL.md) — flags API changes for escalation. +* [`sentry-skills:code-review`](https://github.com/getsentry/skills#available-skills) — flags API changes for escalation. #### Per-SDK override @@ -119,7 +119,7 @@ Every breaking change must include: #### Suggested skill(s) -* [`sentry-skills:code-review`](https://github.com/getsentry/skills/blob/main/plugins/sentry-skills/skills/code-review/SKILL.md) +* [`sentry-skills:code-review`](https://github.com/getsentry/skills#available-skills) #### Per-SDK override From da361b25dfe0618f1818c6b97f4a677019c50691 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Johannes=20Daxb=C3=B6ck?= Date: Wed, 18 Feb 2026 16:45:42 +0100 Subject: [PATCH 07/10] add empty playbook :) --- develop-docs/sdk/getting-started/playbooks/breaking-changes.mdx | 0 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 develop-docs/sdk/getting-started/playbooks/breaking-changes.mdx diff --git a/develop-docs/sdk/getting-started/playbooks/breaking-changes.mdx b/develop-docs/sdk/getting-started/playbooks/breaking-changes.mdx new file mode 100644 index 00000000000000..e69de29bb2d1d6 From f97e04ce4c1563c4d63c36af0d99b81d11e259ef Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Johannes=20Daxb=C3=B6ck?= Date: Wed, 18 Feb 2026 16:48:22 +0100 Subject: [PATCH 08/10] link breaking changes to existing doc --- develop-docs/sdk/getting-started/standards/api-architecture.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/develop-docs/sdk/getting-started/standards/api-architecture.mdx b/develop-docs/sdk/getting-started/standards/api-architecture.mdx index 7c560d25bb6613..6b1311317b1430 100644 --- a/develop-docs/sdk/getting-started/standards/api-architecture.mdx +++ b/develop-docs/sdk/getting-started/standards/api-architecture.mdx @@ -100,7 +100,7 @@ Process: #### Rule -Breaking changes must follow the [breaking changes playbook](../playbooks/breaking-changes). +Breaking changes must follow the [breaking changes playbook](../../processes/breaking_changes/). Breaking changes may only ship in a major version. They must not ship in minor versions. Opt-in previews are allowed in minor versions. From dc72afd31e825766402fbc40c4b3d944b83cda68 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Johannes=20Daxb=C3=B6ck?= <114897+dingsdax@users.noreply.github.com> Date: Wed, 18 Feb 2026 16:49:32 +0100 Subject: [PATCH 09/10] Apply suggestion from @stephanie-anderson Co-authored-by: Stephanie Anderson --- develop-docs/sdk/getting-started/standards/api-architecture.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/develop-docs/sdk/getting-started/standards/api-architecture.mdx b/develop-docs/sdk/getting-started/standards/api-architecture.mdx index 6b1311317b1430..2e2c2e689c43c3 100644 --- a/develop-docs/sdk/getting-started/standards/api-architecture.mdx +++ b/develop-docs/sdk/getting-started/standards/api-architecture.mdx @@ -113,7 +113,7 @@ Every breaking change must include: #### Enforcement -* [Commit footer BREAKING CHANGE:](../../../engineering-practices/commit-messages/#footer) triggers CI checks +* [Commit footer BREAKING CHANGE:](/engineering-practices/commit-messages/#footer) triggers CI checks * Breaking changes in non-major branches are CI-blocked * Human review. From 34f1f86eff800cb9bb996afbeb938d3330b763e8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Johannes=20Daxb=C3=B6ck?= Date: Wed, 18 Feb 2026 17:07:42 +0100 Subject: [PATCH 10/10] remove link to breaking changes --- develop-docs/sdk/getting-started/standards/api-architecture.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/develop-docs/sdk/getting-started/standards/api-architecture.mdx b/develop-docs/sdk/getting-started/standards/api-architecture.mdx index 2e2c2e689c43c3..ae76b600f47ba1 100644 --- a/develop-docs/sdk/getting-started/standards/api-architecture.mdx +++ b/develop-docs/sdk/getting-started/standards/api-architecture.mdx @@ -100,7 +100,7 @@ Process: #### Rule -Breaking changes must follow the [breaking changes playbook](../../processes/breaking_changes/). +Breaking changes must follow the breaking changes playbook. Breaking changes may only ship in a major version. They must not ship in minor versions. Opt-in previews are allowed in minor versions.