diff --git a/app/[[...path]]/page.tsx b/app/[[...path]]/page.tsx index e0ea91451a2b1..a16fbebf4d884 100644 --- a/app/[[...path]]/page.tsx +++ b/app/[[...path]]/page.tsx @@ -76,6 +76,10 @@ function mdxComponentsForFrontMatter(frontMatter: Record) { const boundProps = { version: String(frontMatter.spec_version), status: frontMatter.spec_status, + 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 2e2eb6d8ee1db..2c69fdeb7d1fa 100644 --- a/develop-docs/sdk/getting-started/standards/spec-lifecycle.mdx +++ b/develop-docs/sdk/getting-started/standards/spec-lifecycle.mdx @@ -25,6 +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`. 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 new file mode 100644 index 0000000000000..81daf152cfd50 --- /dev/null +++ b/develop-docs/sdk/getting-started/standards/writing-specs.mdx @@ -0,0 +1,122 @@ +--- +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 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 + +- **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". 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. +- **Legacy spec**: a spec, other than a process spec, without `spec_guidelines` in its frontmatter. + +## Requirements + + + +### Keywords + +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, SDKs **MAY** produce its observable result in any other way. + + + + + +### 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. + +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. + + + + + +### Concision + +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. + + + + + +### 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 + +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_: 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_: 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. + + + + + +### Legacy Specs + +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. + + + +## Implementation Guidance + +**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. 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 [Structure](#structure)). Don't add requirements, and list every requirement whose level or meaning changed in the changelog entry. + +## Changelog + + diff --git a/src/components/specMeta.tsx b/src/components/specMeta.tsx index e042efcd7a78c..419b003ce30dc 100644 --- a/src/components/specMeta.tsx +++ b/src/components/specMeta.tsx @@ -5,10 +5,19 @@ 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; + /** Value of the `spec_kind` frontmatter field. `process` specs are not subject to the guidelines. */ + kind?: string; }; -export function SpecMeta({version, status}: 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'; + // `spec_guidelines` is `writing-specs@`; show just the version. + const guidelinesVersion = guidelines?.match(/^writing-specs@(.+)$/)?.[1]; return (
@@ -42,6 +51,21 @@ export function SpecMeta({version, status}: SpecMetaProps) {
+ {guidelines && ( +

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

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

+ 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. +

+ )} ); }