From eb334a06f2d00d831c2ffe806d8b4ac620f43692 Mon Sep 17 00:00:00 2001 From: "sentry-junior[bot]" <264270552+sentry-junior[bot]@users.noreply.github.com> Date: Mon, 19 Oct 2026 14:45:34 +0000 Subject: [PATCH 1/9] docs(sdk): Add Writing SDK Specs page and legacy spec notice Add a meta-spec for writing SDK specs: requirements only describe externally observable behavior, follow RFC 2119 Section 6, and default to SHOULD. Specs opt in with spec_guidelines frontmatter; SpecMeta shows a legacy notice on every spec that does not declare it. Co-Authored-By: Daniel Szoke <7881302+szokeasaurusrex@users.noreply.github.com> --- app/[[...path]]/page.tsx | 3 + .../standards/spec-lifecycle.mdx | 1 + .../standards/writing-specs.mdx | 100 ++++++++++++++++++ src/components/specMeta.tsx | 15 ++- 4 files changed, 118 insertions(+), 1 deletion(-) create mode 100644 develop-docs/sdk/getting-started/standards/writing-specs.mdx diff --git a/app/[[...path]]/page.tsx b/app/[[...path]]/page.tsx index e0ea91451a2b1..3e0a58223f297 100644 --- a/app/[[...path]]/page.tsx +++ b/app/[[...path]]/page.tsx @@ -76,6 +76,9 @@ function mdxComponentsForFrontMatter(frontMatter: Record) { const boundProps = { version: String(frontMatter.spec_version), status: frontMatter.spec_status, + guidelines: frontMatter.spec_guidelines + ? String(frontMatter.spec_guidelines) + : undefined, }; specOverrides.SpecMeta = function () { return ; diff --git a/develop-docs/sdk/getting-started/standards/spec-lifecycle.mdx b/develop-docs/sdk/getting-started/standards/spec-lifecycle.mdx index 2e2eb6d8ee1db..2bde3a07660af 100644 --- a/develop-docs/sdk/getting-started/standards/spec-lifecycle.mdx +++ b/develop-docs/sdk/getting-started/standards/spec-lifecycle.mdx @@ -25,6 +25,7 @@ Each spec is an MDX page with frontmatter that drives the status badge, version, | `spec_depends_on` | no | Other specs this one relies on, each `{id, version}` with a SemVer range. | | `spec_platforms` | no | Platforms the spec applies to; defaults to `all`. | | `spec_superseded_by` | no | `spec_id` of the replacement spec. Set when `deprecated`. | +| `spec_guidelines` | no | Declares conformance to [Writing SDK Specs](/sdk/getting-started/standards/writing-specs/), e.g. `writing-specs@0.1`. Specs without it show a legacy notice. | A spec's body is divided into `` blocks, each with its own `status`, a `since` version marking when its current requirements landed, and an optional `superseded_by` link. Sections **MAY** advance independently — a `stable` spec can still contain a `candidate` section that's gathering feedback. diff --git a/develop-docs/sdk/getting-started/standards/writing-specs.mdx b/develop-docs/sdk/getting-started/standards/writing-specs.mdx new file mode 100644 index 0000000000000..4738d3daf02d8 --- /dev/null +++ b/develop-docs/sdk/getting-started/standards/writing-specs.mdx @@ -0,0 +1,100 @@ +--- +title: Writing SDK Specs +description: How to write SDK specs that only require externally observable behavior and use requirement keywords sparingly. +spec_id: sdk/getting-started/standards/writing-specs +spec_version: 0.1.0 +spec_status: draft +spec_guidelines: writing-specs@0.1 +spec_changelog: + - version: 0.1.0 + date: 2026-10-19 + summary: Initial draft +sidebar_order: 0 +--- + + + + + +SDK specs define what SDKs do, not how they do it. This spec builds on [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119) and adds only what is specific to Sentry SDK specs. + +## Scope + +This spec applies to specs. Its [Legacy Specs](#legacy-specs) section also applies to SDKs that implement legacy specs. Status, versioning, and changelogs are covered by [Spec Lifecycle](/sdk/getting-started/standards/spec-lifecycle/). + +## Definitions + +- **Spec**: a page under `develop-docs/sdk/` with `spec_id` frontmatter. +- **Requirement**: a statement in a spec that uses, rather than mentions, an RFC 2119 keyword written in uppercase, such as "MUST", "SHOULD", or "MAY". +- **Non-normative content**: anything in a spec that is not a requirement. +- **Externally observable behavior**: behavior whose conformance can be determined without inspecting the implementation's internals. For an SDK, conformance is determined using only its public API, the data it sends, its calls into user code, its effects on the host application, and its responses to inputs. +- **Legacy spec**: a spec without `spec_guidelines` in its frontmatter. + +## Requirements + + + +### Keywords + +Requirement keywords have the meaning defined in RFC 2119. Keywords **SHOULD** be bold. A keyword that is mentioned rather than used **SHOULD** be put in quotes. Non-normative content **SHOULD NOT** state obligations with lowercase "must", "should", "may", or phrases such as "needs to". + + + + + +### Observable Behavior + +Requirements **MUST** only describe externally observable behavior. When a requirement is written as steps, only its observable result is required. + + + + + +### Requirement Levels + +Requirements **MUST** follow [Section 6 of RFC 2119](https://www.rfc-editor.org/rfc/rfc2119#section-6): + +> Imperatives of the type defined in this memo must be used with care and sparingly. In particular, they MUST only be used where it is actually required for interoperation or to limit behavior which has potential for causing harm (e.g., limiting retransmisssions) For example, they must not be used to try to impose a particular method on implementors where the method is not required for interoperability. + +In addition, requirements **MAY** specify an SDK's public API. Such requirements **SHOULD** allow SDKs to adapt names, signatures, and types to their platform's conventions. + +"SHOULD" is the default requirement level. "MUST" and "MUST NOT" **SHOULD** only be used where no SDK could have a valid reason to deviate. Authors **SHOULD** assume such a reason could exist unless shown otherwise. + +A requirement that most SDKs do not implement yet **SHOULD** be placed in a `draft` or `candidate` section (see [Spec Lifecycle](/sdk/getting-started/standards/spec-lifecycle/)), not weakened. + + + + + +### Structure + +A spec **SHOULD** contain, in this order: a short introduction, Scope (optional), Definitions (optional), Requirements, and Implementation Guidance (optional), followed by the changelog required by Spec Lifecycle. Non-normative content **SHOULD** be kept to a minimum and, apart from the introduction and brief examples, placed in Implementation Guidance. Implementation Guidance **SHOULD** only describe proven patterns that are not documented elsewhere. + + + + + +### Legacy Specs + +A spec that conforms to this spec **SHOULD** declare it with `spec_guidelines: writing-specs@`. A spec **MUST NOT** declare it unless the whole spec conforms. Legacy specs **SHOULD** display a notice linking to this section. + +In a legacy spec, requirements on behavior that is not externally observable are not mandatory. SDKs **SHOULD** preserve the externally observable behavior that results from them. All other requirements in a legacy spec apply as written. + + + +## Implementation Guidance + +_This section is non-normative._ + +**The black-box test.** Ask: "Could I check this against a mock transport and the public API, without opening the SDK's source?" If not, it isn't a requirement. Usually the observable intent can be kept: + +- "Use a single, centralized `ClientReports` component per client" → "Discarded events are reported in the client report of the client that discarded them." +- "Aggregate counts in a map keyed by reason and category" → "Each client report contains at most one entry per (reason, category) pair." + +**The Section 6 test.** Ask: "Is this part of the public API? If not, would Sentry reject or misread data if an SDK ignored it, would SDKs fail to work together, or would users be harmed?" If none apply, it isn't a requirement: delete it, or keep it as guidance if it is a proven pattern. If one applies, use "SHOULD" unless no SDK could have a valid reason to deviate. Outside the public API, consistency across SDKs alone is not a reason for a requirement. + +**Migrating a legacy spec.** Rewrite the observable intent as requirements, move proven guidance into Implementation Guidance, delete the rest, then add `spec_guidelines`. + +## Changelog + + diff --git a/src/components/specMeta.tsx b/src/components/specMeta.tsx index e042efcd7a78c..e0d476d3450ba 100644 --- a/src/components/specMeta.tsx +++ b/src/components/specMeta.tsx @@ -5,9 +5,11 @@ import {SPEC_STATUS_BADGE, type SpecStatus} from './specConstants'; type SpecMetaProps = { status: SpecStatus; version: string; + /** Value of the `spec_guidelines` frontmatter field, e.g. `writing-specs@0.1`. */ + guidelines?: string; }; -export function SpecMeta({version, status}: SpecMetaProps) { +export function SpecMeta({version, status, guidelines}: SpecMetaProps) { const badgeClass = SPEC_STATUS_BADGE[status]; return ( @@ -42,6 +44,17 @@ export function SpecMeta({version, status}: SpecMetaProps) { + {!guidelines && ( +

+ This spec predates the{' '} + + spec writing guidelines + {' '} + and does not follow them yet. Requirements on behavior that is not externally + observable are not mandatory, but SDKs should preserve the observable behavior + that results from them. +

+ )} ); } From 72febc8db1f0a0de264a0b3dc66f98b91d19170f Mon Sep 17 00:00:00 2001 From: "sentry-junior[bot]" <264270552+sentry-junior[bot]@users.noreply.github.com> Date: Mon, 19 Oct 2026 15:56:18 +0000 Subject: [PATCH 2/9] docs(sdk): Show followed guidelines version and exempt process specs Display the spec_guidelines value in SpecMeta, add a spec_kind: process field for playbooks and engineering standards so they are out of scope for Writing SDK Specs and show no legacy notice, and narrow the spec's scope accordingly. Co-Authored-By: Daniel Szoke <7881302+szokeasaurusrex@users.noreply.github.com> --- app/[[...path]]/page.tsx | 1 + .../aligning-cross-sdk-changes.mdx | 1 + .../coordination/managing-linear-projects.mdx | 1 + .../quarterly-cross-sdk-retro.mdx | 1 + .../playbooks/coordination/triaging.mdx | 1 + .../development/adding-a-dependency.mdx | 1 + .../development/handling-a-regression.mdx | 1 + .../handling-external-contributor-pr.mdx | 1 + .../playbooks/development/opening-a-pr.mdx | 1 + .../playbooks/development/reviewing-a-pr.mdx | 1 + .../reviewing-ai-generated-code.mdx | 1 + .../development/syncing-feature-branches.mdx | 1 + .../sdk-lifecycle/breaking-changes.mdx | 1 + .../sdk-lifecycle/cutting-a-release.mdx | 1 + .../sdk-lifecycle/deprecating-an-api.mdx | 1 + .../sdk-lifecycle/deprecating-an-sdk.mdx | 1 + .../dropping-platform-support.mdx | 1 + .../setup/setting-up-new-sdk-repo.mdx | 1 + .../setting-up-release-infrastructure.mdx | 1 + .../standards/api-architecture.mdx | 1 + .../standards/code-quality.mdx | 1 + .../standards/code-submission.mdx | 1 + .../standards/coordination-maintenance.mdx | 1 + .../standards/planning-scoping.mdx | 1 + .../standards/release-versioning.mdx | 1 + .../standards/repository-docs.mdx | 1 + .../getting-started/standards/review-ci.mdx | 1 + .../standards/spec-lifecycle.mdx | 3 +- .../standards/writing-specs.mdx | 5 ++-- src/components/specMeta.tsx | 28 +++++++++++++++---- 30 files changed, 54 insertions(+), 9 deletions(-) diff --git a/app/[[...path]]/page.tsx b/app/[[...path]]/page.tsx index 3e0a58223f297..a16fbebf4d884 100644 --- a/app/[[...path]]/page.tsx +++ b/app/[[...path]]/page.tsx @@ -79,6 +79,7 @@ function mdxComponentsForFrontMatter(frontMatter: Record) { guidelines: frontMatter.spec_guidelines ? String(frontMatter.spec_guidelines) : undefined, + kind: frontMatter.spec_kind ? String(frontMatter.spec_kind) : undefined, }; specOverrides.SpecMeta = function () { return ; diff --git a/develop-docs/sdk/getting-started/playbooks/coordination/aligning-cross-sdk-changes.mdx b/develop-docs/sdk/getting-started/playbooks/coordination/aligning-cross-sdk-changes.mdx index cfebc0c4b9e1d..aa0955c15a2bb 100644 --- a/develop-docs/sdk/getting-started/playbooks/coordination/aligning-cross-sdk-changes.mdx +++ b/develop-docs/sdk/getting-started/playbooks/coordination/aligning-cross-sdk-changes.mdx @@ -3,6 +3,7 @@ title: Aligning Cross-SDK Changes spec_id: sdk/playbooks/aligning-cross-sdk-changes spec_version: 1.0.0 spec_status: candidate +spec_kind: process spec_depends_on: - id: sdk/getting-started/standards/coordination-maintenance version: ">=1.0.0" diff --git a/develop-docs/sdk/getting-started/playbooks/coordination/managing-linear-projects.mdx b/develop-docs/sdk/getting-started/playbooks/coordination/managing-linear-projects.mdx index 49a11279bdecb..9a3d89fefd7d8 100644 --- a/develop-docs/sdk/getting-started/playbooks/coordination/managing-linear-projects.mdx +++ b/develop-docs/sdk/getting-started/playbooks/coordination/managing-linear-projects.mdx @@ -3,6 +3,7 @@ title: Project Management in Linear spec_id: sdk/playbooks/managing-linear-projects spec_version: 1.0.0 spec_status: draft +spec_kind: process spec_depends_on: - id: sdk/getting-started/standards/planning-scoping version: ">=1.0.0" diff --git a/develop-docs/sdk/getting-started/playbooks/coordination/quarterly-cross-sdk-retro.mdx b/develop-docs/sdk/getting-started/playbooks/coordination/quarterly-cross-sdk-retro.mdx index 3cacff17252db..ec4fbc45116ee 100644 --- a/develop-docs/sdk/getting-started/playbooks/coordination/quarterly-cross-sdk-retro.mdx +++ b/develop-docs/sdk/getting-started/playbooks/coordination/quarterly-cross-sdk-retro.mdx @@ -3,6 +3,7 @@ title: Quarterly Cross-SDK Retro spec_id: sdk/playbooks/quarterly-cross-sdk-retro spec_version: 1.0.0 spec_status: draft +spec_kind: process spec_depends_on: - id: sdk/getting-started/standards/coordination-maintenance version: ">=1.0.0" diff --git a/develop-docs/sdk/getting-started/playbooks/coordination/triaging.mdx b/develop-docs/sdk/getting-started/playbooks/coordination/triaging.mdx index 8692a3919a487..6ff3e92896d0f 100644 --- a/develop-docs/sdk/getting-started/playbooks/coordination/triaging.mdx +++ b/develop-docs/sdk/getting-started/playbooks/coordination/triaging.mdx @@ -3,6 +3,7 @@ title: Triaging spec_id: sdk/playbooks/triaging spec_version: 1.0.0 spec_status: candidate +spec_kind: process spec_depends_on: - id: sdk/getting-started/standards/coordination-maintenance version: ">=1.0.0" diff --git a/develop-docs/sdk/getting-started/playbooks/development/adding-a-dependency.mdx b/develop-docs/sdk/getting-started/playbooks/development/adding-a-dependency.mdx index 88618dbc89824..bc9d137e4ef86 100644 --- a/develop-docs/sdk/getting-started/playbooks/development/adding-a-dependency.mdx +++ b/develop-docs/sdk/getting-started/playbooks/development/adding-a-dependency.mdx @@ -3,6 +3,7 @@ title: Adding a Dependency spec_id: sdk/playbooks/adding-a-dependency spec_version: 1.0.0 spec_status: candidate +spec_kind: process spec_depends_on: - id: sdk/getting-started/standards/code-quality version: ">=1.0.0" diff --git a/develop-docs/sdk/getting-started/playbooks/development/handling-a-regression.mdx b/develop-docs/sdk/getting-started/playbooks/development/handling-a-regression.mdx index bcc64003f27e1..2885e2577c9ee 100644 --- a/develop-docs/sdk/getting-started/playbooks/development/handling-a-regression.mdx +++ b/develop-docs/sdk/getting-started/playbooks/development/handling-a-regression.mdx @@ -3,6 +3,7 @@ title: Handling a Regression spec_id: sdk/playbooks/handling-a-regression spec_version: 1.0.0 spec_status: candidate +spec_kind: process spec_depends_on: - id: sdk/getting-started/standards/coordination-maintenance version: ">=1.0.0" diff --git a/develop-docs/sdk/getting-started/playbooks/development/handling-external-contributor-pr.mdx b/develop-docs/sdk/getting-started/playbooks/development/handling-external-contributor-pr.mdx index 86ae45b9135f3..e09e851c7f37a 100644 --- a/develop-docs/sdk/getting-started/playbooks/development/handling-external-contributor-pr.mdx +++ b/develop-docs/sdk/getting-started/playbooks/development/handling-external-contributor-pr.mdx @@ -3,6 +3,7 @@ title: Handling an External Contributor Pull Request spec_id: sdk/playbooks/handling-external-contributor-pr spec_version: 1.0.0 spec_status: candidate +spec_kind: process spec_depends_on: - id: sdk/getting-started/standards/review-ci version: ">=1.0.0" diff --git a/develop-docs/sdk/getting-started/playbooks/development/opening-a-pr.mdx b/develop-docs/sdk/getting-started/playbooks/development/opening-a-pr.mdx index 2d7a36fe47a02..159ff894811c8 100644 --- a/develop-docs/sdk/getting-started/playbooks/development/opening-a-pr.mdx +++ b/develop-docs/sdk/getting-started/playbooks/development/opening-a-pr.mdx @@ -3,6 +3,7 @@ title: Opening a Pull Request spec_id: sdk/playbooks/opening-a-pr spec_version: 1.0.0 spec_status: candidate +spec_kind: process spec_depends_on: - id: sdk/getting-started/standards/code-submission version: ">=1.0.0" diff --git a/develop-docs/sdk/getting-started/playbooks/development/reviewing-a-pr.mdx b/develop-docs/sdk/getting-started/playbooks/development/reviewing-a-pr.mdx index 8ea96b9afd887..3f891ad245b1f 100644 --- a/develop-docs/sdk/getting-started/playbooks/development/reviewing-a-pr.mdx +++ b/develop-docs/sdk/getting-started/playbooks/development/reviewing-a-pr.mdx @@ -3,6 +3,7 @@ title: Reviewing a Pull Request spec_id: sdk/playbooks/reviewing-a-pr spec_version: 1.0.0 spec_status: candidate +spec_kind: process spec_depends_on: - id: sdk/getting-started/standards/review-ci version: ">=1.0.0" diff --git a/develop-docs/sdk/getting-started/playbooks/development/reviewing-ai-generated-code.mdx b/develop-docs/sdk/getting-started/playbooks/development/reviewing-ai-generated-code.mdx index 3f737c67a670c..95ee07e681c7e 100644 --- a/develop-docs/sdk/getting-started/playbooks/development/reviewing-ai-generated-code.mdx +++ b/develop-docs/sdk/getting-started/playbooks/development/reviewing-ai-generated-code.mdx @@ -3,6 +3,7 @@ title: Reviewing AI-Generated Code spec_id: sdk/playbooks/reviewing-ai-generated-code spec_version: 1.0.0 spec_status: candidate +spec_kind: process spec_depends_on: - id: sdk/getting-started/standards/review-ci version: ">=1.0.0" diff --git a/develop-docs/sdk/getting-started/playbooks/development/syncing-feature-branches.mdx b/develop-docs/sdk/getting-started/playbooks/development/syncing-feature-branches.mdx index 63cd35904a0a2..f80803611f8be 100644 --- a/develop-docs/sdk/getting-started/playbooks/development/syncing-feature-branches.mdx +++ b/develop-docs/sdk/getting-started/playbooks/development/syncing-feature-branches.mdx @@ -3,6 +3,7 @@ title: Syncing Feature Branches spec_id: sdk/playbooks/syncing-feature-branches spec_version: 1.0.0 spec_status: candidate +spec_kind: process spec_changelog: - version: 1.0.0 date: 2026-02-21 diff --git a/develop-docs/sdk/getting-started/playbooks/sdk-lifecycle/breaking-changes.mdx b/develop-docs/sdk/getting-started/playbooks/sdk-lifecycle/breaking-changes.mdx index 54fc19e6ca480..10e809b227cdc 100644 --- a/develop-docs/sdk/getting-started/playbooks/sdk-lifecycle/breaking-changes.mdx +++ b/develop-docs/sdk/getting-started/playbooks/sdk-lifecycle/breaking-changes.mdx @@ -3,6 +3,7 @@ title: Introducing Breaking Changes spec_id: sdk/playbooks/breaking-changes spec_version: 1.0.0 spec_status: candidate +spec_kind: process spec_depends_on: - id: sdk/getting-started/standards/api-architecture version: ">=1.0.0" diff --git a/develop-docs/sdk/getting-started/playbooks/sdk-lifecycle/cutting-a-release.mdx b/develop-docs/sdk/getting-started/playbooks/sdk-lifecycle/cutting-a-release.mdx index e46c3f0ccce21..ff2fc5d053d5e 100644 --- a/develop-docs/sdk/getting-started/playbooks/sdk-lifecycle/cutting-a-release.mdx +++ b/develop-docs/sdk/getting-started/playbooks/sdk-lifecycle/cutting-a-release.mdx @@ -3,6 +3,7 @@ title: Cutting a Release spec_id: sdk/playbooks/cutting-a-release spec_version: 1.1.0 spec_status: candidate +spec_kind: process spec_depends_on: - id: sdk/getting-started/standards/review-ci version: ">=1.0.0" diff --git a/develop-docs/sdk/getting-started/playbooks/sdk-lifecycle/deprecating-an-api.mdx b/develop-docs/sdk/getting-started/playbooks/sdk-lifecycle/deprecating-an-api.mdx index 5f07d53ef8933..1f09eb113721b 100644 --- a/develop-docs/sdk/getting-started/playbooks/sdk-lifecycle/deprecating-an-api.mdx +++ b/develop-docs/sdk/getting-started/playbooks/sdk-lifecycle/deprecating-an-api.mdx @@ -3,6 +3,7 @@ title: Deprecating an API spec_id: sdk/playbooks/deprecating-an-api spec_version: 1.0.0 spec_status: candidate +spec_kind: process spec_depends_on: - id: sdk/getting-started/standards/api-architecture version: ">=1.0.0" diff --git a/develop-docs/sdk/getting-started/playbooks/sdk-lifecycle/deprecating-an-sdk.mdx b/develop-docs/sdk/getting-started/playbooks/sdk-lifecycle/deprecating-an-sdk.mdx index 40ed6e5562adb..ad11cb949b9c8 100644 --- a/develop-docs/sdk/getting-started/playbooks/sdk-lifecycle/deprecating-an-sdk.mdx +++ b/develop-docs/sdk/getting-started/playbooks/sdk-lifecycle/deprecating-an-sdk.mdx @@ -3,6 +3,7 @@ title: Deprecating an SDK spec_id: sdk/playbooks/deprecating-an-sdk spec_version: 1.0.0 spec_status: candidate +spec_kind: process spec_depends_on: - id: sdk/getting-started/standards/api-architecture version: ">=1.0.0" diff --git a/develop-docs/sdk/getting-started/playbooks/sdk-lifecycle/dropping-platform-support.mdx b/develop-docs/sdk/getting-started/playbooks/sdk-lifecycle/dropping-platform-support.mdx index 18d27d63fc51d..ed528fc32b544 100644 --- a/develop-docs/sdk/getting-started/playbooks/sdk-lifecycle/dropping-platform-support.mdx +++ b/develop-docs/sdk/getting-started/playbooks/sdk-lifecycle/dropping-platform-support.mdx @@ -3,6 +3,7 @@ title: Dropping Platform or Language Version Support spec_id: sdk/playbooks/dropping-platform-support spec_version: 1.0.0 spec_status: candidate +spec_kind: process spec_depends_on: - id: sdk/getting-started/standards/api-architecture version: ">=1.0.0" diff --git a/develop-docs/sdk/getting-started/playbooks/setup/setting-up-new-sdk-repo.mdx b/develop-docs/sdk/getting-started/playbooks/setup/setting-up-new-sdk-repo.mdx index ba2142bb1d36b..1c8db7432100d 100644 --- a/develop-docs/sdk/getting-started/playbooks/setup/setting-up-new-sdk-repo.mdx +++ b/develop-docs/sdk/getting-started/playbooks/setup/setting-up-new-sdk-repo.mdx @@ -3,6 +3,7 @@ title: Setting Up a New SDK Repository spec_id: sdk/playbooks/setting-up-new-sdk-repo spec_version: 1.0.0 spec_status: candidate +spec_kind: process spec_depends_on: - id: sdk/getting-started/standards/repository-docs version: ">=1.0.0" diff --git a/develop-docs/sdk/getting-started/playbooks/setup/setting-up-release-infrastructure.mdx b/develop-docs/sdk/getting-started/playbooks/setup/setting-up-release-infrastructure.mdx index 597cb938c0462..673b14f224dd3 100644 --- a/develop-docs/sdk/getting-started/playbooks/setup/setting-up-release-infrastructure.mdx +++ b/develop-docs/sdk/getting-started/playbooks/setup/setting-up-release-infrastructure.mdx @@ -3,6 +3,7 @@ title: Setting Up Release Infrastructure spec_id: sdk/playbooks/release-infrastructure spec_version: 1.0.0 spec_status: stable +spec_kind: process spec_depends_on: - id: sdk/getting-started/standards/release-versioning version: ">=1.0.0" diff --git a/develop-docs/sdk/getting-started/standards/api-architecture.mdx b/develop-docs/sdk/getting-started/standards/api-architecture.mdx index 382ef7f3aad0a..aae5f131fb751 100644 --- a/develop-docs/sdk/getting-started/standards/api-architecture.mdx +++ b/develop-docs/sdk/getting-started/standards/api-architecture.mdx @@ -3,6 +3,7 @@ title: API and Architecture spec_id: sdk/getting-started/standards/api-architecture spec_version: 1.0.0 spec_status: stable +spec_kind: process spec_platforms: - all spec_changelog: diff --git a/develop-docs/sdk/getting-started/standards/code-quality.mdx b/develop-docs/sdk/getting-started/standards/code-quality.mdx index c2bdb0a79b988..a5c8de1dd31e2 100644 --- a/develop-docs/sdk/getting-started/standards/code-quality.mdx +++ b/develop-docs/sdk/getting-started/standards/code-quality.mdx @@ -3,6 +3,7 @@ title: Code Quality spec_id: sdk/getting-started/standards/code-quality spec_version: 1.0.0 spec_status: stable +spec_kind: process spec_platforms: - all spec_changelog: diff --git a/develop-docs/sdk/getting-started/standards/code-submission.mdx b/develop-docs/sdk/getting-started/standards/code-submission.mdx index 1aa418ccf12d2..7be63fa562a25 100644 --- a/develop-docs/sdk/getting-started/standards/code-submission.mdx +++ b/develop-docs/sdk/getting-started/standards/code-submission.mdx @@ -3,6 +3,7 @@ title: Code Submission spec_id: sdk/getting-started/standards/code-submission spec_version: 1.2.0 spec_status: stable +spec_kind: process spec_platforms: - all spec_changelog: diff --git a/develop-docs/sdk/getting-started/standards/coordination-maintenance.mdx b/develop-docs/sdk/getting-started/standards/coordination-maintenance.mdx index 3fa547e124151..cc518a851cf40 100644 --- a/develop-docs/sdk/getting-started/standards/coordination-maintenance.mdx +++ b/develop-docs/sdk/getting-started/standards/coordination-maintenance.mdx @@ -3,6 +3,7 @@ title: Coordination and Maintenance spec_id: sdk/getting-started/standards/coordination-maintenance spec_version: 1.0.0 spec_status: stable +spec_kind: process spec_platforms: - all spec_changelog: diff --git a/develop-docs/sdk/getting-started/standards/planning-scoping.mdx b/develop-docs/sdk/getting-started/standards/planning-scoping.mdx index 1a280a4f042f3..c0e6d730fb2fe 100644 --- a/develop-docs/sdk/getting-started/standards/planning-scoping.mdx +++ b/develop-docs/sdk/getting-started/standards/planning-scoping.mdx @@ -3,6 +3,7 @@ title: Planning and Scoping spec_id: sdk/getting-started/standards/planning-scoping spec_version: 1.0.0 spec_status: draft +spec_kind: process spec_platforms: - all spec_changelog: diff --git a/develop-docs/sdk/getting-started/standards/release-versioning.mdx b/develop-docs/sdk/getting-started/standards/release-versioning.mdx index f2a3b0e910066..a7d0ad9b9993d 100644 --- a/develop-docs/sdk/getting-started/standards/release-versioning.mdx +++ b/develop-docs/sdk/getting-started/standards/release-versioning.mdx @@ -3,6 +3,7 @@ title: Release and Versioning spec_id: sdk/getting-started/standards/release-versioning spec_version: 1.0.0 spec_status: stable +spec_kind: process spec_platforms: - all spec_changelog: diff --git a/develop-docs/sdk/getting-started/standards/repository-docs.mdx b/develop-docs/sdk/getting-started/standards/repository-docs.mdx index 154251f5144b5..bc4b3318e0f6d 100644 --- a/develop-docs/sdk/getting-started/standards/repository-docs.mdx +++ b/develop-docs/sdk/getting-started/standards/repository-docs.mdx @@ -3,6 +3,7 @@ title: Repository and Documentation spec_id: sdk/getting-started/standards/repository-docs spec_version: 1.1.0 spec_status: stable +spec_kind: process spec_platforms: - all spec_changelog: diff --git a/develop-docs/sdk/getting-started/standards/review-ci.mdx b/develop-docs/sdk/getting-started/standards/review-ci.mdx index fc9af8eeff2af..62dabdf2dcacf 100644 --- a/develop-docs/sdk/getting-started/standards/review-ci.mdx +++ b/develop-docs/sdk/getting-started/standards/review-ci.mdx @@ -3,6 +3,7 @@ title: Review and CI spec_id: sdk/getting-started/standards/review-ci spec_version: 1.1.0 spec_status: stable +spec_kind: process spec_platforms: - all spec_changelog: diff --git a/develop-docs/sdk/getting-started/standards/spec-lifecycle.mdx b/develop-docs/sdk/getting-started/standards/spec-lifecycle.mdx index 2bde3a07660af..2c69fdeb7d1fa 100644 --- a/develop-docs/sdk/getting-started/standards/spec-lifecycle.mdx +++ b/develop-docs/sdk/getting-started/standards/spec-lifecycle.mdx @@ -25,7 +25,8 @@ Each spec is an MDX page with frontmatter that drives the status badge, version, | `spec_depends_on` | no | Other specs this one relies on, each `{id, version}` with a SemVer range. | | `spec_platforms` | no | Platforms the spec applies to; defaults to `all`. | | `spec_superseded_by` | no | `spec_id` of the replacement spec. Set when `deprecated`. | -| `spec_guidelines` | no | Declares conformance to [Writing SDK Specs](/sdk/getting-started/standards/writing-specs/), e.g. `writing-specs@0.1`. Specs without it show a legacy notice. | +| `spec_guidelines` | no | Declares conformance to [Writing SDK Specs](/sdk/getting-started/standards/writing-specs/), e.g. `writing-specs@0.1`. Shown next to the version. Specs without it show a legacy notice, unless `spec_kind` is `process`. | +| `spec_kind` | no | Set to `process` for specs that set rules for how SDK teams work, such as playbooks and engineering standards, rather than for how SDKs behave. Process specs are out of scope for Writing SDK Specs and show no legacy notice. | A spec's body is divided into `` blocks, each with its own `status`, a `since` version marking when its current requirements landed, and an optional `superseded_by` link. Sections **MAY** advance independently — a `stable` spec can still contain a `candidate` section that's gathering feedback. diff --git a/develop-docs/sdk/getting-started/standards/writing-specs.mdx b/develop-docs/sdk/getting-started/standards/writing-specs.mdx index 4738d3daf02d8..87c5a325ef64e 100644 --- a/develop-docs/sdk/getting-started/standards/writing-specs.mdx +++ b/develop-docs/sdk/getting-started/standards/writing-specs.mdx @@ -20,7 +20,7 @@ SDK specs define what SDKs do, not how they do it. This spec builds on [RFC 2119 ## Scope -This spec applies to specs. Its [Legacy Specs](#legacy-specs) section also applies to SDKs that implement legacy specs. Status, versioning, and changelogs are covered by [Spec Lifecycle](/sdk/getting-started/standards/spec-lifecycle/). +This spec applies to itself and to all specs except process specs. Its [Legacy Specs](#legacy-specs) section also applies to SDKs that implement legacy specs. Status, versioning, changelogs, and frontmatter fields are covered by [Spec Lifecycle](/sdk/getting-started/standards/spec-lifecycle/). ## Definitions @@ -28,7 +28,8 @@ This spec applies to specs. Its [Legacy Specs](#legacy-specs) section also appli - **Requirement**: a statement in a spec that uses, rather than mentions, an RFC 2119 keyword written in uppercase, such as "MUST", "SHOULD", or "MAY". - **Non-normative content**: anything in a spec that is not a requirement. - **Externally observable behavior**: behavior whose conformance can be determined without inspecting the implementation's internals. For an SDK, conformance is determined using only its public API, the data it sends, its calls into user code, its effects on the host application, and its responses to inputs. -- **Legacy spec**: a spec without `spec_guidelines` in its frontmatter. +- **Process spec**: a spec with `spec_kind: process` in its frontmatter. Process specs, such as playbooks and engineering standards, set rules for how SDK teams work rather than for how SDKs behave. +- **Legacy spec**: a spec, other than a process spec, without `spec_guidelines` in its frontmatter. ## Requirements diff --git a/src/components/specMeta.tsx b/src/components/specMeta.tsx index e0d476d3450ba..79733629e5b1f 100644 --- a/src/components/specMeta.tsx +++ b/src/components/specMeta.tsx @@ -7,10 +7,15 @@ type SpecMetaProps = { version: string; /** Value of the `spec_guidelines` frontmatter field, e.g. `writing-specs@0.1`. */ guidelines?: string; + /** Value of the `spec_kind` frontmatter field. `process` specs are not subject to the guidelines. */ + kind?: string; }; -export function SpecMeta({version, status, guidelines}: SpecMetaProps) { +const WRITING_SPECS_PATH = '/sdk/getting-started/standards/writing-specs/'; + +export function SpecMeta({version, status, guidelines, kind}: SpecMetaProps) { const badgeClass = SPEC_STATUS_BADGE[status]; + const isProcessSpec = kind === 'process'; return (
@@ -43,14 +48,25 @@ export function SpecMeta({version, status, guidelines}: SpecMetaProps) { (changelog)
+ {guidelines && ( +
+ Guidelines + + + {guidelines} + + +
+ )} - {!guidelines && ( + {!guidelines && !isProcessSpec && (

This spec predates the{' '} - - spec writing guidelines - {' '} - and does not follow them yet. Requirements on behavior that is not externally + spec writing guidelines and + does not follow them yet. Requirements on behavior that is not externally observable are not mandatory, but SDKs should preserve the observable behavior that results from them.

From 90b1ba8d7047ef7a0cf4bfbfb960763bd425e607 Mon Sep 17 00:00:00 2001 From: "sentry-junior[bot]" <264270552+sentry-junior[bot]@users.noreply.github.com> Date: Mon, 19 Oct 2026 16:10:50 +0000 Subject: [PATCH 3/9] docs(sdk): Show followed guidelines version as readable text Co-Authored-By: Daniel Szoke <7881302+szokeasaurusrex@users.noreply.github.com> --- src/components/specMeta.tsx | 21 ++++++++------------- 1 file changed, 8 insertions(+), 13 deletions(-) diff --git a/src/components/specMeta.tsx b/src/components/specMeta.tsx index 79733629e5b1f..419b003ce30dc 100644 --- a/src/components/specMeta.tsx +++ b/src/components/specMeta.tsx @@ -16,6 +16,8 @@ const WRITING_SPECS_PATH = '/sdk/getting-started/standards/writing-specs/'; export function SpecMeta({version, status, guidelines, kind}: SpecMetaProps) { const badgeClass = SPEC_STATUS_BADGE[status]; const isProcessSpec = kind === 'process'; + // `spec_guidelines` is `writing-specs@`; show just the version. + const guidelinesVersion = guidelines?.match(/^writing-specs@(.+)$/)?.[1]; return (
@@ -48,20 +50,13 @@ export function SpecMeta({version, status, guidelines, kind}: SpecMetaProps) { (changelog)
- {guidelines && ( -
- Guidelines - - - {guidelines} - - -
- )} + {guidelines && ( +

+ Follows Writing SDK Specs + {guidelinesVersion ? ` version ${guidelinesVersion}` : ` (${guidelines})`}. +

+ )} {!guidelines && !isProcessSpec && (

This spec predates the{' '} From 4a2eb79d79efb78e3719d346ff800cf8f60a3fbf Mon Sep 17 00:00:00 2001 From: "sentry-junior[bot]" <264270552+sentry-junior[bot]@users.noreply.github.com> Date: Mon, 19 Oct 2026 16:32:44 +0000 Subject: [PATCH 4/9] docs(sdk): Add concision rule and migration limits to Writing SDK Specs Co-Authored-By: Daniel Szoke <7881302+szokeasaurusrex@users.noreply.github.com> --- .../getting-started/standards/writing-specs.mdx | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/develop-docs/sdk/getting-started/standards/writing-specs.mdx b/develop-docs/sdk/getting-started/standards/writing-specs.mdx index 87c5a325ef64e..f37abe4db93c6 100644 --- a/develop-docs/sdk/getting-started/standards/writing-specs.mdx +++ b/develop-docs/sdk/getting-started/standards/writing-specs.mdx @@ -65,11 +65,19 @@ A requirement that most SDKs do not implement yet **SHOULD** be placed in a `dra + + +### Concision + +Specs **SHOULD** be as concise as possible without losing necessary detail. Each requirement **SHOULD** be stated once, in as few words as it needs. Content that readers do not need to implement or verify the spec **SHOULD** be left out, such as code or JSON snippets that only restate requirements and examples that add no information. Implementation Guidance **SHOULD** only describe patterns that are not documented elsewhere and that implementers would likely get wrong without it. + + + ### Structure -A spec **SHOULD** contain, in this order: a short introduction, Scope (optional), Definitions (optional), Requirements, and Implementation Guidance (optional), followed by the changelog required by Spec Lifecycle. Non-normative content **SHOULD** be kept to a minimum and, apart from the introduction and brief examples, placed in Implementation Guidance. Implementation Guidance **SHOULD** only describe proven patterns that are not documented elsewhere. +A spec **SHOULD** contain, in this order: a short introduction, Scope (optional), Definitions (optional), Requirements, and Implementation Guidance (optional), followed by the changelog required by Spec Lifecycle. Non-normative content other than the introduction and brief examples **SHOULD** be placed in Implementation Guidance. @@ -77,7 +85,7 @@ A spec **SHOULD** contain, in this order: a short introduction, Scope (optional) ### Legacy Specs -A spec that conforms to this spec **SHOULD** declare it with `spec_guidelines: writing-specs@`. A spec **MUST NOT** declare it unless the whole spec conforms. Legacy specs **SHOULD** display a notice linking to this section. +A spec that conforms to this spec **SHOULD** declare it with `spec_guidelines: writing-specs@`. A spec **MUST NOT** declare it unless the whole spec conforms. Legacy specs **SHOULD** display a notice linking to this section. Migrating a legacy spec **SHOULD NOT** add requirements, and its changelog entry **SHOULD** list every requirement whose level or meaning changed. In a legacy spec, requirements on behavior that is not externally observable are not mandatory. SDKs **SHOULD** preserve the externally observable behavior that results from them. All other requirements in a legacy spec apply as written. @@ -92,9 +100,9 @@ _This section is non-normative._ - "Use a single, centralized `ClientReports` component per client" → "Discarded events are reported in the client report of the client that discarded them." - "Aggregate counts in a map keyed by reason and category" → "Each client report contains at most one entry per (reason, category) pair." -**The Section 6 test.** Ask: "Is this part of the public API? If not, would Sentry reject or misread data if an SDK ignored it, would SDKs fail to work together, or would users be harmed?" If none apply, it isn't a requirement: delete it, or keep it as guidance if it is a proven pattern. If one applies, use "SHOULD" unless no SDK could have a valid reason to deviate. Outside the public API, consistency across SDKs alone is not a reason for a requirement. +**The Section 6 test.** Ask: "Is this part of the public API? If not, would Sentry reject or misread data if an SDK ignored it, would SDKs fail to work together, or would users be harmed?" If none apply, it isn't a requirement. Outside the public API, consistency across SDKs alone is not a reason for a requirement. -**Migrating a legacy spec.** Rewrite the observable intent as requirements, move proven guidance into Implementation Guidance, delete the rest, then add `spec_guidelines`. +**Migrating a legacy spec.** Rewrite the observable intent as requirements and delete everything else unless it qualifies as Implementation Guidance (see [Concision](#concision)). Then add `spec_guidelines`. ## Changelog From 92131a6e85337882478ead7f4950812e6769c5ea Mon Sep 17 00:00:00 2001 From: "sentry-junior[bot]" <264270552+sentry-junior[bot]@users.noreply.github.com> Date: Mon, 19 Oct 2026 16:35:16 +0000 Subject: [PATCH 5/9] docs(sdk): Make Writing SDK Specs follow its own rules Co-Authored-By: Daniel Szoke <7881302+szokeasaurusrex@users.noreply.github.com> --- .../getting-started/standards/writing-specs.mdx | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/develop-docs/sdk/getting-started/standards/writing-specs.mdx b/develop-docs/sdk/getting-started/standards/writing-specs.mdx index f37abe4db93c6..1d9a2d9ad837d 100644 --- a/develop-docs/sdk/getting-started/standards/writing-specs.mdx +++ b/develop-docs/sdk/getting-started/standards/writing-specs.mdx @@ -25,7 +25,7 @@ This spec applies to itself and to all specs except process specs. Its [Legacy S ## Definitions - **Spec**: a page under `develop-docs/sdk/` with `spec_id` frontmatter. -- **Requirement**: a statement in a spec that uses, rather than mentions, an RFC 2119 keyword written in uppercase, such as "MUST", "SHOULD", or "MAY". +- **Requirement**: a statement in a spec that uses, rather than mentions, an RFC 2119 keyword written in uppercase, such as "MUST", "SHOULD", or "MAY". Keywords have the meaning defined in RFC 2119. - **Non-normative content**: anything in a spec that is not a requirement. - **Externally observable behavior**: behavior whose conformance can be determined without inspecting the implementation's internals. For an SDK, conformance is determined using only its public API, the data it sends, its calls into user code, its effects on the host application, and its responses to inputs. - **Process spec**: a spec with `spec_kind: process` in its frontmatter. Process specs, such as playbooks and engineering standards, set rules for how SDK teams work rather than for how SDKs behave. @@ -37,7 +37,7 @@ This spec applies to itself and to all specs except process specs. Its [Legacy S ### Keywords -Requirement keywords have the meaning defined in RFC 2119. Keywords **SHOULD** be bold. A keyword that is mentioned rather than used **SHOULD** be put in quotes. Non-normative content **SHOULD NOT** state obligations with lowercase "must", "should", "may", or phrases such as "needs to". +Keywords **SHOULD** be bold. A keyword that is mentioned rather than used **SHOULD** be put in quotes. Non-normative content **SHOULD NOT** state obligations with lowercase "must", "should", "may", or phrases such as "needs to". @@ -45,7 +45,7 @@ Requirement keywords have the meaning defined in RFC 2119. Keywords **SHOULD** b ### Observable Behavior -Requirements **MUST** only describe externally observable behavior. When a requirement is written as steps, only its observable result is required. +Requirements **MUST** only describe externally observable behavior. When a requirement is written as steps, SDKs **MAY** produce its observable result in any other way. @@ -59,7 +59,7 @@ Requirements **MUST** follow [Section 6 of RFC 2119](https://www.rfc-editor.org/ In addition, requirements **MAY** specify an SDK's public API. Such requirements **SHOULD** allow SDKs to adapt names, signatures, and types to their platform's conventions. -"SHOULD" is the default requirement level. "MUST" and "MUST NOT" **SHOULD** only be used where no SDK could have a valid reason to deviate. Authors **SHOULD** assume such a reason could exist unless shown otherwise. +Requirements **SHOULD** use "SHOULD" by default, and "MUST" or "MUST NOT" only where no SDK could have a valid reason to deviate. Authors **SHOULD** assume such a reason could exist unless shown otherwise. A requirement that most SDKs do not implement yet **SHOULD** be placed in a `draft` or `candidate` section (see [Spec Lifecycle](/sdk/getting-started/standards/spec-lifecycle/)), not weakened. @@ -77,7 +77,7 @@ Specs **SHOULD** be as concise as possible without losing necessary detail. Each ### Structure -A spec **SHOULD** contain, in this order: a short introduction, Scope (optional), Definitions (optional), Requirements, and Implementation Guidance (optional), followed by the changelog required by Spec Lifecycle. Non-normative content other than the introduction and brief examples **SHOULD** be placed in Implementation Guidance. +A spec **SHOULD** contain, in this order: a short introduction, Scope (optional), Definitions (optional), Requirements, and Implementation Guidance (optional), followed by the changelog required by Spec Lifecycle. Other non-normative content, apart from brief examples, **SHOULD** be placed in Implementation Guidance. @@ -87,14 +87,12 @@ A spec **SHOULD** contain, in this order: a short introduction, Scope (optional) A spec that conforms to this spec **SHOULD** declare it with `spec_guidelines: writing-specs@`. A spec **MUST NOT** declare it unless the whole spec conforms. Legacy specs **SHOULD** display a notice linking to this section. Migrating a legacy spec **SHOULD NOT** add requirements, and its changelog entry **SHOULD** list every requirement whose level or meaning changed. -In a legacy spec, requirements on behavior that is not externally observable are not mandatory. SDKs **SHOULD** preserve the externally observable behavior that results from them. All other requirements in a legacy spec apply as written. +SDKs **MAY** deviate from requirements in a legacy spec on behavior that is not externally observable, but **SHOULD** preserve the externally observable behavior that results from them. ## Implementation Guidance -_This section is non-normative._ - **The black-box test.** Ask: "Could I check this against a mock transport and the public API, without opening the SDK's source?" If not, it isn't a requirement. Usually the observable intent can be kept: - "Use a single, centralized `ClientReports` component per client" → "Discarded events are reported in the client report of the client that discarded them." @@ -102,7 +100,7 @@ _This section is non-normative._ **The Section 6 test.** Ask: "Is this part of the public API? If not, would Sentry reject or misread data if an SDK ignored it, would SDKs fail to work together, or would users be harmed?" If none apply, it isn't a requirement. Outside the public API, consistency across SDKs alone is not a reason for a requirement. -**Migrating a legacy spec.** Rewrite the observable intent as requirements and delete everything else unless it qualifies as Implementation Guidance (see [Concision](#concision)). Then add `spec_guidelines`. +**Migrating a legacy spec.** Rewrite the observable intent as requirements and delete everything else unless it qualifies as Implementation Guidance (see [Concision](#concision)). ## Changelog From 9e6b59592008a5c93bccb8bd1ad9820cb3ecf9d4 Mon Sep 17 00:00:00 2001 From: "sentry-junior[bot]" <264270552+sentry-junior[bot]@users.noreply.github.com> Date: Mon, 19 Oct 2026 16:44:49 +0000 Subject: [PATCH 6/9] docs(sdk): Tighten Concision, describe sections in Structure, move migration notes to guidance --- .../getting-started/standards/writing-specs.mdx | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/develop-docs/sdk/getting-started/standards/writing-specs.mdx b/develop-docs/sdk/getting-started/standards/writing-specs.mdx index 1d9a2d9ad837d..3a60985efbebb 100644 --- a/develop-docs/sdk/getting-started/standards/writing-specs.mdx +++ b/develop-docs/sdk/getting-started/standards/writing-specs.mdx @@ -69,7 +69,7 @@ A requirement that most SDKs do not implement yet **SHOULD** be placed in a `dra ### Concision -Specs **SHOULD** be as concise as possible without losing necessary detail. Each requirement **SHOULD** be stated once, in as few words as it needs. Content that readers do not need to implement or verify the spec **SHOULD** be left out, such as code or JSON snippets that only restate requirements and examples that add no information. Implementation Guidance **SHOULD** only describe patterns that are not documented elsewhere and that implementers would likely get wrong without it. +Specs **SHOULD** be as concise as possible without losing necessary detail. They **SHOULD NOT** repeat requirements or include content readers don't need, such as snippets or examples that only restate requirements. @@ -77,7 +77,16 @@ Specs **SHOULD** be as concise as possible without losing necessary detail. Each ### Structure -A spec **SHOULD** contain, in this order: a short introduction, Scope (optional), Definitions (optional), Requirements, and Implementation Guidance (optional), followed by the changelog required by Spec Lifecycle. Other non-normative content, apart from brief examples, **SHOULD** be placed in Implementation Guidance. +A spec **SHOULD** contain these sections, in this order: + +- _Introduction_ (untitled): a short summary of the spec. +- _Scope_ (optional): what the spec applies to. +- _Definitions_ (optional): terms with a spec-specific meaning. +- _Requirements_: all requirements. +- _Implementation Guidance_ (optional): only patterns that are not documented elsewhere and that implementers would likely get wrong without it. +- _Changelog_: as required by Spec Lifecycle. + +Other non-normative content, apart from brief examples, **SHOULD** be placed in _Implementation Guidance_. @@ -85,7 +94,7 @@ A spec **SHOULD** contain, in this order: a short introduction, Scope (optional) ### Legacy Specs -A spec that conforms to this spec **SHOULD** declare it with `spec_guidelines: writing-specs@`. A spec **MUST NOT** declare it unless the whole spec conforms. Legacy specs **SHOULD** display a notice linking to this section. Migrating a legacy spec **SHOULD NOT** add requirements, and its changelog entry **SHOULD** list every requirement whose level or meaning changed. +A spec that conforms to this spec **SHOULD** declare it with `spec_guidelines: writing-specs@`. A spec **MUST NOT** declare it unless the whole spec conforms. Legacy specs **SHOULD** display a notice linking to this section. SDKs **MAY** deviate from requirements in a legacy spec on behavior that is not externally observable, but **SHOULD** preserve the externally observable behavior that results from them. @@ -100,7 +109,7 @@ SDKs **MAY** deviate from requirements in a legacy spec on behavior that is not **The Section 6 test.** Ask: "Is this part of the public API? If not, would Sentry reject or misread data if an SDK ignored it, would SDKs fail to work together, or would users be harmed?" If none apply, it isn't a requirement. Outside the public API, consistency across SDKs alone is not a reason for a requirement. -**Migrating a legacy spec.** Rewrite the observable intent as requirements and delete everything else unless it qualifies as Implementation Guidance (see [Concision](#concision)). +**Migrating a legacy spec.** Rewrite the observable intent as requirements and delete everything else unless it qualifies as _Implementation Guidance_ (see [Structure](#structure)). Don't add requirements, and list every requirement whose level or meaning changed in the changelog entry. ## Changelog From bff0712a18956b9733c6690d025ca362b721f03f Mon Sep 17 00:00:00 2001 From: "sentry-junior[bot]" <264270552+sentry-junior[bot]@users.noreply.github.com> Date: Mon, 19 Oct 2026 16:51:43 +0000 Subject: [PATCH 7/9] docs(sdk): Drop Introduction label, clarify frontmatter declaration, drop notice rule --- .../sdk/getting-started/standards/writing-specs.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/develop-docs/sdk/getting-started/standards/writing-specs.mdx b/develop-docs/sdk/getting-started/standards/writing-specs.mdx index 3a60985efbebb..8da1a8ce09d7c 100644 --- a/develop-docs/sdk/getting-started/standards/writing-specs.mdx +++ b/develop-docs/sdk/getting-started/standards/writing-specs.mdx @@ -77,16 +77,16 @@ Specs **SHOULD** be as concise as possible without losing necessary detail. They ### Structure -A spec **SHOULD** contain these sections, in this order: +A spec **SHOULD** contain, in this order: -- _Introduction_ (untitled): a short summary of the spec. +- A short summary of the spec. - _Scope_ (optional): what the spec applies to. - _Definitions_ (optional): terms with a spec-specific meaning. - _Requirements_: all requirements. - _Implementation Guidance_ (optional): only patterns that are not documented elsewhere and that implementers would likely get wrong without it. - _Changelog_: as required by Spec Lifecycle. -Other non-normative content, apart from brief examples, **SHOULD** be placed in _Implementation Guidance_. +Non-normative content, apart from brief examples, **SHOULD** be placed in _Implementation Guidance_. @@ -94,7 +94,7 @@ Other non-normative content, apart from brief examples, **SHOULD** be placed in ### Legacy Specs -A spec that conforms to this spec **SHOULD** declare it with `spec_guidelines: writing-specs@`. A spec **MUST NOT** declare it unless the whole spec conforms. Legacy specs **SHOULD** display a notice linking to this section. +A spec that conforms to this spec **SHOULD** declare it in its frontmatter with `spec_guidelines: writing-specs@`. A spec **MUST NOT** declare it unless the whole spec conforms. SDKs **MAY** deviate from requirements in a legacy spec on behavior that is not externally observable, but **SHOULD** preserve the externally observable behavior that results from them. From 7bb786b4aafc2a7715fe9d21ebe9581dc8bea3f8 Mon Sep 17 00:00:00 2001 From: "sentry-junior[bot]" <264270552+sentry-junior[bot]@users.noreply.github.com> Date: Mon, 19 Oct 2026 17:05:20 +0000 Subject: [PATCH 8/9] docs(sdk): Add Clarity rule, require Scope, drop non-normative placement rule Co-Authored-By: Daniel Szoke <7881302+szokeasaurusrex@users.noreply.github.com> --- .../sdk/getting-started/standards/writing-specs.mdx | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/develop-docs/sdk/getting-started/standards/writing-specs.mdx b/develop-docs/sdk/getting-started/standards/writing-specs.mdx index 8da1a8ce09d7c..bc9b710441385 100644 --- a/develop-docs/sdk/getting-started/standards/writing-specs.mdx +++ b/develop-docs/sdk/getting-started/standards/writing-specs.mdx @@ -73,6 +73,14 @@ Specs **SHOULD** be as concise as possible without losing necessary detail. They + + +### Clarity + +Specs **SHOULD NOT** be vague or ambiguous, so that readers agree on what each requirement means and whether an SDK conforms to it. This can conflict with _Concision_. Specs **SHOULD** balance the two, adding words only where they remove doubt. + + + ### Structure @@ -80,14 +88,12 @@ Specs **SHOULD** be as concise as possible without losing necessary detail. They A spec **SHOULD** contain, in this order: - A short summary of the spec. -- _Scope_ (optional): what the spec applies to. +- _Scope_: what the spec applies to, such as all SDKs or only some. - _Definitions_ (optional): terms with a spec-specific meaning. - _Requirements_: all requirements. - _Implementation Guidance_ (optional): only patterns that are not documented elsewhere and that implementers would likely get wrong without it. - _Changelog_: as required by Spec Lifecycle. -Non-normative content, apart from brief examples, **SHOULD** be placed in _Implementation Guidance_. - From 5243ece2799b987867fa2ca916b924448be88044 Mon Sep 17 00:00:00 2001 From: "sentry-junior[bot]" <264270552+sentry-junior[bot]@users.noreply.github.com> Date: Tue, 20 Oct 2026 08:40:04 +0000 Subject: [PATCH 9/9] docs(sdk): Replace 'optional' with explicit rules for Definitions and Implementation Guidance --- develop-docs/sdk/getting-started/standards/writing-specs.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/develop-docs/sdk/getting-started/standards/writing-specs.mdx b/develop-docs/sdk/getting-started/standards/writing-specs.mdx index bc9b710441385..81daf152cfd50 100644 --- a/develop-docs/sdk/getting-started/standards/writing-specs.mdx +++ b/develop-docs/sdk/getting-started/standards/writing-specs.mdx @@ -89,9 +89,9 @@ A spec **SHOULD** contain, in this order: - A short summary of the spec. - _Scope_: what the spec applies to, such as all SDKs or only some. -- _Definitions_ (optional): terms with a spec-specific meaning. +- _Definitions_: terms with a spec-specific meaning. This section **MAY** be omitted if there are no terms which need to be defined. - _Requirements_: all requirements. -- _Implementation Guidance_ (optional): only patterns that are not documented elsewhere and that implementers would likely get wrong without it. +- _Implementation Guidance_: patterns that are not documented elsewhere and that implementers would likely get wrong without guidance. This section is non-normative and **SHOULD NOT** be included if no such patterns need to be documented. - _Changelog_: as required by Spec Lifecycle.