From 9221332110e429eedf031a8da7bdda57f4f8e5e9 Mon Sep 17 00:00:00 2001 From: Alex Krawiec Date: Mon, 5 Oct 2026 11:29:18 -0700 Subject: [PATCH 1/2] docs: Add trailing slashes to internal links in develop-docs develop-docs renders at develop.sentry.dev from the same Next config, so the same rule applies there: a link without a trailing slash is served a 308 before the page loads. https://develop.sentry.dev/backend/application-domains -> 308 https://develop.sentry.dev/backend/application-domains/ -> 200 This was the last bucket left from the trailing-slash work in #19639 and #19675, which covered only the user docs. 240 links across 39 files, produced by `pnpm lint:trailing-slash:fix` from #19666. Verified: every changed file differs from master only by added "/" characters, with no slash removed and no external URL altered. A sample of 25 rewritten destinations all return 200 on develop.sentry.dev. `pnpm lint:trailing-slash` is now clean for develop-docs. The 23 remaining violations it reports are drift in docs/, fixed in #19811. Co-Authored-By: Claude Opus 5 --- develop-docs/getting-started/index.mdx | 2 +- develop-docs/sdk/foundations/client/index.mdx | 2 +- .../client/integrations/graphql.mdx | 2 +- .../foundations/client/integrations/index.mdx | 8 +-- .../client/integrations/mcp/index.mdx | 4 +- .../processing/batch-processor.mdx | 2 +- .../state-management/hub-and-scope/index.mdx | 2 +- .../state-management/scopes/index.mdx | 4 +- .../sdk/getting-started/ai-tools/index.mdx | 2 +- .../sdk/getting-started/philosophy/index.mdx | 2 +- .../aligning-cross-sdk-changes.mdx | 32 ++++++------ .../coordination/managing-linear-projects.mdx | 50 +++++++++---------- .../quarterly-cross-sdk-retro.mdx | 6 +-- .../playbooks/coordination/triaging.mdx | 16 +++--- .../development/adding-a-dependency.mdx | 14 +++--- .../development/handling-a-regression.mdx | 16 +++--- .../handling-external-contributor-pr.mdx | 26 +++++----- .../playbooks/development/opening-a-pr.mdx | 38 +++++++------- .../playbooks/development/reviewing-a-pr.mdx | 24 ++++----- .../reviewing-ai-generated-code.mdx | 24 ++++----- .../sdk-lifecycle/breaking-changes.mdx | 22 ++++---- .../sdk-lifecycle/cutting-a-release.mdx | 18 +++---- .../sdk-lifecycle/deprecating-an-api.mdx | 20 ++++---- .../sdk-lifecycle/deprecating-an-sdk.mdx | 22 ++++---- .../dropping-platform-support.mdx | 16 +++--- .../setup/setting-up-new-sdk-repo.mdx | 48 +++++++++--------- .../setting-up-release-infrastructure.mdx | 10 ++-- .../standards/api-architecture.mdx | 4 +- .../standards/code-quality.mdx | 2 +- .../standards/coordination-maintenance.mdx | 8 +-- .../standards/planning-scoping.mdx | 4 +- .../standards/release-versioning.mdx | 4 +- .../standards/repository-docs.mdx | 4 +- .../getting-started/standards/review-ci.mdx | 8 +-- .../javascript-sdks/browser-tracing.mdx | 4 +- develop-docs/sdk/telemetry/logs.mdx | 4 +- develop-docs/sdk/telemetry/metrics.mdx | 2 +- develop-docs/sdk/telemetry/traces/otlp.mdx | 2 +- develop-docs/self-hosted/index.mdx | 2 +- 39 files changed, 240 insertions(+), 240 deletions(-) diff --git a/develop-docs/getting-started/index.mdx b/develop-docs/getting-started/index.mdx index d9373129a5687..a6340a65f785f 100644 --- a/develop-docs/getting-started/index.mdx +++ b/develop-docs/getting-started/index.mdx @@ -4,7 +4,7 @@ description: This documentation serves as reference points for developing agains sidebar_order: 1 --- -We recommend going through the [engineering practices](/engineering-practices) and our [development philosophy](/getting-started/philosophy/) before contributing a change to Sentry. +We recommend going through the [engineering practices](/engineering-practices/) and our [development philosophy](/getting-started/philosophy/) before contributing a change to Sentry. diff --git a/develop-docs/sdk/foundations/client/index.mdx b/develop-docs/sdk/foundations/client/index.mdx index 07f7f5e761b49..4dbeb9b06e9fa 100644 --- a/develop-docs/sdk/foundations/client/index.mdx +++ b/develop-docs/sdk/foundations/client/index.mdx @@ -51,7 +51,7 @@ Related specs: - [Scopes](/sdk/foundations/state-management/scopes/) — scope chain and client resolution - [Transport](/sdk/foundations/transport/) — envelope delivery - [Envelopes](/sdk/foundations/envelopes/) — wire format -- [Attributes](/sdk/foundations/state-management/scopes/attributes) — attribute type system +- [Attributes](/sdk/foundations/state-management/scopes/attributes/) — attribute type system --- diff --git a/develop-docs/sdk/foundations/client/integrations/graphql.mdx b/develop-docs/sdk/foundations/client/integrations/graphql.mdx index 7d7be98a7ed86..c305dffafebe5 100644 --- a/develop-docs/sdk/foundations/client/integrations/graphql.mdx +++ b/develop-docs/sdk/foundations/client/integrations/graphql.mdx @@ -20,7 +20,7 @@ sidebar_order: 2 ## Overview -GraphQL client integrations should match the guidelines for [HTTP Client Integrations](/sdk/foundations/client/integrations/http-client) with differences described below. +GraphQL client integrations should match the guidelines for [HTTP Client Integrations](/sdk/foundations/client/integrations/http-client/) with differences described below. --- diff --git a/develop-docs/sdk/foundations/client/integrations/index.mdx b/develop-docs/sdk/foundations/client/integrations/index.mdx index 76ed6ee94c313..5e0d7b42e3a71 100644 --- a/develop-docs/sdk/foundations/client/integrations/index.mdx +++ b/develop-docs/sdk/foundations/client/integrations/index.mdx @@ -26,10 +26,10 @@ Users configure integrations via the `integrations` option in `Sentry.init()`. Related specs: - [Client](/sdk/foundations/client/) — client lifecycle and event pipeline -- [HTTP Client Integration](/sdk/foundations/client/integrations/http-client) — HTTP client instrumentation guidelines -- [GraphQL Integration](/sdk/foundations/client/integrations/graphql) — GraphQL client instrumentation guidelines -- [Feature Flags Integration](/sdk/foundations/client/integrations/feature-flags) — feature flag tracking guidelines -- [Modules Integration](/sdk/foundations/client/integrations/modules) — loaded library and version reporting +- [HTTP Client Integration](/sdk/foundations/client/integrations/http-client/) — HTTP client instrumentation guidelines +- [GraphQL Integration](/sdk/foundations/client/integrations/graphql/) — GraphQL client instrumentation guidelines +- [Feature Flags Integration](/sdk/foundations/client/integrations/feature-flags/) — feature flag tracking guidelines +- [Modules Integration](/sdk/foundations/client/integrations/modules/) — loaded library and version reporting --- diff --git a/develop-docs/sdk/foundations/client/integrations/mcp/index.mdx b/develop-docs/sdk/foundations/client/integrations/mcp/index.mdx index 91a712ec947f1..ad066cc4c2127 100644 --- a/develop-docs/sdk/foundations/client/integrations/mcp/index.mdx +++ b/develop-docs/sdk/foundations/client/integrations/mcp/index.mdx @@ -6,5 +6,5 @@ The MCP Server module instruments Anthropic's Model Context Protocol (MCP) SDKs. ## Features -- [Tracing](./tracing) -- [Errors](./errors) +- [Tracing](./tracing/) +- [Errors](./errors/) diff --git a/develop-docs/sdk/foundations/processing/batch-processor.mdx b/develop-docs/sdk/foundations/processing/batch-processor.mdx index 685930e578070..3fd0b7d2f1b8f 100644 --- a/develop-docs/sdk/foundations/processing/batch-processor.mdx +++ b/develop-docs/sdk/foundations/processing/batch-processor.mdx @@ -38,7 +38,7 @@ The BatchProcessor **MUST** forward all spans and logs in memory to the transpor 2. When the user calls `SentrySDK.close()`, the BatchProcessor **MUST** forward all data in memory to the transport. SDKs **SHOULD** keep their existing closing behavior. 3. When the application shuts down gracefully, the BatchProcessor **SHOULD** forward all data in memory to the transport. The transport **SHOULD** keep its existing behavior, which usually stores the data to disk as an envelope. It is not required to call a transport `flush`. This is mostly relevant for mobile SDKs already subscribed to these hooks, such as [applicationWillTerminate](https://developer.apple.com/documentation/uikit/uiapplicationdelegate/applicationwillterminate(_:)) on iOS. 4. When the application moves to the background, the BatchProcessor **SHOULD** forward all the data in memory to the transport and stop the timer. The transport **SHOULD** keep its existing behavior, which usually stores the data to disk as an envelope. It is not required to call the transport `flush`. This is mostly relevant for mobile SDKs. -5. Mobile SDKs **MUST** minimize data loss when sudden process terminations occur. Refer to the [Mobile Telemetry Processor](/sdk/foundations/processing/telemetry-processor/mobile-telemetry-processor) section for more details. +5. Mobile SDKs **MUST** minimize data loss when sudden process terminations occur. Refer to the [Mobile Telemetry Processor](/sdk/foundations/processing/telemetry-processor/mobile-telemetry-processor/) section for more details. The detailed specification is written in the [Gherkin syntax](https://cucumber.io/docs/gherkin/reference/). The specification uses spans as an example, but the same applies to logs or any other future telemetry data. diff --git a/develop-docs/sdk/foundations/state-management/hub-and-scope/index.mdx b/develop-docs/sdk/foundations/state-management/hub-and-scope/index.mdx index fb85faf128db5..7412d90eff5bb 100644 --- a/develop-docs/sdk/foundations/state-management/hub-and-scope/index.mdx +++ b/develop-docs/sdk/foundations/state-management/hub-and-scope/index.mdx @@ -61,7 +61,7 @@ The decision to remove the Hub from all Sentry SDKs was confirmed on 2024-05-03 - **Disabled SDK**: The SDK is considered disabled when the client has no transport. In this state, callbacks like `configure_scope` and event processors **SHOULD NOT** be invoked, and breadcrumbs **SHOULD NOT** be recorded. -- **Automatic Context Data**: SDKs and their integrations automatically populate scopes with useful contextual data such as tags, contexts, and extras. This typically happens by hooking into a framework (e.g., a web framework middleware setting request-related context on the scope). See [Data Scrubbing](/sdk/foundations/data-scrubbing) for considerations around sensitive data. +- **Automatic Context Data**: SDKs and their integrations automatically populate scopes with useful contextual data such as tags, contexts, and extras. This typically happens by hooking into a framework (e.g., a web framework middleware setting request-related context on the scope). See [Data Scrubbing](/sdk/foundations/data-scrubbing/) for considerations around sensitive data. --- diff --git a/develop-docs/sdk/foundations/state-management/scopes/index.mdx b/develop-docs/sdk/foundations/state-management/scopes/index.mdx index 3273c2345535e..bd802f214b7f6 100644 --- a/develop-docs/sdk/foundations/state-management/scopes/index.mdx +++ b/develop-docs/sdk/foundations/state-management/scopes/index.mdx @@ -72,7 +72,7 @@ Scopes are the mechanism by which Sentry SDKs propagate contextual data (tags, b This model replaces the [Hub & Scope](/sdk/foundations/state-management/hub-and-scope/) model. The Hub is removed; its functionality is absorbed into the three scope types. The design aligns with [OpenTelemetry's Context](https://opentelemetry.io/docs/specs/otel/context/) propagation — an immutable, fork-on-write mechanism that carries execution-scoped values across API boundaries. See [RFC 0122](https://github.com/getsentry/rfcs/pull/122) for the original design. Related specs: -- [Attributes](/sdk/foundations/state-management/scopes/attributes) — attribute type system for scope data +- [Attributes](/sdk/foundations/state-management/scopes/attributes/) — attribute type system for scope data - [Breadcrumbs](/sdk/foundations/state-management/scopes/breadcrumbs/) — structured event trail on scopes - [Hub & Scope](/sdk/foundations/state-management/hub-and-scope/) — deprecated predecessor @@ -96,7 +96,7 @@ This replaces the manual hub-cloning pattern from the old model. Users no longer ### Automatic Context Data -SDKs and their integrations automatically populate scopes with useful contextual data such as tags, contexts, and attributes. This typically happens by hooking into a framework (e.g., a web framework middleware setting request-related context on the isolation scope). This automatic enrichment is a key benefit of scopes — users get useful data on events without manual instrumentation. See [Data Scrubbing](/sdk/foundations/data-scrubbing) for considerations around sensitive data. +SDKs and their integrations automatically populate scopes with useful contextual data such as tags, contexts, and attributes. This typically happens by hooking into a framework (e.g., a web framework middleware setting request-related context on the isolation scope). This automatic enrichment is a key benefit of scopes — users get useful data on events without manual instrumentation. See [Data Scrubbing](/sdk/foundations/data-scrubbing/) for considerations around sensitive data. ### Scope Chain diff --git a/develop-docs/sdk/getting-started/ai-tools/index.mdx b/develop-docs/sdk/getting-started/ai-tools/index.mdx index 750aa0f1b091c..ba8d5240cd136 100644 --- a/develop-docs/sdk/getting-started/ai-tools/index.mdx +++ b/develop-docs/sdk/getting-started/ai-tools/index.mdx @@ -20,4 +20,4 @@ This section covers the AI tools available to SDK engineers, how they layer toge | **[Sentry CLI](https://docs.sentry.io/ai/sentry-cli/)** | Natural-language issue management | List, inspect, and triage issues from the terminal or an agent | | Rules files | Workflow-specific instructions | Fixed conventions that vary by task or directory | -Requirement levels (MUST/SHOULD) are defined in [Repository and Documentation Standards](/sdk/getting-started/standards/repository-docs) and [Review and CI Standards](/sdk/getting-started/standards/review-ci). +Requirement levels (MUST/SHOULD) are defined in [Repository and Documentation Standards](/sdk/getting-started/standards/repository-docs/) and [Review and CI Standards](/sdk/getting-started/standards/review-ci/). diff --git a/develop-docs/sdk/getting-started/philosophy/index.mdx b/develop-docs/sdk/getting-started/philosophy/index.mdx index 9cba780c59ff0..ff5ef031d2cb5 100644 --- a/develop-docs/sdk/getting-started/philosophy/index.mdx +++ b/develop-docs/sdk/getting-started/philosophy/index.mdx @@ -55,7 +55,7 @@ While we generally should try to keep the API surfaces of SDKs reasonable small. Some types of errors cannot be resolved without the data that was given to the program. But make sure that auto instrumentations doesn't attach PII without an explicit opt-in from the user. The server must be aware of parts of the protocol that include PII to scrub them by default. -Please check Data Handling for more detail. +Please check Data Handling for more detail. ## Don't forget the big picture 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 81bd7c73cda15..cfebc0c4b9e1d 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 @@ -24,12 +24,12 @@ This playbook guides SDK teams through coordinating changes that affect multiple Related resources: -- [Cross-SDK Coordination standard](/sdk/getting-started/standards/coordination-maintenance#cross-sdk-coordination) — coordination requirements and process -- [Managing Linear Projects](/sdk/getting-started/playbooks/coordination/managing-linear-projects) — how to set up and run each per-SDK project created in step 5 -- [Planning and Scoping standard](/sdk/getting-started/standards/planning-scoping) — design-first gate, risk identification, and project naming requirements -- [Semantic conventions process](/sdk/getting-started/standards/api-architecture#semantic-conventions-process) — process for new attributes -- [Deprecating an API](/sdk/getting-started/playbooks/sdk-lifecycle/deprecating-an-api) — related playbook for API changes -- [Deprecating an SDK](/sdk/getting-started/playbooks/sdk-lifecycle/deprecating-an-sdk) — related playbook for full SDK deprecation +- [Cross-SDK Coordination standard](/sdk/getting-started/standards/coordination-maintenance/#cross-sdk-coordination) — coordination requirements and process +- [Managing Linear Projects](/sdk/getting-started/playbooks/coordination/managing-linear-projects/) — how to set up and run each per-SDK project created in step 5 +- [Planning and Scoping standard](/sdk/getting-started/standards/planning-scoping/) — design-first gate, risk identification, and project naming requirements +- [Semantic conventions process](/sdk/getting-started/standards/api-architecture/#semantic-conventions-process) — process for new attributes +- [Deprecating an API](/sdk/getting-started/playbooks/sdk-lifecycle/deprecating-an-api/) — related playbook for API changes +- [Deprecating an SDK](/sdk/getting-started/playbooks/sdk-lifecycle/deprecating-an-sdk/) — related playbook for full SDK deprecation --- @@ -45,7 +45,7 @@ You **MUST** create an RFC or Linear initiative describing: - Timeline - Open questions -An RFC or initiative proposal is a design document and triggers the [Design-First Gate](/sdk/getting-started/standards/planning-scoping#design-first-gate) standard. It **MUST** also include a risk section per the [Risk Identification](/sdk/getting-started/standards/planning-scoping#risk-identification) standard. +An RFC or initiative proposal is a design document and triggers the [Design-First Gate](/sdk/getting-started/standards/planning-scoping/#design-first-gate) standard. It **MUST** also include a risk section per the [Risk Identification](/sdk/getting-started/standards/planning-scoping/#risk-identification) standard. #### 2. Allow cross-SDK review period @@ -57,7 +57,7 @@ You **MUST** allow a minimum of 1 week for all affected SDK teams to review and #### 3. Land semantic conventions first (if needed) -If the change involves new attributes, you **MUST** land the sentry-conventions PR first ([Semantic conventions process](/sdk/getting-started/standards/api-architecture#semantic-conventions-process)). +If the change involves new attributes, you **MUST** land the sentry-conventions PR first ([Semantic conventions process](/sdk/getting-started/standards/api-architecture/#semantic-conventions-process)). After the conventions PR is approved, you **MUST** wait 3 business days before implementing in any SDK. This grace period allows teams to review the final conventions and raise concerns. @@ -89,7 +89,7 @@ You **SHOULD** use the [`sentry-sdk-skills:linear-initiative`](https://github.co If not using the skill, you **MUST** manually: - Create a sub-initiative under the appropriate parent initiative in Linear -- For each SDK team involved, create a separate **project** under this sub-initiative, named per the [Project Naming](/sdk/getting-started/standards/planning-scoping#project-naming) standard (`[Effort name] [SDK name]`) +- For each SDK team involved, create a separate **project** under this sub-initiative, named per the [Project Naming](/sdk/getting-started/standards/planning-scoping/#project-naming) standard (`[Effort name] [SDK name]`) - You **MUST NOT** use a single project with multiple issues, as the project is only completed once **all** SDK teams finish their work - Each project **MUST** contain at least one issue with the **same title and description** as the project - Additional issues **MAY** be added as needed but **SHOULD** remain within the scope of the alignment effort @@ -108,7 +108,7 @@ This public issue **MAY** be omitted for changes that are: #### 6. Implement in each SDK independently -Each team **MUST** follow their own PR process ([Opening a PR](/sdk/getting-started/playbooks/development/opening-a-pr), [Reviewing a PR](/sdk/getting-started/playbooks/development/reviewing-a-pr)). The Linear projects provide visibility, but each SDK maintains its own standards and timeline. +Each team **MUST** follow their own PR process ([Opening a PR](/sdk/getting-started/playbooks/development/opening-a-pr/), [Reviewing a PR](/sdk/getting-started/playbooks/development/reviewing-a-pr/)). The Linear projects provide visibility, but each SDK maintains its own standards and timeline. You **SHOULD** use the [`sentry-sdk-skills:sdk-feature-implementation`](https://github.com/getsentry/sdk-skills?tab=readme-ov-file#available-skills) skill to spawn parallel agents that create draft PRs across all target SDK repos. The skill uses the Linear context gathered in step 5 and handles CI monitoring across repos. @@ -137,12 +137,12 @@ This helps improve future cross-SDK coordination. ## Referenced Standards -- [Cross-SDK Coordination standard](/sdk/getting-started/standards/coordination-maintenance#cross-sdk-coordination) — coordination process and requirements -- [Design-First Gate](/sdk/getting-started/standards/planning-scoping#design-first-gate) — RFC/proposal triggers this gate; must be complete before implementation -- [Risk Identification](/sdk/getting-started/standards/planning-scoping#risk-identification) — risk section required in the proposal; high risks block implementation start -- [Project Naming](/sdk/getting-started/standards/planning-scoping#project-naming) — `[Effort name] [SDK name]` format required for per-SDK projects -- [Managing Linear Projects](/sdk/getting-started/playbooks/coordination/managing-linear-projects) — how to set up and run each per-SDK project -- [Semantic conventions process](/sdk/getting-started/standards/api-architecture#semantic-conventions-process) — process for landing new attribute conventions +- [Cross-SDK Coordination standard](/sdk/getting-started/standards/coordination-maintenance/#cross-sdk-coordination) — coordination process and requirements +- [Design-First Gate](/sdk/getting-started/standards/planning-scoping/#design-first-gate) — RFC/proposal triggers this gate; must be complete before implementation +- [Risk Identification](/sdk/getting-started/standards/planning-scoping/#risk-identification) — risk section required in the proposal; high risks block implementation start +- [Project Naming](/sdk/getting-started/standards/planning-scoping/#project-naming) — `[Effort name] [SDK name]` format required for per-SDK projects +- [Managing Linear Projects](/sdk/getting-started/playbooks/coordination/managing-linear-projects/) — how to set up and run each per-SDK project +- [Semantic conventions process](/sdk/getting-started/standards/api-architecture/#semantic-conventions-process) — process for landing new attribute conventions --- 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 7c5fe3e8326dd..49a11279bdecb 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 @@ -36,9 +36,9 @@ SDK work falls under the **Great Data Capture** goal — see *Goal Hierarchy* (i Related resources: -- [Planning and Scoping standard](/sdk/getting-started/standards/planning-scoping) — issue quality, definition of done, design-first gate, risk identification, and AI-assisted planning requirements -- [Aligning Cross-SDK Changes](/sdk/getting-started/playbooks/coordination/aligning-cross-sdk-changes) — detailed playbook for cross-SDK sub-initiative work -- [Triaging](/sdk/getting-started/playbooks/coordination/triaging) — how issues enter the queue before landing in a project or backlog +- [Planning and Scoping standard](/sdk/getting-started/standards/planning-scoping/) — issue quality, definition of done, design-first gate, risk identification, and AI-assisted planning requirements +- [Aligning Cross-SDK Changes](/sdk/getting-started/playbooks/coordination/aligning-cross-sdk-changes/) — detailed playbook for cross-SDK sub-initiative work +- [Triaging](/sdk/getting-started/playbooks/coordination/triaging/) — how issues enter the queue before landing in a project or backlog --- @@ -53,7 +53,7 @@ SDK work maps to four levels in Linear: | **Project** | Time-bounded delivery tracked by one SDK team — always lives under an initiative or sub-initiative | | **Issue** | Individual unit of work — lives inside a project or standalone in the team backlog | -The [Issue Quality](/sdk/getting-started/standards/planning-scoping#issue-quality) and [Definition of Done](/sdk/getting-started/standards/planning-scoping#definition-of-done) standards apply at the issue level regardless of whether the issue belongs to a project. +The [Issue Quality](/sdk/getting-started/standards/planning-scoping/#issue-quality) and [Definition of Done](/sdk/getting-started/standards/planning-scoping/#definition-of-done) standards apply at the issue level regardless of whether the issue belongs to a project. --- @@ -73,9 +73,9 @@ If the correct initiative does not exist yet, create one or confirm the category ### Cross-SDK Alignment: Sub-Initiatives -When a change requires alignment across multiple SDKs, it **MUST** be tracked as a sub-initiative with one project per SDK team — not as a single project with issues from multiple teams. Project names **MUST** follow the [Project Naming](/sdk/getting-started/standards/planning-scoping#project-naming) standard: `[Effort name] [SDK name]`. +When a change requires alignment across multiple SDKs, it **MUST** be tracked as a sub-initiative with one project per SDK team — not as a single project with issues from multiple teams. Project names **MUST** follow the [Project Naming](/sdk/getting-started/standards/planning-scoping/#project-naming) standard: `[Effort name] [SDK name]`. -For the full process — proposal, review periods, sequencing, and documentation coordination — follow the [Aligning Cross-SDK Changes](/sdk/getting-started/playbooks/coordination/aligning-cross-sdk-changes) playbook. +For the full process — proposal, review periods, sequencing, and documentation coordination — follow the [Aligning Cross-SDK Changes](/sdk/getting-started/playbooks/coordination/aligning-cross-sdk-changes/) playbook. ### Initiative Hygiene @@ -98,7 +98,7 @@ Run these steps in order when starting a new project. You **MUST** set all of the following attributes before sharing the project with the team: -- **Title**: follow the [Project Naming](/sdk/getting-started/standards/planning-scoping#project-naming) standard — cross-SDK rollout projects use `[Effort name] [SDK name]` (e.g., `OTLP Integration [Python]`); standalone projects use a clear, action-oriented title +- **Title**: follow the [Project Naming](/sdk/getting-started/standards/planning-scoping/#project-naming) standard — cross-SDK rollout projects use `[Effort name] [SDK name]` (e.g., `OTLP Integration [Python]`); standalone projects use a clear, action-oriented title - **Initiative**: link to the appropriate initiative or create one (see [Initiatives](#initiatives) above); **MUST** be set before work begins - **Lead**: a single owner (not a team) - **Status**: set to the appropriate state (`Planned`, `In Progress`, etc.) @@ -172,7 +172,7 @@ Use this template as a starting point for the project description. For cross-SDK #### 2. Add Pre-Implementation Documentation -Before implementation begins, you **MUST** complete all pre-implementation documentation required by the [Design-First Gate](/sdk/getting-started/standards/planning-scoping#design-first-gate) and [Risk Identification](/sdk/getting-started/standards/planning-scoping#risk-identification) standards. +Before implementation begins, you **MUST** complete all pre-implementation documentation required by the [Design-First Gate](/sdk/getting-started/standards/planning-scoping/#design-first-gate) and [Risk Identification](/sdk/getting-started/standards/planning-scoping/#risk-identification) standards. - If the estimate is greater than **M** or the change affects more than one SDK, a design document (**Develop Docs**, **RFC**, **PRFAQ**, or **DACI**) **MUST** be linked in the project's **Documentation** field. - The design document **MUST** be complete (not a draft or stub) before the first implementation PR is reviewed. @@ -193,12 +193,12 @@ Announce the project in relevant team channels once the project and channel are Before moving the project to **In Progress**, create and triage the initial issue backlog: -- All issues **MUST** meet the [Issue Quality](/sdk/getting-started/standards/planning-scoping#issue-quality) requirements: assignee, detailed description, SDK label, type label, estimate, and priority. +- All issues **MUST** meet the [Issue Quality](/sdk/getting-started/standards/planning-scoping/#issue-quality) requirements: assignee, detailed description, SDK label, type label, estimate, and priority. - Issues estimated larger than **M** **MUST** be split before they are moved to **Todo**. -- Use a spike (timeboxed per the [Spike Timeboxing](/sdk/getting-started/standards/planning-scoping#spike-timeboxing) standard) for any work that is too uncertain to estimate. +- Use a spike (timeboxed per the [Spike Timeboxing](/sdk/getting-started/standards/planning-scoping/#spike-timeboxing) standard) for any work that is too uncertain to estimate. - Apply priorities clearly: mark blockers and critical-path issues as high priority. -For AI-assisted decomposition of the backlog, follow the [AI-Assisted Planning](/sdk/getting-started/standards/planning-scoping#ai-assisted-planning) standard — all AI-generated sub-issues **MUST** be reviewed and approved before moving to **Todo**. +For AI-assisted decomposition of the backlog, follow the [AI-Assisted Planning](/sdk/getting-started/standards/planning-scoping/#ai-assisted-planning) standard — all AI-generated sub-issues **MUST** be reviewed and approved before moving to **Todo**. ### During the Project @@ -215,21 +215,21 @@ Observe the following WIP limits at all times: At each weekly sync (or equivalent cadence): - Move stale issues back to **Backlog** if they are no longer ready. -- Re-estimate or split issues that have grown beyond **M** per the [Issue Quality](/sdk/getting-started/standards/planning-scoping#issue-quality) standard. +- Re-estimate or split issues that have grown beyond **M** per the [Issue Quality](/sdk/getting-started/standards/planning-scoping/#issue-quality) standard. - Close or archive issues that are no longer in scope with a brief note explaining why. Use the [Linear views](#using-linear-views) recommended below to surface work that needs attention during weekly reviews. #### Handle Incoming Issues and PRs -Issues and PRs that arrive while the project is active **MUST** go through the standard triage process — follow the [Triaging](/sdk/getting-started/playbooks/coordination/triaging) playbook. The project lead owns this. +Issues and PRs that arrive while the project is active **MUST** go through the standard triage process — follow the [Triaging](/sdk/getting-started/playbooks/coordination/triaging/) playbook. The project lead owns this. #### Visibility for Major Releases If the project delivers a **major release** or a **user-visible feature**: - Create a public GitHub issue (or link an existing one) to track community interest and questions. -- Coordinate documentation PRs so they land at the same time as the SDK release — docs **MUST NOT** go live before the SDK ships (see [Aligning Cross-SDK Changes](/sdk/getting-started/playbooks/coordination/aligning-cross-sdk-changes)). +- Coordinate documentation PRs so they land at the same time as the SDK release — docs **MUST NOT** go live before the SDK ships (see [Aligning Cross-SDK Changes](/sdk/getting-started/playbooks/coordination/aligning-cross-sdk-changes/)). - Post a project update at least once per week while the project is **In Progress**. For changes that only affect internal implementation details with no user-facing impact, public visibility **MAY** be omitted. @@ -238,7 +238,7 @@ For changes that only affect internal implementation details with no user-facing Run these steps in order when all implementation and documentation is shipped. -Verify closure against the [Definition of Done](/sdk/getting-started/standards/planning-scoping#definition-of-done) standard before setting the project to **Done**. +Verify closure against the [Definition of Done](/sdk/getting-started/standards/planning-scoping/#definition-of-done) standard before setting the project to **Done**. #### Close-Out Steps @@ -291,8 +291,8 @@ audience. Issues that are not part of a project — bugs accepted from triage, backlog items, community-reported issues — are worked under the same rules as project issues. The -[Issue Quality](/sdk/getting-started/standards/planning-scoping#issue-quality) and -[Definition of Done](/sdk/getting-started/standards/planning-scoping#definition-of-done) standards +[Issue Quality](/sdk/getting-started/standards/planning-scoping/#issue-quality) and +[Definition of Done](/sdk/getting-started/standards/planning-scoping/#definition-of-done) standards apply equally. The same WIP limits apply: no more than **3** issues **In Progress** per engineer at any time. @@ -333,14 +333,14 @@ Teams **MAY** add additional views. The views above **SHOULD** exist in every SD ## Referenced Standards -- [Project Naming](/sdk/getting-started/standards/planning-scoping#project-naming) — naming conventions for cross-SDK rollout and standalone projects -- [Issue Quality](/sdk/getting-started/standards/planning-scoping#issue-quality) — required issue attributes and size limits -- [Definition of Done](/sdk/getting-started/standards/planning-scoping#definition-of-done) — conditions for closing issues and projects -- [Design-First Gate](/sdk/getting-started/standards/planning-scoping#design-first-gate) — when design docs are required before implementation -- [Risk Identification](/sdk/getting-started/standards/planning-scoping#risk-identification) — required risk section in design documents; high risks block implementation start -- [Spike Timeboxing](/sdk/getting-started/standards/planning-scoping#spike-timeboxing) — timeboxing exploration work -- [AI-Assisted Planning](/sdk/getting-started/standards/planning-scoping#ai-assisted-planning) — human review requirements for AI-generated planning artifacts -- [Cross-SDK Coordination Protocol](/sdk/getting-started/standards/coordination-maintenance#cross-sdk-coordination) — cross-SDK process (see [Aligning Cross-SDK Changes](/sdk/getting-started/playbooks/coordination/aligning-cross-sdk-changes)) +- [Project Naming](/sdk/getting-started/standards/planning-scoping/#project-naming) — naming conventions for cross-SDK rollout and standalone projects +- [Issue Quality](/sdk/getting-started/standards/planning-scoping/#issue-quality) — required issue attributes and size limits +- [Definition of Done](/sdk/getting-started/standards/planning-scoping/#definition-of-done) — conditions for closing issues and projects +- [Design-First Gate](/sdk/getting-started/standards/planning-scoping/#design-first-gate) — when design docs are required before implementation +- [Risk Identification](/sdk/getting-started/standards/planning-scoping/#risk-identification) — required risk section in design documents; high risks block implementation start +- [Spike Timeboxing](/sdk/getting-started/standards/planning-scoping/#spike-timeboxing) — timeboxing exploration work +- [AI-Assisted Planning](/sdk/getting-started/standards/planning-scoping/#ai-assisted-planning) — human review requirements for AI-generated planning artifacts +- [Cross-SDK Coordination Protocol](/sdk/getting-started/standards/coordination-maintenance/#cross-sdk-coordination) — cross-SDK process (see [Aligning Cross-SDK Changes](/sdk/getting-started/playbooks/coordination/aligning-cross-sdk-changes/)) --- 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 08f828d7f351d..3cacff17252db 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 @@ -21,8 +21,8 @@ spec_changelog: This playbook guides SDK teams through conducting a quarterly retrospective to identify and address cross-SDK process issues. It covers async question gathering, compilation, sync discussion, and actionable outcomes. By following these steps, teams continuously improve standards, playbooks, and collaboration patterns based on real experience. Related resources: -- [Cross-SDK Coordination standard](/sdk/getting-started/standards/coordination-maintenance#cross-sdk-coordination) — coordination process this retro evaluates -- [Aligning Cross-SDK Changes](/sdk/getting-started/playbooks/coordination/aligning-cross-sdk-changes) — references this retro in step 8 +- [Cross-SDK Coordination standard](/sdk/getting-started/standards/coordination-maintenance/#cross-sdk-coordination) — coordination process this retro evaluates +- [Aligning Cross-SDK Changes](/sdk/getting-started/playbooks/coordination/aligning-cross-sdk-changes/) — references this retro in step 8 --- @@ -67,7 +67,7 @@ This meta-analysis helps identify deeper systemic issues versus one-time problem ## Referenced Standards -- [Cross-SDK Coordination standard](/sdk/getting-started/standards/coordination-maintenance#cross-sdk-coordination) — coordination process evaluated by this retro +- [Cross-SDK Coordination standard](/sdk/getting-started/standards/coordination-maintenance/#cross-sdk-coordination) — coordination process evaluated by this retro - All standards and playbooks — this retro is the feedback loop for continuous improvement --- diff --git a/develop-docs/sdk/getting-started/playbooks/coordination/triaging.mdx b/develop-docs/sdk/getting-started/playbooks/coordination/triaging.mdx index 218189d59d53c..8692a3919a487 100644 --- a/develop-docs/sdk/getting-started/playbooks/coordination/triaging.mdx +++ b/develop-docs/sdk/getting-started/playbooks/coordination/triaging.mdx @@ -27,10 +27,10 @@ Triage **SHOULD** prioritise acknowledgement and categorization over immediate f Triage **MAY** be bypassed if the issue was created by a team member. Related resources: -- [Triaging SLA](/sdk/getting-started/standards/coordination-maintenance#issue-triage) — 2 business day first response requirement -- [GitHub Saved Replies](/sdk/getting-started/templates/saved-replies) — team-approved response templates for common scenarios -- [Handling an External Contributor PR](/sdk/getting-started/playbooks/development/handling-external-contributor-pr) — PR-specific triage workflow -- [Handling a Regression](/sdk/getting-started/playbooks/development/handling-a-regression) — regression response process +- [Triaging SLA](/sdk/getting-started/standards/coordination-maintenance/#issue-triage) — 2 business day first response requirement +- [GitHub Saved Replies](/sdk/getting-started/templates/saved-replies/) — team-approved response templates for common scenarios +- [Handling an External Contributor PR](/sdk/getting-started/playbooks/development/handling-external-contributor-pr/) — PR-specific triage workflow +- [Handling a Regression](/sdk/getting-started/playbooks/development/handling-a-regression/) — regression response process --- @@ -50,12 +50,12 @@ Items **MAY** arrive through any of these channels. Social media is out of scope Response time expectations vary by channel: -- **GitHub issues and PRs** — initial response **MUST** be within **2 business days** ([Triaging SLA](/sdk/getting-started/standards/coordination-maintenance#issue-triage)) +- **GitHub issues and PRs** — initial response **MUST** be within **2 business days** ([Triaging SLA](/sdk/getting-started/standards/coordination-maintenance/#issue-triage)) - **Slack and Discord** — response **SHOULD** be within a **few hours** during business hours The response **MUST** acknowledge receipt and set expectations — a clarifying question, next steps, or a likely outcome. The initial response does not imply acceptance, prioritisation, or commitment to work. -Use the [acknowledgement saved replies](/sdk/getting-started/templates/saved-replies#acknowledging-issues) as a starting point. +Use the [acknowledgement saved replies](/sdk/getting-started/templates/saved-replies/#acknowledging-issues) as a starting point. #### 3. Normalise the item @@ -90,13 +90,13 @@ Labels are applied automatically to reflect where action is required: When an issue carries **`Waiting for: Product Owner`**, treat it as an active obligation in the triage queue — respond, investigate, or escalate within the SLA window. Labels reset automatically on each state transition. -See also: [Waiting-for Labels](/sdk/getting-started/standards/coordination-maintenance#issue-triage) +See also: [Waiting-for Labels](/sdk/getting-started/standards/coordination-maintenance/#issue-triage) --- ## Referenced Standards -- [Triaging SLA](/sdk/getting-started/standards/coordination-maintenance#issue-triage) — 2 business day first response baseline and enforcement +- [Triaging SLA](/sdk/getting-started/standards/coordination-maintenance/#issue-triage) — 2 business day first response baseline and enforcement --- 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 8ca8c857a7d80..88618dbc89824 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 @@ -21,9 +21,9 @@ spec_changelog: This playbook guides SDK maintainers through the process of adding a new dependency to an SDK repository. It covers justification requirements, health and security evaluation, approval workflows, and integration steps. By following these steps, teams ensure that dependencies are vetted for maintenance health, security posture, license compatibility, and performance impact before integration. Related resources: -- [Dependency Management Standard](/sdk/getting-started/standards/code-quality#dependency-management) — dependency requirements and audit practices -- [SDK Size and Performance Budgets](/sdk/getting-started/standards/code-quality#size-performance-budgets) — size and performance tracking requirements -- [Security Practices](/sdk/getting-started/standards/code-quality#security-practices) — security requirements for dependencies +- [Dependency Management Standard](/sdk/getting-started/standards/code-quality/#dependency-management) — dependency requirements and audit practices +- [SDK Size and Performance Budgets](/sdk/getting-started/standards/code-quality/#size-performance-budgets) — size and performance tracking requirements +- [Security Practices](/sdk/getting-started/standards/code-quality/#security-practices) — security requirements for dependencies --- @@ -40,7 +40,7 @@ The issue **MUST** include documentation of the following: - Maintenance health (last release date, number of maintainers, open issue count) - Security posture (known vulnerabilities, audit history) - License compatibility -- Size impact on the SDK (see [SDK size and performance budgets](/sdk/getting-started/standards/code-quality#size-performance-budgets)) +- Size impact on the SDK (see [SDK size and performance budgets](/sdk/getting-started/standards/code-quality/#size-performance-budgets)) #### 3. Get explicit approval @@ -64,9 +64,9 @@ The PR reviewer **MUST** explicitly acknowledge the new dependency, not just app ## Referenced Standards -- [Dependency Management](/sdk/getting-started/standards/code-quality#dependency-management) — requirements for adding and maintaining dependencies -- [SDK Size and Performance Budgets](/sdk/getting-started/standards/code-quality#size-performance-budgets) — size and performance budget tracking -- [Security Practices](/sdk/getting-started/standards/code-quality#security-practices) — security requirements and vulnerability handling +- [Dependency Management](/sdk/getting-started/standards/code-quality/#dependency-management) — requirements for adding and maintaining dependencies +- [SDK Size and Performance Budgets](/sdk/getting-started/standards/code-quality/#size-performance-budgets) — size and performance budget tracking +- [Security Practices](/sdk/getting-started/standards/code-quality/#security-practices) — security requirements and vulnerability handling --- 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 00151301303c9..bcc64003f27e1 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 @@ -23,9 +23,9 @@ spec_changelog: This playbook guides SDK maintainers through handling regressions discovered after a release. It covers severity assessment, response options (patch release vs. rollback), communication protocols, and post-incident review. By following these steps, regressions will be resolved quickly with minimal user impact. Related resources: -- [Post-release monitoring](/sdk/getting-started/standards/coordination-maintenance#releases) — how regressions are detected -- [Rollback procedures](/sdk/getting-started/standards/coordination-maintenance#releases) — emergency rollback process -- [Cutting a Release](/sdk/getting-started/playbooks/sdk-lifecycle/cutting-a-release) — standard release process (expedited for patches) +- [Post-release monitoring](/sdk/getting-started/standards/coordination-maintenance/#releases) — how regressions are detected +- [Rollback procedures](/sdk/getting-started/standards/coordination-maintenance/#releases) — emergency rollback process +- [Cutting a Release](/sdk/getting-started/playbooks/sdk-lifecycle/cutting-a-release/) — standard release process (expedited for patches) --- @@ -46,11 +46,11 @@ You **MUST** take one of the following actions: **Option A: Revert and patch** - Revert the problematic commit(s) on a release branch - Use the revert commit format: `revert: ` -- Cut a patch release following [Cutting a Release](/sdk/getting-started/playbooks/sdk-lifecycle/cutting-a-release), expedited — you **MAY** skip non-essential gates for critical severity +- Cut a patch release following [Cutting a Release](/sdk/getting-started/playbooks/sdk-lifecycle/cutting-a-release/), expedited — you **MAY** skip non-essential gates for critical severity **Option B: Yank the release** - If a clean revert isn't possible, yank the bad release from the package registry -- Follow the documented rollback procedure: [Rollback procedures](/sdk/getting-started/standards/coordination-maintenance#releases) +- Follow the documented rollback procedure: [Rollback procedures](/sdk/getting-started/standards/coordination-maintenance/#releases) #### 3. Communicate @@ -70,9 +70,9 @@ This helps identify gaps in testing, review processes, or monitoring that can be ## Referenced Standards -- [Post-release monitoring](/sdk/getting-started/standards/coordination-maintenance#releases) — monitoring that detects regressions -- [Rollback procedures](/sdk/getting-started/standards/coordination-maintenance#releases) — emergency rollback process -- [Release Gating Criteria](/sdk/getting-started/standards/review-ci#release-gating) — gates that may be expedited for critical patches +- [Post-release monitoring](/sdk/getting-started/standards/coordination-maintenance/#releases) — monitoring that detects regressions +- [Rollback procedures](/sdk/getting-started/standards/coordination-maintenance/#releases) — emergency rollback process +- [Release Gating Criteria](/sdk/getting-started/standards/review-ci/#release-gating) — gates that may be expedited for critical patches --- 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 be8d528945bef..86ae45b9135f3 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 @@ -23,11 +23,11 @@ spec_changelog: This playbook guides SDK maintainers through triaging and reviewing pull requests from external contributors. It covers timely triage, linked issue requirements, CI checks, saved replies for common patterns, and review processes for viable PRs. By following these steps, external contributors receive respectful, timely feedback that respects everyone's time. Related resources: -- [Review and CI Standards](/sdk/getting-started/standards/review-ci) — review SLAs and feedback conventions -- [Code Submission Standards](/sdk/getting-started/standards/code-submission) — PR description requirements -- [Saved Replies](/sdk/getting-started/templates/saved-replies) — GitHub saved replies for common scenarios -- [Reviewing a PR](/sdk/getting-started/playbooks/development/reviewing-a-pr) — standard review process -- [Reviewing AI-Generated Code](/sdk/getting-started/playbooks/development/reviewing-ai-generated-code) — AI-specific checks +- [Review and CI Standards](/sdk/getting-started/standards/review-ci/) — review SLAs and feedback conventions +- [Code Submission Standards](/sdk/getting-started/standards/code-submission/) — PR description requirements +- [Saved Replies](/sdk/getting-started/templates/saved-replies/) — GitHub saved replies for common scenarios +- [Reviewing a PR](/sdk/getting-started/playbooks/development/reviewing-a-pr/) — standard review process +- [Reviewing AI-Generated Code](/sdk/getting-started/playbooks/development/reviewing-ai-generated-code/) — AI-specific checks --- @@ -35,11 +35,11 @@ Related resources: #### 1. Triage within 2 business days -([Review SLAs](/sdk/getting-started/standards/review-ci#code-review)). Every external PR **REQUIRES** a timely, substantive response. +([Review SLAs](/sdk/getting-started/standards/review-ci/#code-review)). Every external PR **REQUIRES** a timely, substantive response. #### 2. Check for a linked issue -If the PR is non-trivial and has no linked issue, use the ["Open an issue first" saved reply](/sdk/getting-started/templates/saved-replies#closing-pull-requests) and close the PR. +If the PR is non-trivial and has no linked issue, use the ["Open an issue first" saved reply](/sdk/getting-started/templates/saved-replies/#closing-pull-requests) and close the PR. #### 3. Check CI status @@ -47,15 +47,15 @@ If checks are failing, comment specifically on what's broken and give the contri #### 4. Check for speculative refactors -If the PR is a style-only change or refactor with no linked issue or problem statement, use the ["Let's discuss the approach first" saved reply](/sdk/getting-started/templates/saved-replies#closing-pull-requests) and close the PR. +If the PR is a style-only change or refactor with no linked issue or problem statement, use the ["Let's discuss the approach first" saved reply](/sdk/getting-started/templates/saved-replies/#closing-pull-requests) and close the PR. #### 5. If the PR is viable -Review it using the standard process ([Reviewing a PR](/sdk/getting-started/playbooks/development/reviewing-a-pr)). If it appears AI-generated, also apply [AI-specific checks](/sdk/getting-started/playbooks/development/reviewing-ai-generated-code). +Review it using the standard process ([Reviewing a PR](/sdk/getting-started/playbooks/development/reviewing-a-pr/)). If it appears AI-generated, also apply [AI-specific checks](/sdk/getting-started/playbooks/development/reviewing-ai-generated-code/). #### 6. When requesting changes -You **MUST** be specific, use LOGAF prefixes ([Review feedback conventions](/sdk/getting-started/standards/review-ci#code-review)), and explain *why* — so the contributor (or their AI tool) can address the feedback effectively. +You **MUST** be specific, use LOGAF prefixes ([Review feedback conventions](/sdk/getting-started/standards/review-ci/#code-review)), and explain *why* — so the contributor (or their AI tool) can address the feedback effectively. #### 7. Closing fast is kind @@ -63,9 +63,9 @@ A 30-second close with a clear, respectful reason is better than a PR that sits ## Referenced Standards -- [Review SLAs](/sdk/getting-started/standards/review-ci#code-review) — timely response requirements -- [Review feedback conventions](/sdk/getting-started/standards/review-ci#code-review) — LOGAF scale for feedback -- [PR description quality](/sdk/getting-started/standards/code-submission#pr-description-quality) — linked issue requirement +- [Review SLAs](/sdk/getting-started/standards/review-ci/#code-review) — timely response requirements +- [Review feedback conventions](/sdk/getting-started/standards/review-ci/#code-review) — LOGAF scale for feedback +- [PR description quality](/sdk/getting-started/standards/code-submission/#pr-description-quality) — linked issue requirement --- 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 b5bd90b75541e..2d7a36fe47a02 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 @@ -27,9 +27,9 @@ spec_changelog: This playbook guides contributors through creating a well-structured pull request for an SDK repository. It covers branch naming, commit formatting, local verification, draft PR workflow, and review assignment. By following these steps, PRs will have proper documentation, pass CI checks, and be ready for efficient review. Related resources: -- [Code Submission Standards](/sdk/getting-started/standards/code-submission) — commit format, branch naming, and PR requirements +- [Code Submission Standards](/sdk/getting-started/standards/code-submission/) — commit format, branch naming, and PR requirements - [Sentry Skills](https://github.com/getsentry/skills#available-skills) — automation tools for commits and PRs -- [Repository Documentation Standards](/sdk/getting-started/standards/repository-docs) — documentation requirements +- [Repository Documentation Standards](/sdk/getting-started/standards/repository-docs/) — documentation requirements --- @@ -37,17 +37,17 @@ Related resources: #### 1. Branch from the default branch -You **MUST** use the naming convention `//` ([Branch naming](/sdk/getting-started/standards/code-submission#branch-naming)). +You **MUST** use the naming convention `//` ([Branch naming](/sdk/getting-started/standards/code-submission/#branch-naming)). Examples: `theo/feat/add-user-auth`, `alice/fix/rate-limit-parsing`. #### 2. Confirm a linked issue exists -If there isn't one, create it first — even for internal work. Non-trivial changes **REQUIRE** an issue before a PR ([PR description quality](/sdk/getting-started/standards/code-submission#pr-description-quality)). +If there isn't one, create it first — even for internal work. Non-trivial changes **REQUIRE** an issue before a PR ([PR description quality](/sdk/getting-started/standards/code-submission/#pr-description-quality)). #### 3. Write commits -You **MUST** use [conventional format](/sdk/getting-started/standards/code-submission#commit-message-format). If AI-assisted, you **MUST** add `Co-Authored-By` in the commit footer ([AI attribution](/sdk/getting-started/standards/code-submission#ai-attribution)). +You **MUST** use [conventional format](/sdk/getting-started/standards/code-submission/#commit-message-format). If AI-assisted, you **MUST** add `Co-Authored-By` in the commit footer ([AI attribution](/sdk/getting-started/standards/code-submission/#ai-attribution)). You **SHOULD** use the [`sentry-skills:commit`](https://github.com/getsentry/skills#available-skills) skill to create properly formatted commits. @@ -57,17 +57,17 @@ Tests **MUST** pass, linter **MUST** pass, and the SDK **MUST** build cleanly be #### 5. Open the PR as a draft -You **MUST** open PRs as drafts ([PR draft mode](/sdk/getting-started/standards/code-submission#pr-draft-mode)). +You **MUST** open PRs as drafts ([PR draft mode](/sdk/getting-started/standards/code-submission/#pr-draft-mode)). You **SHOULD** use the [`sentry-skills:create-pr`](https://github.com/getsentry/skills#available-skills) skill to create the PR with proper formatting. #### 6. Write the description -You **MUST** include: what changed, why, linked issue, and context for reviewers. No boilerplate, no test plan sections ([PR description quality](/sdk/getting-started/standards/code-submission#pr-description-quality)). +You **MUST** include: what changed, why, linked issue, and context for reviewers. No boilerplate, no test plan sections ([PR description quality](/sdk/getting-started/standards/code-submission/#pr-description-quality)). #### 7. If the change is user-facing -You **MUST** add a changelog entry ([Changelog entry](/sdk/getting-started/standards/code-submission#changelog-entry)) and open or link a docs PR ([Documentation-with-code](/sdk/getting-started/standards/repository-docs#documentation-with-code)). +You **MUST** add a changelog entry ([Changelog entry](/sdk/getting-started/standards/code-submission/#changelog-entry)) and open or link a docs PR ([Documentation-with-code](/sdk/getting-started/standards/repository-docs/#documentation-with-code)). #### 8. Wait for CI to pass @@ -75,20 +75,20 @@ When green, mark the PR as ready for review. #### 9. Assign 1–2 reviewers -If the PR touches public API, dependencies, or security-sensitive areas, you **MUST** assign an @sdk-seniors reviewer ([Required reviewers](/sdk/getting-started/standards/review-ci#code-review)). +If the PR touches public API, dependencies, or security-sensitive areas, you **MUST** assign an @sdk-seniors reviewer ([Required reviewers](/sdk/getting-started/standards/review-ci/#code-review)). ## Referenced Standards -- [Branch naming](/sdk/getting-started/standards/code-submission#branch-naming) — branch naming convention format -- [Commit message format](/sdk/getting-started/standards/code-submission#commit-message-format) — conventional commit structure -- [AI attribution](/sdk/getting-started/standards/code-submission#ai-attribution) — Co-Authored-By footer requirement -- [PR draft mode](/sdk/getting-started/standards/code-submission#pr-draft-mode) — draft PR workflow -- [PR description quality](/sdk/getting-started/standards/code-submission#pr-description-quality) — description content requirements -- [Changelog entry](/sdk/getting-started/standards/code-submission#changelog-entry) — user-facing change documentation -- [One logical change per PR](/sdk/getting-started/standards/code-submission#one-logical-change-per-pr) — focused PR scope -- [Documentation-with-code](/sdk/getting-started/standards/repository-docs#documentation-with-code) — docs PR requirements -- [Required reviewers](/sdk/getting-started/standards/review-ci#code-review) — @sdk-seniors review triggers -- [Test requirements by change type](/sdk/getting-started/standards/code-quality#testing) — test coverage requirements +- [Branch naming](/sdk/getting-started/standards/code-submission/#branch-naming) — branch naming convention format +- [Commit message format](/sdk/getting-started/standards/code-submission/#commit-message-format) — conventional commit structure +- [AI attribution](/sdk/getting-started/standards/code-submission/#ai-attribution) — Co-Authored-By footer requirement +- [PR draft mode](/sdk/getting-started/standards/code-submission/#pr-draft-mode) — draft PR workflow +- [PR description quality](/sdk/getting-started/standards/code-submission/#pr-description-quality) — description content requirements +- [Changelog entry](/sdk/getting-started/standards/code-submission/#changelog-entry) — user-facing change documentation +- [One logical change per PR](/sdk/getting-started/standards/code-submission/#one-logical-change-per-pr) — focused PR scope +- [Documentation-with-code](/sdk/getting-started/standards/repository-docs/#documentation-with-code) — docs PR requirements +- [Required reviewers](/sdk/getting-started/standards/review-ci/#code-review) — @sdk-seniors review triggers +- [Test requirements by change type](/sdk/getting-started/standards/code-quality/#testing) — test coverage requirements --- 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 0b93ecadfddbf..8ea96b9afd887 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 @@ -25,8 +25,8 @@ spec_changelog: This playbook guides reviewers through conducting effective code reviews for SDK pull requests. It covers PR description validation, CI verification, code quality assessment, and feedback conventions using the LOGAF scale. By following these steps, reviews will focus on risk reduction, maintain consistent quality standards, and provide actionable feedback. Related resources: -- [Review and CI Standards](/sdk/getting-started/standards/review-ci) — review requirements and feedback conventions -- [Code Quality Standards](/sdk/getting-started/standards/code-quality) — test requirements and quality criteria +- [Review and CI Standards](/sdk/getting-started/standards/review-ci/) — review requirements and feedback conventions +- [Code Quality Standards](/sdk/getting-started/standards/code-quality/) — test requirements and quality criteria - [Sentry code review checklist](/engineering-practices/code-review/) — detailed review criteria - [Sentry Skills](https://github.com/getsentry/skills#available-skills) — code-review skill for automated checks @@ -56,18 +56,18 @@ Use the [code review checklist](/engineering-practices/code-review/). You **MUST - Unintended side effects or behavior changes - Backwards compatibility - Security vulnerabilities -- Test coverage appropriate for the change type ([Test requirements by change type](/sdk/getting-started/standards/code-quality#testing)) -- Test quality — do assertions verify real behavior? ([Test quality](/sdk/getting-started/standards/code-quality#testing)) +- Test coverage appropriate for the change type ([Test requirements by change type](/sdk/getting-started/standards/code-quality/#testing)) +- Test quality — do assertions verify real behavior? ([Test quality](/sdk/getting-started/standards/code-quality/#testing)) You **SHOULD** use the [`sentry-skills:code-review`](https://github.com/getsentry/skills#available-skills) skill to systematically check for issues. #### 4. Check for @sdk-seniors review triggers -([Required reviewers](/sdk/getting-started/standards/review-ci#code-review)): public API changes, new dependencies, schema changes, security-sensitive code, new frameworks. If any apply and no @sdk-seniors reviewer is assigned, flag it. +([Required reviewers](/sdk/getting-started/standards/review-ci/#code-review)): public API changes, new dependencies, schema changes, security-sensitive code, new frameworks. If any apply and no @sdk-seniors reviewer is assigned, flag it. #### 5. Use LOGAF prefixes on all feedback -You **MUST** use LOGAF prefixes on all feedback ([Review feedback conventions](/sdk/getting-started/standards/review-ci#code-review)): +You **MUST** use LOGAF prefixes on all feedback ([Review feedback conventions](/sdk/getting-started/standards/review-ci/#code-review)): - `h:` (high) — must fix before merge. Bugs, security issues, breakage, data loss. - `m:` (medium) — should fix. Design concerns, missing tests, unclear code. - `l:` (low) — optional nit. Style preferences, minor suggestions. @@ -78,12 +78,12 @@ You **MUST NOT** block for style preferences. The goal is risk reduction, not pe ## Referenced Standards -- [Review feedback conventions](/sdk/getting-started/standards/review-ci#code-review) — LOGAF scale and blocking criteria -- [Required reviewers](/sdk/getting-started/standards/review-ci#code-review) — @sdk-seniors review triggers -- [Required CI checks baseline](/sdk/getting-started/standards/review-ci#required-ci-checks) — minimum CI requirements -- [Test requirements by change type](/sdk/getting-started/standards/code-quality#testing) — test coverage expectations -- [Test quality](/sdk/getting-started/standards/code-quality#testing) — meaningful assertion requirements -- [PR description quality](/sdk/getting-started/standards/code-submission#pr-description-quality) — description content requirements +- [Review feedback conventions](/sdk/getting-started/standards/review-ci/#code-review) — LOGAF scale and blocking criteria +- [Required reviewers](/sdk/getting-started/standards/review-ci/#code-review) — @sdk-seniors review triggers +- [Required CI checks baseline](/sdk/getting-started/standards/review-ci/#required-ci-checks) — minimum CI requirements +- [Test requirements by change type](/sdk/getting-started/standards/code-quality/#testing) — test coverage expectations +- [Test quality](/sdk/getting-started/standards/code-quality/#testing) — meaningful assertion requirements +- [PR description quality](/sdk/getting-started/standards/code-submission/#pr-description-quality) — description content requirements --- 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 7b84b08e37af5..3f737c67a670c 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 @@ -25,15 +25,15 @@ spec_changelog: This playbook extends the standard code review process with AI-specific checks for common failure modes in AI-generated code. It covers hallucinated imports, meaningless tests, over-engineering, speculative changes, missing context, and subtle behavior changes. By following these steps, reviewers will catch issues that automated tools miss while maintaining the same quality standards as human-written code. Related resources: -- [Reviewing a PR](/sdk/getting-started/playbooks/development/reviewing-a-pr) — base review process -- [Code Quality Standards](/sdk/getting-started/standards/code-quality) — test quality requirements +- [Reviewing a PR](/sdk/getting-started/playbooks/development/reviewing-a-pr/) — base review process +- [Code Quality Standards](/sdk/getting-started/standards/code-quality/) — test quality requirements - [Sentry Skills](https://github.com/getsentry/skills#available-skills) — find-bugs skill for systematic detection --- ## Standard review first -Apply the full review checklist from [Reviewing a PR](/sdk/getting-started/playbooks/development/reviewing-a-pr): +Apply the full review checklist from [Reviewing a PR](/sdk/getting-started/playbooks/development/reviewing-a-pr/): #### 1. Check the PR description @@ -45,7 +45,7 @@ You **MUST NOT** review failing code. #### 3. Review for common issues -Runtime errors, performance, side effects, backwards compatibility, security, test coverage ([Test requirements by change type](/sdk/getting-started/standards/code-quality#testing)), test quality ([Test quality](/sdk/getting-started/standards/code-quality#testing)). +Runtime errors, performance, side effects, backwards compatibility, security, test coverage ([Test requirements by change type](/sdk/getting-started/standards/code-quality/#testing)), test quality ([Test quality](/sdk/getting-started/standards/code-quality/#testing)). #### 4. Check @sdk-seniors review triggers @@ -53,7 +53,7 @@ Public API, dependencies, schema changes, security-sensitive code, frameworks. #### 5. Use LOGAF prefixes on feedback -([Review feedback conventions](/sdk/getting-started/standards/review-ci#code-review)) +([Review feedback conventions](/sdk/getting-started/standards/review-ci/#code-review)) #### 6. Approve when only `l:` items remain @@ -69,7 +69,7 @@ Verify every import and function call actually exists. AI tools sometimes refere #### 2. Tests that test nothing -You **MUST** check that test assertions would actually fail if the feature broke ([Test quality](/sdk/getting-started/standards/code-quality#testing)). Watch for: hardcoded expected values that happen to match the output, `assert True` or equivalents, testing mock behavior instead of real behavior, asserting only that no exception was thrown. +You **MUST** check that test assertions would actually fail if the feature broke ([Test quality](/sdk/getting-started/standards/code-quality/#testing)). Watch for: hardcoded expected values that happen to match the output, `assert True` or equivalents, testing mock behavior instead of real behavior, asserting only that no exception was thrown. #### 3. Over-engineering @@ -77,7 +77,7 @@ AI tools frequently add unnecessary abstractions, configuration options, and err #### 4. Speculative changes -Code changes beyond what the issue or PR describes ([One logical change per PR](/sdk/getting-started/standards/code-submission#one-logical-change-per-pr)). If the PR is "fix null check" but also reorganizes imports and adds docstrings, request a split. +Code changes beyond what the issue or PR describes ([One logical change per PR](/sdk/getting-started/standards/code-submission/#one-logical-change-per-pr)). If the PR is "fix null check" but also reorganizes imports and adds docstrings, request a split. #### 5. Missing architecture context @@ -91,11 +91,11 @@ You **SHOULD** use the [`sentry-skills:find-bugs`](https://github.com/getsentry/ ## Referenced Standards -- [Review feedback conventions](/sdk/getting-started/standards/review-ci#code-review) — LOGAF scale and blocking criteria -- [Test requirements by change type](/sdk/getting-started/standards/code-quality#testing) — test coverage expectations -- [Test quality](/sdk/getting-started/standards/code-quality#testing) — meaningful assertion requirements -- [AI attribution](/sdk/getting-started/standards/code-submission#ai-attribution) — Co-Authored-By footer requirement -- [One logical change per PR](/sdk/getting-started/standards/code-submission#one-logical-change-per-pr) — focused PR scope +- [Review feedback conventions](/sdk/getting-started/standards/review-ci/#code-review) — LOGAF scale and blocking criteria +- [Test requirements by change type](/sdk/getting-started/standards/code-quality/#testing) — test coverage expectations +- [Test quality](/sdk/getting-started/standards/code-quality/#testing) — meaningful assertion requirements +- [AI attribution](/sdk/getting-started/standards/code-submission/#ai-attribution) — Co-Authored-By footer requirement +- [One logical change per PR](/sdk/getting-started/standards/code-submission/#one-logical-change-per-pr) — focused PR scope --- 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 3721b3db2abc1..54fc19e6ca480 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 @@ -24,11 +24,11 @@ This playbook guides SDK maintainers through deciding whether a change is breaki Related resources: -- [Breaking change process](/sdk/getting-started/standards/api-architecture#breaking-and-deprecation) — when a major release is required and what every breaking change must include -- [Deprecation lifecycle](/sdk/getting-started/standards/api-architecture#breaking-and-deprecation) — the deprecation stages and timelines -- [Deprecating an API](/sdk/getting-started/playbooks/sdk-lifecycle/deprecating-an-api) — step-by-step deprecation workflow -- [Deprecating an SDK](/sdk/getting-started/playbooks/sdk-lifecycle/deprecating-an-sdk) — full SDK deprecation process -- [Release and Versioning](/sdk/getting-started/standards/release-versioning) — SemVer requirements and release tooling +- [Breaking change process](/sdk/getting-started/standards/api-architecture/#breaking-and-deprecation) — when a major release is required and what every breaking change must include +- [Deprecation lifecycle](/sdk/getting-started/standards/api-architecture/#breaking-and-deprecation) — the deprecation stages and timelines +- [Deprecating an API](/sdk/getting-started/playbooks/sdk-lifecycle/deprecating-an-api/) — step-by-step deprecation workflow +- [Deprecating an SDK](/sdk/getting-started/playbooks/sdk-lifecycle/deprecating-an-sdk/) — full SDK deprecation process +- [Release and Versioning](/sdk/getting-started/standards/release-versioning/) — SemVer requirements and release tooling --- @@ -73,7 +73,7 @@ For product-side changes, estimate how many users are affected before deciding o #### 3. Decide on release scope -Breaking changes **MUST** ship in a major version and **MUST NOT** ship in minor versions, per the [Breaking change process](/sdk/getting-started/standards/api-architecture#breaking-and-deprecation). Use the classification and impact data from the previous steps to plan the release. +Breaking changes **MUST** ship in a major version and **MUST NOT** ship in minor versions, per the [Breaking change process](/sdk/getting-started/standards/api-architecture/#breaking-and-deprecation). Use the classification and impact data from the previous steps to plan the release. Consider the following when planning: @@ -83,13 +83,13 @@ Consider the following when planning: #### 4. Add deprecation warnings and a compatibility layer -In a prior minor release, prepare users for the upcoming change per the [Deprecation lifecycle](/sdk/getting-started/standards/api-architecture#breaking-and-deprecation): +In a prior minor release, prepare users for the upcoming change per the [Deprecation lifecycle](/sdk/getting-started/standards/api-architecture/#breaking-and-deprecation): - Add runtime deprecation warnings that include: what is changing, what to use instead, and a link to migration docs - Where feasible, support a transitional phase where both the old and new behavior work — an SDK option acting as a feature flag is a good pattern - Maintain deprecated APIs until the major release that removes them -For full step-by-step deprecation guidance, follow the [Deprecating an API](/sdk/getting-started/playbooks/sdk-lifecycle/deprecating-an-api) playbook. +For full step-by-step deprecation guidance, follow the [Deprecating an API](/sdk/getting-started/playbooks/sdk-lifecycle/deprecating-an-api/) playbook. #### 5. Write a migration guide @@ -125,9 +125,9 @@ If you do not have access, reach out to @sdk-seniors, the Data team or request a ## Referenced Standards -- [Breaking change process](/sdk/getting-started/standards/api-architecture#breaking-and-deprecation) — when a major release is required, required artifacts, and enforcement -- [Deprecation lifecycle](/sdk/getting-started/standards/api-architecture#breaking-and-deprecation) — deprecation timeline and stages -- [Version format](/sdk/getting-started/standards/release-versioning#version-format) — SemVer requirements for major version bumps +- [Breaking change process](/sdk/getting-started/standards/api-architecture/#breaking-and-deprecation) — when a major release is required, required artifacts, and enforcement +- [Deprecation lifecycle](/sdk/getting-started/standards/api-architecture/#breaking-and-deprecation) — deprecation timeline and stages +- [Version format](/sdk/getting-started/standards/release-versioning/#version-format) — SemVer requirements for major version bumps --- 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 14236f40c2b5e..e46c3f0ccce21 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 @@ -28,9 +28,9 @@ This playbook guides SDK maintainers through cutting a release for an SDK reposi All Sentry SDKs use [Craft](https://github.com/getsentry/craft) for release automation via GitHub Actions. Releases are **always** triggered through CI — never from a local machine. The process follows a prepare → publish workflow coordinated through the [getsentry/publish](https://github.com/getsentry/publish) repository, with a mandatory two-person approval requirement. Related resources: -- [Review and CI Standards](/sdk/getting-started/standards/review-ci) — release gating criteria -- [Coordination and Maintenance Standards](/sdk/getting-started/standards/coordination-maintenance) — post-release monitoring and rollback procedures -- [Handling a Regression](/sdk/getting-started/playbooks/development/handling-a-regression) — regression response process +- [Review and CI Standards](/sdk/getting-started/standards/review-ci/) — release gating criteria +- [Coordination and Maintenance Standards](/sdk/getting-started/standards/coordination-maintenance/) — post-release monitoring and rollback procedures +- [Handling a Regression](/sdk/getting-started/playbooks/development/handling-a-regression/) — regression response process - Your SDK's `CONTRIBUTING.md` or release documentation — SDK-specific procedures and tooling details --- @@ -39,7 +39,7 @@ Related resources: #### 1. Verify release gating criteria -You **MUST** verify all criteria pass ([Release gating criteria](/sdk/getting-started/standards/review-ci#release-gating)): +You **MUST** verify all criteria pass ([Release gating criteria](/sdk/getting-started/standards/review-ci/#release-gating)): - All required CI checks pass on the default branch - No unresolved `h:` (high) review comments on merged PRs since last release - Changelog is substantive (not empty or internal-only for a release with user-facing changes) @@ -84,14 +84,14 @@ The artifact **MUST** be published and installable. Quick smoke test: install th #### 6. Post-release monitoring -You **MUST** follow post-release monitoring procedures ([Post-release monitoring](/sdk/getting-started/standards/coordination-maintenance#releases)): +You **MUST** follow post-release monitoring procedures ([Post-release monitoring](/sdk/getting-started/standards/coordination-maintenance/#releases)): - Check SDK crash detection within 24 hours - Verify dogfooding (Sentry's own products) picks up the new version - Monitor the issue tracker for regression reports for 48 hours #### 7. If a critical regression is found -Trigger the [Handling a Regression](/sdk/getting-started/playbooks/development/handling-a-regression) process. +Trigger the [Handling a Regression](/sdk/getting-started/playbooks/development/handling-a-regression/) process. --- @@ -111,9 +111,9 @@ Common SDK-specific variations include: ## Referenced Standards -- [Release gating criteria](/sdk/getting-started/standards/review-ci#release-gating) — pre-release quality gates -- [Post-release monitoring](/sdk/getting-started/standards/coordination-maintenance#releases) — monitoring requirements and timeline -- [Rollback procedures](/sdk/getting-started/standards/coordination-maintenance#releases) — emergency rollback process +- [Release gating criteria](/sdk/getting-started/standards/review-ci/#release-gating) — pre-release quality gates +- [Post-release monitoring](/sdk/getting-started/standards/coordination-maintenance/#releases) — monitoring requirements and timeline +- [Rollback procedures](/sdk/getting-started/standards/coordination-maintenance/#releases) — emergency rollback process --- 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 1c38b72f27954..5f07d53ef8933 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 @@ -25,9 +25,9 @@ spec_changelog: This playbook guides SDK maintainers through deprecating an API in a way that minimizes user disruption. It covers deprecation announcements, migration guide creation, maintenance periods, and eventual removal. By following these steps, users will have clear migration paths and sufficient time to adapt. Related resources: -- [Deprecation lifecycle](/sdk/getting-started/standards/api-architecture#breaking-and-deprecation) — deprecation timeline and requirements -- [Breaking change process](/sdk/getting-started/standards/api-architecture#breaking-and-deprecation) — process for eventual API removal -- [Aligning Cross-SDK Changes](/sdk/getting-started/playbooks/coordination/aligning-cross-sdk-changes) — coordinating deprecations across multiple SDKs +- [Deprecation lifecycle](/sdk/getting-started/standards/api-architecture/#breaking-and-deprecation) — deprecation timeline and requirements +- [Breaking change process](/sdk/getting-started/standards/api-architecture/#breaking-and-deprecation) — process for eventual API removal +- [Aligning Cross-SDK Changes](/sdk/getting-started/playbooks/coordination/aligning-cross-sdk-changes/) — coordinating deprecations across multiple SDKs --- @@ -35,7 +35,7 @@ Related resources: #### 1. If this is a multi-SDK deprecation -If the deprecation affects multiple Sentry SDKs, you **MUST** follow the [Aligning Cross-SDK Changes](/sdk/getting-started/playbooks/coordination/aligning-cross-sdk-changes) process first to coordinate timing and approach across SDK teams. +If the deprecation affects multiple Sentry SDKs, you **MUST** follow the [Aligning Cross-SDK Changes](/sdk/getting-started/playbooks/coordination/aligning-cross-sdk-changes/) process first to coordinate timing and approach across SDK teams. #### 2. Announce in a minor release @@ -46,7 +46,7 @@ In the minor release where the API is deprecated, you **MUST**: - A code example of the migration - A link to documentation - Add a changelog entry explaining the deprecation and the migration path -- Open a docs PR with a migration guide containing copy-pastable before/after examples ([Documentation-with-Code](/sdk/getting-started/standards/repository-docs#documentation-with-code)) +- Open a docs PR with a migration guide containing copy-pastable before/after examples ([Documentation-with-Code](/sdk/getting-started/standards/repository-docs/#documentation-with-code)) - Test the migration guide by having an AI tool follow it — if the tool can't complete the migration, rewrite the guide #### 3. Maintain the deprecated API @@ -60,7 +60,7 @@ This gives users time to migrate without breaking their applications immediately When removing the deprecated API in a major version, you **MUST**: - Remove the API and its tests -- Include `BREAKING CHANGE:` in the commit footer ([Breaking change process](/sdk/getting-started/standards/api-architecture#breaking-and-deprecation)) +- Include `BREAKING CHANGE:` in the commit footer ([Breaking change process](/sdk/getting-started/standards/api-architecture/#breaking-and-deprecation)) - Update the migration guide to reference the major version that removes it #### 5. Communicate @@ -73,10 +73,10 @@ For high-impact deprecations, you **SHOULD** consider a blog post or announcemen ## Referenced Standards -- [Deprecation lifecycle](/sdk/getting-started/standards/api-architecture#breaking-and-deprecation) — deprecation timeline requirements -- [Breaking change process](/sdk/getting-started/standards/api-architecture#breaking-and-deprecation) — process for API removal in major versions -- [Documentation-with-Code](/sdk/getting-started/standards/repository-docs#documentation-with-code) — copy-pastable migration examples requirement -- [Cross-SDK Coordination standard](/sdk/getting-started/standards/coordination-maintenance#cross-sdk-coordination) — coordinating multi-SDK changes +- [Deprecation lifecycle](/sdk/getting-started/standards/api-architecture/#breaking-and-deprecation) — deprecation timeline requirements +- [Breaking change process](/sdk/getting-started/standards/api-architecture/#breaking-and-deprecation) — process for API removal in major versions +- [Documentation-with-Code](/sdk/getting-started/standards/repository-docs/#documentation-with-code) — copy-pastable migration examples requirement +- [Cross-SDK Coordination standard](/sdk/getting-started/standards/coordination-maintenance/#cross-sdk-coordination) — coordinating multi-SDK changes --- 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 31773b4552e00..40ed6e5562adb 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 @@ -20,15 +20,15 @@ spec_changelog: ## Overview -This playbook guides SDK maintainers through deprecating an entire SDK. Unlike [deprecating an API](/sdk/getting-started/playbooks/sdk-lifecycle/deprecating-an-api) or [dropping a platform version](/sdk/getting-started/playbooks/sdk-lifecycle/dropping-platform-support), deprecating an SDK means ending all active development and eventually archiving the repository. It covers impact analysis, approval, final release, public announcement, documentation updates, package registry deprecation, repo archival, and post-EOL cleanup. +This playbook guides SDK maintainers through deprecating an entire SDK. Unlike [deprecating an API](/sdk/getting-started/playbooks/sdk-lifecycle/deprecating-an-api/) or [dropping a platform version](/sdk/getting-started/playbooks/sdk-lifecycle/dropping-platform-support/), deprecating an SDK means ending all active development and eventually archiving the repository. It covers impact analysis, approval, final release, public announcement, documentation updates, package registry deprecation, repo archival, and post-EOL cleanup. Related resources: -- [Deprecation lifecycle](/sdk/getting-started/standards/api-architecture#breaking-changes-and-deprecations) — deprecation timeline and requirements -- [Documenting decisions](/sdk/getting-started/standards/coordination-maintenance#documenting-decisions) — traceability requirement for decisions -- [Cutting a Release](/sdk/getting-started/playbooks/sdk-lifecycle/cutting-a-release) — release process for the final release -- [Deprecating an API](/sdk/getting-started/playbooks/sdk-lifecycle/deprecating-an-api) — related playbook for API-level deprecation -- [Dropping Platform or Language Version Support](/sdk/getting-started/playbooks/sdk-lifecycle/dropping-platform-support) — related playbook for version-level support drops +- [Deprecation lifecycle](/sdk/getting-started/standards/api-architecture/#breaking-changes-and-deprecations) — deprecation timeline and requirements +- [Documenting decisions](/sdk/getting-started/standards/coordination-maintenance/#documenting-decisions) — traceability requirement for decisions +- [Cutting a Release](/sdk/getting-started/playbooks/sdk-lifecycle/cutting-a-release/) — release process for the final release +- [Deprecating an API](/sdk/getting-started/playbooks/sdk-lifecycle/deprecating-an-api/) — related playbook for API-level deprecation +- [Dropping Platform or Language Version Support](/sdk/getting-started/playbooks/sdk-lifecycle/dropping-platform-support/) — related playbook for version-level support drops Two examples of this are [sentry-cordova](https://github.com/getsentry/sentry-cordova) (archived March 2026, users migrated to Capacitor, React Native, or Flutter) and [sentry-xamarin](https://github.com/getsentry/sentry-xamarin) (archived after Xamarin reached end of life, users migrated to .NET MAUI via `sentry-dotnet`). @@ -68,7 +68,7 @@ You **MUST** confirm that affected users have a viable path forward: #### 4. Get approval -Work with the engineering manager responsible for the SDK to get approval. The decision **MUST** be documented in Linear or GitHub per the [Documenting decisions](/sdk/getting-started/standards/coordination-maintenance#documenting-decisions) standard. +Work with the engineering manager responsible for the SDK to get approval. The decision **MUST** be documented in Linear or GitHub per the [Documenting decisions](/sdk/getting-started/standards/coordination-maintenance/#documenting-decisions) standard. --- @@ -78,7 +78,7 @@ Once approved, execute these steps in sequence. The order matters — cut the fi #### 5. Cut a final release -You **SHOULD** cut a final release with up-to-date dependencies to give users a stable baseline. Follow the [Cutting a Release](/sdk/getting-started/playbooks/sdk-lifecycle/cutting-a-release) playbook. Even if the release contains no new features, a clean final release is better than leaving users on a months-old version. The changelog **SHOULD** note that this is the final planned release and that the SDK is entering deprecation. +You **SHOULD** cut a final release with up-to-date dependencies to give users a stable baseline. Follow the [Cutting a Release](/sdk/getting-started/playbooks/sdk-lifecycle/cutting-a-release/) playbook. Even if the release contains no new features, a clean final release is better than leaving users on a months-old version. The changelog **SHOULD** note that this is the final planned release and that the SDK is entering deprecation. #### 6. Create a public deprecation announcement @@ -152,9 +152,9 @@ After a grace period (6–12 months post-archival), you **SHOULD**: ## Referenced Standards -- [Deprecation lifecycle](/sdk/getting-started/standards/api-architecture#breaking-changes-and-deprecations) — deprecation timeline and stages -- [Documenting decisions](/sdk/getting-started/standards/coordination-maintenance#documenting-decisions) — traceability requirement -- [Cutting a Release](/sdk/getting-started/playbooks/sdk-lifecycle/cutting-a-release) — release process for the final release +- [Deprecation lifecycle](/sdk/getting-started/standards/api-architecture/#breaking-changes-and-deprecations) — deprecation timeline and stages +- [Documenting decisions](/sdk/getting-started/standards/coordination-maintenance/#documenting-decisions) — traceability requirement +- [Cutting a Release](/sdk/getting-started/playbooks/sdk-lifecycle/cutting-a-release/) — release process for the final release --- 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 393aa3ffe3728..18d27d63fc51d 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 @@ -24,10 +24,10 @@ This playbook guides SDK maintainers through dropping support for a platform or Related resources: -- [Platform/language version support policy](/sdk/getting-started/standards/coordination-maintenance#platformlanguage-version-support-policy) — support policy and requirements -- [Breaking change process](/sdk/getting-started/standards/api-architecture#breaking-and-deprecation) — process for removal in major versions -- [Deprecation lifecycle](/sdk/getting-started/standards/api-architecture#breaking-and-deprecation) — deprecation timeline -- [Deprecating an SDK](/sdk/getting-started/playbooks/sdk-lifecycle/deprecating-an-sdk) — when deprecating the entire SDK, not just a platform version +- [Platform/language version support policy](/sdk/getting-started/standards/coordination-maintenance/#platformlanguage-version-support-policy) — support policy and requirements +- [Breaking change process](/sdk/getting-started/standards/api-architecture/#breaking-and-deprecation) — process for removal in major versions +- [Deprecation lifecycle](/sdk/getting-started/standards/api-architecture/#breaking-and-deprecation) — deprecation timeline +- [Deprecating an SDK](/sdk/getting-started/playbooks/sdk-lifecycle/deprecating-an-sdk/) — when deprecating the entire SDK, not just a platform version --- @@ -63,7 +63,7 @@ When removing support in a major version, you **MUST**: - Drop the version from the CI test matrix - Update documentation (README, docs site) to reflect the removed support -- Include `BREAKING CHANGE:` in the commit footer ([Breaking change process](/sdk/getting-started/standards/api-architecture#breaking-and-deprecation)) +- Include `BREAKING CHANGE:` in the commit footer ([Breaking change process](/sdk/getting-started/standards/api-architecture/#breaking-and-deprecation)) #### 5. Provide migration guidance @@ -75,9 +75,9 @@ This helps users understand the upgrade path and avoid breaking their applicatio ## Referenced Standards -- [Breaking change process](/sdk/getting-started/standards/api-architecture#breaking-and-deprecation) — process for removal in major versions -- [Deprecation lifecycle](/sdk/getting-started/standards/api-architecture#breaking-and-deprecation) — deprecation timeline requirements -- [Platform/language version support policy](/sdk/getting-started/standards/coordination-maintenance#platformlanguage-version-support-policy) — support policy baseline +- [Breaking change process](/sdk/getting-started/standards/api-architecture/#breaking-and-deprecation) — process for removal in major versions +- [Deprecation lifecycle](/sdk/getting-started/standards/api-architecture/#breaking-and-deprecation) — deprecation timeline requirements +- [Platform/language version support policy](/sdk/getting-started/standards/coordination-maintenance/#platformlanguage-version-support-policy) — support policy baseline --- 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 99f41a7ff7391..ba2142bb1d36b 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 @@ -29,8 +29,8 @@ spec_changelog: This playbook guides SDK maintainers through setting up a new SDK repository from scratch. It covers repository scaffolding, required documentation files, CI pipeline configuration, and verification steps to ensure AI tools can effectively contribute. By following these steps, the repository will have proper branch protection, documentation, testing infrastructure, and release automation in place. Related resources: -- [Repository Documentation Standards](/sdk/getting-started/standards/repository-docs) — required files and AI context -- [Review and CI Standards](/sdk/getting-started/standards/review-ci) — CI checks and review requirements +- [Repository Documentation Standards](/sdk/getting-started/standards/repository-docs/) — required files and AI context +- [Review and CI Standards](/sdk/getting-started/standards/review-ci/) — CI checks and review requirements - [Sentry Skills](https://github.com/getsentry/skills#available-skills) — automation tools for commits, PRs, and AGENTS.md --- @@ -40,8 +40,8 @@ Related resources: #### 1. Repository scaffolding Create the repository in the `getsentry` organization. You **MUST** configure branch protection rules: -- Require CI checks to pass ([Required CI checks baseline](/sdk/getting-started/standards/review-ci#required-ci-checks)) -- Require at least one approving review ([Required reviewers](/sdk/getting-started/standards/review-ci#code-review)) +- Require CI checks to pass ([Required CI checks baseline](/sdk/getting-started/standards/review-ci/#required-ci-checks)) +- Require at least one approving review ([Required reviewers](/sdk/getting-started/standards/review-ci/#code-review)) You **MUST** set up a `CODEOWNERS` file with team members to automatically request reviews. @@ -49,9 +49,9 @@ You **MUST** set up a `CODEOWNERS` file with team members to automatically reque You **MUST** create the following files: -- `AGENTS.md` ([AGENTS.md](/sdk/getting-started/standards/repository-docs#repo-files)) — Use the [AGENTS.md template](/sdk/getting-started/templates/agents-md). You **SHOULD** use the [`sentry-skills:agents-md`](https://github.com/getsentry/skills#available-skills) skill to generate initial content. -- `CONTRIBUTING.md` ([CONTRIBUTING.md](/sdk/getting-started/standards/repository-docs#repo-files)) — Use the [CONTRIBUTING.md template](/sdk/getting-started/templates/contributing-md), customized for this SDK. -- `.github/PULL_REQUEST_TEMPLATE.md` ([PR template](/sdk/getting-started/standards/repository-docs#repo-files)) — Use the [PR template](/sdk/getting-started/templates/pr-template). +- `AGENTS.md` ([AGENTS.md](/sdk/getting-started/standards/repository-docs/#repo-files)) — Use the [AGENTS.md template](/sdk/getting-started/templates/agents-md/). You **SHOULD** use the [`sentry-skills:agents-md`](https://github.com/getsentry/skills#available-skills) skill to generate initial content. +- `CONTRIBUTING.md` ([CONTRIBUTING.md](/sdk/getting-started/standards/repository-docs/#repo-files)) — Use the [CONTRIBUTING.md template](/sdk/getting-started/templates/contributing-md/), customized for this SDK. +- `.github/PULL_REQUEST_TEMPLATE.md` ([PR template](/sdk/getting-started/standards/repository-docs/#repo-files)) — Use the [PR template](/sdk/getting-started/templates/pr-template/). - `CHANGELOG.md` or equivalent - `LICENSE` file @@ -61,15 +61,15 @@ Set up CI with at minimum: You **MUST** configure: - Build verification -- Linting ([Linting and formatting in CI](/sdk/getting-started/standards/code-quality#linting-and-type-checking)) -- Type checking, if applicable for the language ([Type checking in CI](/sdk/getting-started/standards/code-quality#linting-and-type-checking)) +- Linting ([Linting and formatting in CI](/sdk/getting-started/standards/code-quality/#linting-and-type-checking)) +- Type checking, if applicable for the language ([Type checking in CI](/sdk/getting-started/standards/code-quality/#linting-and-type-checking)) - Test suite -- Commit message format check ([Commit message format](/sdk/getting-started/standards/code-submission#commit-message-format)) -- Secret scanning ([Security practices](/sdk/getting-started/standards/code-quality#security-practices)) +- Commit message format check ([Commit message format](/sdk/getting-started/standards/code-submission/#commit-message-format)) +- Secret scanning ([Security practices](/sdk/getting-started/standards/code-quality/#security-practices)) #### 4. AI context files -You **MUST** create AI context files ([AI context file maintenance](/sdk/getting-started/standards/repository-docs#ai-context)): +You **MUST** create AI context files ([AI context file maintenance](/sdk/getting-started/standards/repository-docs/#ai-context)): - `AGENTS.md` — required You **SHOULD** create: @@ -86,7 +86,7 @@ You **MUST** configure release automation: #### 6. Rollback documentation -You **MUST** document rollback procedures ([Rollback procedures](/sdk/getting-started/standards/coordination-maintenance#releases)): +You **MUST** document rollback procedures ([Rollback procedures](/sdk/getting-started/standards/coordination-maintenance/#releases)): - Who can publish and yank releases (at least two people) - How to yank a release from the package registry - Backup contact if the primary publisher is unavailable @@ -105,17 +105,17 @@ If the tool cannot do this, the documentation needs work. ## Referenced Standards -- [AGENTS.md](/sdk/getting-started/standards/repository-docs#repo-files) — AI context file requirements -- [CONTRIBUTING.md](/sdk/getting-started/standards/repository-docs#repo-files) — contributor guidelines -- [PR template](/sdk/getting-started/standards/repository-docs#repo-files) — pull request template structure -- [AI context file maintenance](/sdk/getting-started/standards/repository-docs#ai-context) — maintaining AI-readable documentation -- [Required reviewers](/sdk/getting-started/standards/review-ci#code-review) — review approval requirements -- [Required CI checks baseline](/sdk/getting-started/standards/review-ci#required-ci-checks) — minimum CI pipeline requirements -- [Commit message format](/sdk/getting-started/standards/code-submission#commit-message-format) — conventional commit format -- [Linting and formatting in CI](/sdk/getting-started/standards/code-quality#linting-and-type-checking) — automated code style checks -- [Type checking in CI](/sdk/getting-started/standards/code-quality#linting-and-type-checking) — static type verification -- [Security practices](/sdk/getting-started/standards/code-quality#security-practices) — secret scanning and security checks -- [Rollback procedures](/sdk/getting-started/standards/coordination-maintenance#releases) — release rollback documentation +- [AGENTS.md](/sdk/getting-started/standards/repository-docs/#repo-files) — AI context file requirements +- [CONTRIBUTING.md](/sdk/getting-started/standards/repository-docs/#repo-files) — contributor guidelines +- [PR template](/sdk/getting-started/standards/repository-docs/#repo-files) — pull request template structure +- [AI context file maintenance](/sdk/getting-started/standards/repository-docs/#ai-context) — maintaining AI-readable documentation +- [Required reviewers](/sdk/getting-started/standards/review-ci/#code-review) — review approval requirements +- [Required CI checks baseline](/sdk/getting-started/standards/review-ci/#required-ci-checks) — minimum CI pipeline requirements +- [Commit message format](/sdk/getting-started/standards/code-submission/#commit-message-format) — conventional commit format +- [Linting and formatting in CI](/sdk/getting-started/standards/code-quality/#linting-and-type-checking) — automated code style checks +- [Type checking in CI](/sdk/getting-started/standards/code-quality/#linting-and-type-checking) — static type verification +- [Security practices](/sdk/getting-started/standards/code-quality/#security-practices) — secret scanning and security checks +- [Rollback procedures](/sdk/getting-started/standards/coordination-maintenance/#releases) — release rollback documentation --- 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 08074c1312b84..597cb938c0462 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 @@ -21,7 +21,7 @@ spec_changelog: This playbook guides SDK maintainers through setting up automated release infrastructure for a new SDK repository using [Craft](https://craft.sentry.dev). It covers initial tagging, CI configuration, version management, and branch protection rules. By following these steps, the repository will support automated changelog generation, artifact publishing, and controlled releases via GitHub Actions. Related resources: -- [Release Versioning Standard](/sdk/getting-started/standards/release-versioning) — version format and tooling requirements +- [Release Versioning Standard](/sdk/getting-started/standards/release-versioning/) — version format and tooling requirements - [Craft Documentation](https://craft.sentry.dev) — release automation tool - [Craft GitHub Actions](https://craft.sentry.dev/github-actions/) — workflow configuration options @@ -122,10 +122,10 @@ For the ongoing release process after setup, see "Cutting a release" (wip). ## Referenced Standards -- [Version format](/sdk/getting-started/standards/release-versioning#versioning) — SemVer requirements -- [Release tooling](/sdk/getting-started/standards/release-versioning#release-tooling) — Craft and publish setup -- [Release gating criteria](/sdk/getting-started/standards/review-ci#release-gating) — Pre-release validation requirements -- [Rollback procedures](/sdk/getting-started/standards/coordination-maintenance#releases) — Emergency release rollback process +- [Version format](/sdk/getting-started/standards/release-versioning/#versioning) — SemVer requirements +- [Release tooling](/sdk/getting-started/standards/release-versioning/#release-tooling) — Craft and publish setup +- [Release gating criteria](/sdk/getting-started/standards/review-ci/#release-gating) — Pre-release validation requirements +- [Rollback procedures](/sdk/getting-started/standards/coordination-maintenance/#releases) — Emergency release rollback process --- diff --git a/develop-docs/sdk/getting-started/standards/api-architecture.mdx b/develop-docs/sdk/getting-started/standards/api-architecture.mdx index 98d0106dc2986..382ef7f3aad0a 100644 --- a/develop-docs/sdk/getting-started/standards/api-architecture.mdx +++ b/develop-docs/sdk/getting-started/standards/api-architecture.mdx @@ -101,11 +101,11 @@ Deprecations of public APIs, integrations, and supported platforms follow three 2. **Keep it working** for at least one subsequent minor release (e.g., deprecated in X.Y, still functional in X.(Y+1)). 3. **Remove** only in the next major release (X+1.0). -Deprecating an entire SDK follows a separate, more involved process — see the [Deprecating an SDK](/sdk/getting-started/playbooks/sdk-lifecycle/deprecating-an-sdk) playbook. +Deprecating an entire SDK follows a separate, more involved process — see the [Deprecating an SDK](/sdk/getting-started/playbooks/sdk-lifecycle/deprecating-an-sdk/) playbook. ### Breaking changes -Breaking changes **MUST** follow the [breaking changes playbook](/sdk/getting-started/playbooks/sdk-lifecycle/breaking-changes). They can only ship in major versions; opt-in previews are allowed in minor versions. +Breaking changes **MUST** follow the [breaking changes playbook](/sdk/getting-started/playbooks/sdk-lifecycle/breaking-changes/). They can only ship in major versions; opt-in previews are allowed in minor versions. Every breaking change **MUST** include: diff --git a/develop-docs/sdk/getting-started/standards/code-quality.mdx b/develop-docs/sdk/getting-started/standards/code-quality.mdx index 15b9e64c1a2f5..c2bdb0a79b988 100644 --- a/develop-docs/sdk/getting-started/standards/code-quality.mdx +++ b/develop-docs/sdk/getting-started/standards/code-quality.mdx @@ -68,7 +68,7 @@ Adding a dependency is a decision that affects every user of the SDK, so it dese Transitive dependencies matter too. If a transitive dependency changes behavior, that deserves the same review as adding a direct dependency. Run dependency audits at least quarterly. -See [Adding a Dependency](/sdk/getting-started/playbooks/development/adding-a-dependency) for the step-by-step evaluation and approval workflow. +See [Adding a Dependency](/sdk/getting-started/playbooks/development/adding-a-dependency/) for the step-by-step evaluation and approval workflow. diff --git a/develop-docs/sdk/getting-started/standards/coordination-maintenance.mdx b/develop-docs/sdk/getting-started/standards/coordination-maintenance.mdx index 2eba9dc76f9db..3fa547e124151 100644 --- a/develop-docs/sdk/getting-started/standards/coordination-maintenance.mdx +++ b/develop-docs/sdk/getting-started/standards/coordination-maintenance.mdx @@ -30,7 +30,7 @@ When a change affects multiple SDKs, follow this sequence: 4. **Tracking** — set up as a Linear initiative 5. **Communication** — coordinate announcements -See [Aligning Cross-SDK Changes](/sdk/getting-started/playbooks/coordination/aligning-cross-sdk-changes) for the step-by-step playbook and [Managing Linear Projects](/sdk/getting-started/playbooks/coordination/managing-linear-projects) for running per-SDK projects. +See [Aligning Cross-SDK Changes](/sdk/getting-started/playbooks/coordination/aligning-cross-sdk-changes/) for the step-by-step playbook and [Managing Linear Projects](/sdk/getting-started/playbooks/coordination/managing-linear-projects/) for running per-SDK projects. @@ -49,7 +49,7 @@ Issues on GitHub and Linear are automatically labeled to track where action is n Labels are managed automatically and reset on state transitions. Both are removed when the issue is closed. -See the [Triaging playbook](/sdk/getting-started/playbooks/coordination/triaging) for the full workflow. +See the [Triaging playbook](/sdk/getting-started/playbooks/coordination/triaging/) for the full workflow. @@ -59,7 +59,7 @@ See the [Triaging playbook](/sdk/getting-started/playbooks/coordination/triaging ## Platform and language version support -Supported versions should be documented in the README and docs. Dropping support for a platform or language version is a breaking change — it follows the [breaking change and deprecation process](/sdk/getting-started/standards/api-architecture#breaking-and-deprecation) and needs evidence: usage data, upstream EOL status, or maintenance burden. Announce it at least one minor release before the major that drops support. +Supported versions should be documented in the README and docs. Dropping support for a platform or language version is a breaking change — it follows the [breaking change and deprecation process](/sdk/getting-started/standards/api-architecture/#breaking-and-deprecation) and needs evidence: usage data, upstream EOL status, or maintenance burden. Announce it at least one minor release before the major that drops support. Each SDK owns its version matrix. CI should test all supported versions. @@ -89,7 +89,7 @@ Every SDK **MUST** have a documented regression handling plan covering: - Who has permissions — at least two people per SDK must be able to publish and yank - A communication template for notifying users -An annual regression handling drill is recommended. See [Setting up release infrastructure](/sdk/getting-started/playbooks/setup/setting-up-release-infrastructure) for initial setup. +An annual regression handling drill is recommended. See [Setting up release infrastructure](/sdk/getting-started/playbooks/setup/setting-up-release-infrastructure/) for initial setup. diff --git a/develop-docs/sdk/getting-started/standards/planning-scoping.mdx b/develop-docs/sdk/getting-started/standards/planning-scoping.mdx index b49a4448740ae..1a280a4f042f3 100644 --- a/develop-docs/sdk/getting-started/standards/planning-scoping.mdx +++ b/develop-docs/sdk/getting-started/standards/planning-scoping.mdx @@ -59,7 +59,7 @@ Issues estimated larger than **M** (or the team's medium equivalent) **MUST NOT* - All acceptance criteria in the description are met - Code is reviewed and merged -- Tests cover the changed behavior (per the [Test Requirements](/sdk/getting-started/standards/code-quality#testing) standard) +- Tests cover the changed behavior (per the [Test Requirements](/sdk/getting-started/standards/code-quality/#testing) standard) - Any user-facing documentation impact is either shipped or tracked in a follow-up issue **Project level** — a project is done when: @@ -71,7 +71,7 @@ Issues estimated larger than **M** (or the team's medium equivalent) **MUST NOT* An issue or project **MUST NOT** be marked done if any of these conditions are unmet. "Mostly done" or "good enough" are not acceptable states — defer remaining work to a follow-up issue or project instead. -For a project description template including an artifact and communication checklist for the Definition of Done, see [Project Description Template](/sdk/getting-started/playbooks/coordination/managing-linear-projects#project-description-template). +For a project description template including an artifact and communication checklist for the Definition of Done, see [Project Description Template](/sdk/getting-started/playbooks/coordination/managing-linear-projects/#project-description-template). #### Enforcement diff --git a/develop-docs/sdk/getting-started/standards/release-versioning.mdx b/develop-docs/sdk/getting-started/standards/release-versioning.mdx index a9812e946008f..f2a3b0e910066 100644 --- a/develop-docs/sdk/getting-started/standards/release-versioning.mdx +++ b/develop-docs/sdk/getting-started/standards/release-versioning.mdx @@ -56,7 +56,7 @@ SDKs **MUST** use [craft](https://github.com/getsentry/craft) for release prepar - `scripts/bump-version.sh` — version bump script invoked by craft - `.github/workflows/release.yml` — GitHub Actions workflow to trigger releases -Craft targets and bump-version logic are SDK-specific, but the toolchain is the same everywhere. See the [setting up release infrastructure](/sdk/getting-started/playbooks/setup/setting-up-release-infrastructure) playbook for setup instructions. +Craft targets and bump-version logic are SDK-specific, but the toolchain is the same everywhere. See the [setting up release infrastructure](/sdk/getting-started/playbooks/setup/setting-up-release-infrastructure/) playbook for setup instructions. ### Merge target @@ -95,7 +95,7 @@ For the publish side, register the branch in the `publish.yml` workflow in `gets The registered branches **MUST** be protected — disable direct pushing and require PR approvals before merging. -Once a release is out, see [Post-release monitoring and regression handling](/sdk/getting-started/standards/coordination-maintenance#releases) for what to watch and how to respond. +Once a release is out, see [Post-release monitoring and regression handling](/sdk/getting-started/standards/coordination-maintenance/#releases) for what to watch and how to respond. diff --git a/develop-docs/sdk/getting-started/standards/repository-docs.mdx b/develop-docs/sdk/getting-started/standards/repository-docs.mdx index 0b4f6754122c9..154251f5144b5 100644 --- a/develop-docs/sdk/getting-started/standards/repository-docs.mdx +++ b/develop-docs/sdk/getting-started/standards/repository-docs.mdx @@ -33,7 +33,7 @@ Every SDK repo **MUST** have an `AGENTS.md` covering: - Testing conventions - Build instructions - Contribution expectations -- [Commit attribution convention](/sdk/getting-started/standards/code-submission#ai-attribution) +- [Commit attribution convention](/sdk/getting-started/standards/code-submission/#ai-attribution) - SDK-specific standard overrides — updated in the same PR as architectural changes ### CONTRIBUTING.md @@ -62,7 +62,7 @@ User-facing changes need corresponding docs: - **New feature**: docs PR to [sentry-docs](https://github.com/getsentry/sentry-docs/) - **Behavior change**: docs update -- **Deprecation**: migration guide (see [breaking changes and deprecations](/sdk/getting-started/standards/api-architecture#breaking-and-deprecation)) +- **Deprecation**: migration guide (see [breaking changes and deprecations](/sdk/getting-started/standards/api-architecture/#breaking-and-deprecation)) - **New config option**: docs entry The SDK PR should link to the docs PR. Neither merges without the other being at least approved. diff --git a/develop-docs/sdk/getting-started/standards/review-ci.mdx b/develop-docs/sdk/getting-started/standards/review-ci.mdx index 4c76ce2b7cb29..fc9af8eeff2af 100644 --- a/develop-docs/sdk/getting-started/standards/review-ci.mdx +++ b/develop-docs/sdk/getting-started/standards/review-ci.mdx @@ -29,9 +29,9 @@ These standards cover how code gets reviewed and what CI must check before anyth Every PR **REQUIRES** at least one approving review. Some changes need review from an [SDK Senior Engineer](https://github.com/orgs/getsentry/teams/sdk-seniors): -- [Public API changes](/sdk/getting-started/standards/api-architecture#public-api-changes) -- [New dependencies](/sdk/getting-started/standards/code-quality#dependencies) -- [Security-sensitive code](/sdk/getting-started/standards/code-quality#security) +- [Public API changes](/sdk/getting-started/standards/api-architecture/#public-api-changes) +- [New dependencies](/sdk/getting-started/standards/code-quality/#dependencies) +- [Security-sensitive code](/sdk/getting-started/standards/code-quality/#security) - Schema changes - Frameworks or architectural shifts @@ -101,7 +101,7 @@ A release **MUST NOT** ship if: - The changelog is empty for user-facing changes - Any known regression remains unresolved -See [Setting up release infrastructure](/sdk/getting-started/playbooks/setup/setting-up-release-infrastructure) for initial release setup. +See [Setting up release infrastructure](/sdk/getting-started/playbooks/setup/setting-up-release-infrastructure/) for initial release setup. diff --git a/develop-docs/sdk/platform-specifics/javascript-sdks/browser-tracing.mdx b/develop-docs/sdk/platform-specifics/javascript-sdks/browser-tracing.mdx index 44763322f7576..1606e5228e9a6 100644 --- a/develop-docs/sdk/platform-specifics/javascript-sdks/browser-tracing.mdx +++ b/develop-docs/sdk/platform-specifics/javascript-sdks/browser-tracing.mdx @@ -17,7 +17,7 @@ The tracing behavior in our browser SDKs is somewhat unique and significantly di Please note that any kind of automatic tracing instrumentation in the browser requires the `browserTracingIntegration()` to be added to the SDK configuration. -The default configuration of the SDK does not include any performance or tracing-related instrumentation to save on [bundle size](../bundle-size) for errors-only users. +The default configuration of the SDK does not include any performance or tracing-related instrumentation to save on [bundle size](../bundle-size/) for errors-only users. ## Pageload and Navigation Spans @@ -164,7 +164,7 @@ TwP means that the SDK attaches tracing headers to outgoing requests but does no This feature enables connecting frontend to backend errors in the UI without depleting users' span quota. While in other SDKs, TwP is activated by default when neither `tracesSampleRate` nor `tracesSampler` are set, in browser, users still have to add `browserTracingIntegration`. -The reason for this is that our fetch and XHR instrumentation is not included in the default SDK bundle to save on [bundle size](../bundle-size). +The reason for this is that our fetch and XHR instrumentation is not included in the default SDK bundle to save on [bundle size](../bundle-size/). So the only configuration to enable TwP is to register `browserTracingIntegration` but omit the sampling options completely (or set them to `undefined`). TwP mode uses the same [tracing model](#tracing-model) as SDKs configured for regular tracing. diff --git a/develop-docs/sdk/telemetry/logs.mdx b/develop-docs/sdk/telemetry/logs.mdx index a0868eac98cc9..206fbccb35b01 100644 --- a/develop-docs/sdk/telemetry/logs.mdx +++ b/develop-docs/sdk/telemetry/logs.mdx @@ -93,7 +93,7 @@ There are two wire protocols: the `log` envelope with the Sentry Log protocol (p Related specs: - [Envelopes](/sdk/foundations/envelopes/) — transport format -- [Attributes](/sdk/foundations/state-management/scopes/attributes) — attribute type system +- [Attributes](/sdk/foundations/state-management/scopes/attributes/) — attribute type system - [Tracing without Performance](/sdk/foundations/trace-propagation/#default-propagation) — required for trace context - [Trace Origin](/sdk/telemetry/traces/trace-origin/) — origin attribute format @@ -441,7 +441,7 @@ Each log in the `items` array is a JSON object: | `body` | String | **REQUIRED** | 1.0.0 | The log body/message. | | `span_id` | String | **OPTIONAL** | 1.11.0 | Span ID of the active span when the log was collected, as 8 random bytes encoded as a hex string (16 characters). | | `severity_number` | Integer | **OPTIONAL** | 1.0.0 | Severity number per [Severity Levels](#severity-levels). Inferred from `level` unless explicitly set. | -| `attributes` | Object | **OPTIONAL** | 1.0.0 | Key-value pairs of arbitrary data. Values **MUST** declare their type. See [Attributes](/sdk/foundations/state-management/scopes/attributes). | +| `attributes` | Object | **OPTIONAL** | 1.0.0 | Key-value pairs of arbitrary data. Values **MUST** declare their type. See [Attributes](/sdk/foundations/state-management/scopes/attributes/). | diff --git a/develop-docs/sdk/telemetry/metrics.mdx b/develop-docs/sdk/telemetry/metrics.mdx index 66a626032edf9..19668c02dd462 100644 --- a/develop-docs/sdk/telemetry/metrics.mdx +++ b/develop-docs/sdk/telemetry/metrics.mdx @@ -79,7 +79,7 @@ The envelope item type is named `trace_metric` for internal usage to avoid namin Related specs: - [Envelopes](/sdk/foundations/envelopes/) — transport format -- [Attributes](/sdk/foundations/state-management/scopes/attributes) — attribute types and structure +- [Attributes](/sdk/foundations/state-management/scopes/attributes/) — attribute types and structure - [Tracing without Performance](/sdk/foundations/trace-propagation/#default-propagation) — required before adding metrics support - [Telemetry Processor](/sdk/foundations/processing/telemetry-processor/) — buffer data forwarding scenarios diff --git a/develop-docs/sdk/telemetry/traces/otlp.mdx b/develop-docs/sdk/telemetry/traces/otlp.mdx index c455e300ea879..21d6461a52961 100644 --- a/develop-docs/sdk/telemetry/traces/otlp.mdx +++ b/develop-docs/sdk/telemetry/traces/otlp.mdx @@ -8,7 +8,7 @@ This document outlines how to build a dedicated `OTLPIntegration` in SDKs that m ### Existing OpenTelemetry Support -Some of our SDKs (Node, Java) already shipped a complete Performance powered by OpenTelemetry (POTEL) system following the [OpenTelemetry Support spec](../opentelemetry). +Some of our SDKs (Node, Java) already shipped a complete Performance powered by OpenTelemetry (POTEL) system following the [OpenTelemetry Support spec](../opentelemetry/). Some other SDKs (Python, Ruby, Elixir) implement a simpler system with **only** the `SpanProcessor` and `Propagator` components. diff --git a/develop-docs/self-hosted/index.mdx b/develop-docs/self-hosted/index.mdx index 3a353f9be6f54..44c9ec626a793 100644 --- a/develop-docs/self-hosted/index.mdx +++ b/develop-docs/self-hosted/index.mdx @@ -43,7 +43,7 @@ Self-hosted Sentry relies heavily on disk I/O because it runs databases, message Depending on your traffic volume, you may want to increase your system specification to handle increased load. Although most of the times, this is not the case for self-hosted Sentry, since no matter how small or big the traffic is, you will most likely hover around the same used resources. -If increasing the disk storage space isn't possible, you can migrate your storage to use external storage such as AWS S3 or Google Cloud Storage (GCS). Decreasing your `SENTRY_EVENT_RETENTION_DAYS` environment variable to lower numbers will save some storage space from being full, at the cost of having shorter data retention period. See [Event Retention](/self-hosted/configuration#event-retention) section. +If increasing the disk storage space isn't possible, you can migrate your storage to use external storage such as AWS S3 or Google Cloud Storage (GCS). Decreasing your `SENTRY_EVENT_RETENTION_DAYS` environment variable to lower numbers will save some storage space from being full, at the cost of having shorter data retention period. See [Event Retention](/self-hosted/configuration/#event-retention) section. Below is a breakdown of self-hosted Sentry installation compatibility with various Linux distributions: * **Debian/Ubuntu-based** distros are preferred; most users succeed with them, and they're used on Sentry's dogfood instance. From 7a99b70251c2564aea5733dd7955c6cd68c9b45c Mon Sep 17 00:00:00 2001 From: Alex Krawiec Date: Mon, 5 Oct 2026 11:41:33 -0700 Subject: [PATCH 2/2] ci: Ignore the private security-as-code repo in link checking The only failure on this PR's external-link check is two links to github.com/getsentry/security-as-code, which is private: lychee gets a 404 anonymously and can never authenticate into it. Both links are pre-existing on master and untouched by this PR, which changes only trailing slashes on internal links. They surfaced here because the checker scans changed files, and this PR touches the file that holds them. .lycheeignore already has a "Private GitHub repos" section listing getsentry, sentry-options-automator, etl and sdk-skills; this belongs alongside them. Verified: lychee reports 0 errors on that file afterwards. Co-Authored-By: Claude Opus 5 --- .lycheeignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.lycheeignore b/.lycheeignore index c28a794b561dc..b07c9f145f608 100644 --- a/.lycheeignore +++ b/.lycheeignore @@ -66,3 +66,4 @@ https?://empowerplant\.io.* # Private GitHub repos https?://github\.com/getsentry/sdk-skills.* +https?://github\.com/getsentry/security-as-code.*