docs(sdk): Rewrite API and Architecture spec for readability#17014
Merged
stephanie-anderson merged 5 commits intomasterfrom Mar 18, 2026
Merged
docs(sdk): Rewrite API and Architecture spec for readability#17014stephanie-anderson merged 5 commits intomasterfrom
stephanie-anderson merged 5 commits intomasterfrom
Conversation
Replace rigid Rule/Enforcement/Per-SDK override template with natural prose. Add intro framing the philosophy, merge breaking changes and deprecation lifecycle into one section, remove enforcement boilerplate, and promote spec status to stable. Co-Authored-By: Claude <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
![sentry[bot]](https://avatars.githubusercontent.com/in/12637?s=60&v=4){kind=small}
dingsdax
reviewed
Mar 18, 2026
| ## Server-side (Relay) vs. SDK implementation | ||
|
|
||
| New processing or transformation logic **MUST** default to server-side (Relay). | ||
| When deciding where new logic should live, default to server-side (Relay). Processing data in Relay keeps behavior consistent across SDK versions and avoids duplicating logic in clients that may remain deployed indefinitely. |
Contributor
There was a problem hiding this comment.
Is Relay our only entry point? If not we should make this a little bit more open imho.
Contributor
Author
There was a problem hiding this comment.
It is, yes - we only send envelopes to the /envelope endpoint in relay
dingsdax
reviewed
Mar 18, 2026
| Breaking changes and deprecations are closely linked — every breaking change goes through a deprecation period first. Both follow a lifecycle designed to give users time and guidance to migrate. | ||
|
|
||
| Breaking changes **MUST** follow the [breaking changes playbook](/sdk/getting-started/playbooks/sdk-lifecycle/breaking-changes). | ||
| ### Deprecation lifecycle |
Contributor
There was a problem hiding this comment.
I wonder if we really need this here or just in the playbook.
Contributor
Author
There was a problem hiding this comment.
Do you mean the intro?
Contributor
Author
There was a problem hiding this comment.
I'll do the playbooks review after the standards - so I might do this in a separate PR in a few hours
dingsdax
reviewed
Mar 18, 2026
|
|
||
| New attributes **MUST** first be defined in [sentry-conventions](https://github.com/getsentry/sentry-conventions). | ||
| Process: | ||
| 1. Open a PR to sentry-conventions |
Contributor
There was a problem hiding this comment.
I wonder if we should move this out of standard, it reads like process, maybe extracting into a Sentry conventions playbook? I would add that changes to attributes are considered a breaking change and that conventions should be treated like public API, wdyt?
Add that convention attributes should be treated like public API and that changes to existing attributes are breaking changes. Document the sentry-conventions deprecation lifecycle (backfill → normalize). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Update playbook links to match new section IDs after spec rewrite. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
dingsdax
approved these changes
Mar 18, 2026
stephanie-anderson
added a commit
that referenced
this pull request
Mar 18, 2026
Rewrites the API and Architecture standards page to be more human-friendly: - Add intro paragraph framing the core philosophy - Replace rigid Rule/Enforcement/Per-SDK override template with natural prose - Merge breaking changes and deprecation lifecycle into one cohesive section - Remove enforcement boilerplate and StatusBadge components - Add contextual "why" before rules instead of dropping straight into requirements - Thin out RFC keyword density — keep MUST/REQUIRES for hard rules, plain language elsewhere - Promote spec status to stable --------- Co-authored-by: Claude <noreply@anthropic.com>
constantinius
pushed a commit
that referenced
this pull request
Mar 20, 2026
Rewrites the API and Architecture standards page to be more human-friendly: - Add intro paragraph framing the core philosophy - Replace rigid Rule/Enforcement/Per-SDK override template with natural prose - Merge breaking changes and deprecation lifecycle into one cohesive section - Remove enforcement boilerplate and StatusBadge components - Add contextual "why" before rules instead of dropping straight into requirements - Thin out RFC keyword density — keep MUST/REQUIRES for hard rules, plain language elsewhere - Promote spec status to stable --------- Co-authored-by: Claude <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Rewrites the API and Architecture standards page to be more human-friendly: