From 8f62ff0bed78bf73ed60bec5fe27190a7f7d5515 Mon Sep 17 00:00:00 2001 From: Alex Krawiec Date: Mon, 5 Oct 2026 14:27:52 -0700 Subject: [PATCH 01/16] docs: Add trailing slashes to internal links in develop-docs (#19813) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## DESCRIBE YOUR PR The last bucket from the trailing-slash work in #19639 and #19675, which covered only the user docs. `develop-docs/` renders at **develop.sentry.dev** from the same Next config, so the same rule applies β€” 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 ``` **240 links across 39 files**, produced by `pnpm lint:trailing-slash:fix` from #19666. No hand edits. ### Verification - Every changed file differs from master **only by added `/` characters** β€” no slash removed, no external URL altered, no other content touched - 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 violations the linter still reports are drift in `docs/`, fixed separately in #19811. > Note: `AGENTS.md` describes `develop-docs/` as a submodule, but it isn't one β€” `git submodule status` is empty and the directory has direct commits in this repo. Worth correcting in that file at some point, though I've left it out of this PR. ## IS YOUR CHANGE URGENT? Help us prioritize incoming PRs by letting us know when the change needs to go live. Select exactly one option. For deadlines, replace `YYYY-MM-DD` with the due date. You can update this information later by editing the PR description. - [ ] Urgent deadline (GA date, etc.): YYYY-MM-DD - [ ] Other deadline: YYYY-MM-DD - [x] No deadline: Not urgent, can wait up to 1 week+ ## SLA - Teamwork makes the dream work, so please add a reviewer to your PRs. - Please give the docs team up to 1 week to review your PR unless you've supplied a deadline. Thanks in advance for your help! ## PRE-MERGE CHECKLIST _Make sure you've checked the following before merging your changes:_ - [ ] Checked Vercel preview for correctness, including links - [ ] PR was reviewed and approved by any necessary SMEs (subject matter experts) - [ ] PR was reviewed and approved by a member of the [Sentry docs team](https://github.com/orgs/getsentry/teams/docs) πŸ€– Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5 --- .lycheeignore | 1 + 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 +- 40 files changed, 241 insertions(+), 240 deletions(-) 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.* 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 b660035f4f6da77b5cf0b6b870855b9fb17ba296 Mon Sep 17 00:00:00 2001 From: Dan Fuller Date: Mon, 5 Oct 2026 14:31:02 -0700 Subject: [PATCH 02/16] docs(crons): Document 7 day max_runtime limit (#19815) Part of a series limiting crons `max_runtime` to 7 days (10080 minutes), down from 28 days, so in-progress check-ins stop changing after a bounded time. Document the new limit where `max_runtime` is defined, and note in the SDK developer docs that monitor upserts clamp larger values. --- develop-docs/sdk/telemetry/check-ins.mdx | 2 +- docs/platforms/javascript/common/crons/index.mdx | 2 +- .../monitors/crons/getting-started/http/index.mdx | 2 +- includes/javascript-crons-upsert.mdx | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/develop-docs/sdk/telemetry/check-ins.mdx b/develop-docs/sdk/telemetry/check-ins.mdx index cf98d33099a72..dbffb6f8a6aa7 100644 --- a/develop-docs/sdk/telemetry/check-ins.mdx +++ b/develop-docs/sdk/telemetry/check-ins.mdx @@ -221,7 +221,7 @@ When included, the `monitor_config` object supports the following fields: |-------|------|----------|-------|-------------| | `schedule` | Object | **REQUIRED** | 1.1.0 | Schedule configuration. See [Schedule Configuration](#schedule-configuration). | | `checkin_margin` | Number | **OPTIONAL** | 1.1.0 | Allowed margin in minutes after the expected check-in time before the monitor is considered missed. | -| `max_runtime` | Number | **OPTIONAL** | 1.1.0 | Allowed duration in minutes that a monitor may be `in_progress` before being considered failed due to timeout. | +| `max_runtime` | Number | **OPTIONAL** | 1.1.0 | Allowed duration in minutes that a monitor may be `in_progress` before being considered failed due to timeout. The maximum is 10080 (7 days); Sentry clamps larger values sent in a monitor upsert. A check-in can stay in progress for at most 7 days, including repeated `in_progress` check-ins. | | `failure_issue_threshold` | Number | **OPTIONAL** | 1.4.0 | Number of consecutive failed check-ins before an issue is created. | | `recovery_threshold` | Number | **OPTIONAL** | 1.4.0 | Number of consecutive OK check-ins before an issue is resolved. | | `timezone` | String | **OPTIONAL** | 1.1.0 | A [tz database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) string for the monitor's execution schedule timezone. | diff --git a/docs/platforms/javascript/common/crons/index.mdx b/docs/platforms/javascript/common/crons/index.mdx index 2c6cb8a288335..d66ae19055ebd 100644 --- a/docs/platforms/javascript/common/crons/index.mdx +++ b/docs/platforms/javascript/common/crons/index.mdx @@ -162,7 +162,7 @@ We recommend that your check-in margin be less than or equal to your interval. `max_runtime`: -The amount of time (in minutes) your job is allowed to run before it's considered failed. Optional. +The amount of time (in minutes) your job is allowed to run before it's considered failed. The maximum is 10080 minutes (7 days). Optional. `failure_issue_threshold`: diff --git a/docs/product/monitors-and-alerts/monitors/crons/getting-started/http/index.mdx b/docs/product/monitors-and-alerts/monitors/crons/getting-started/http/index.mdx index f87c0608e0e55..894ef770d000a 100644 --- a/docs/product/monitors-and-alerts/monitors/crons/getting-started/http/index.mdx +++ b/docs/product/monitors-and-alerts/monitors/crons/getting-started/http/index.mdx @@ -148,7 +148,7 @@ We recommend that your check-in margin be less than or equal to your interval. `max_runtime`: -The amount of time (in minutes) your job is allowed to run before it's considered failed. Optional. +The amount of time (in minutes) your job is allowed to run before it's considered failed. The maximum is 10080 minutes (7 days). A check-in can stay in progress for at most 7 days, including repeated in-progress check-ins. Optional. `failure_issue_threshold`: diff --git a/includes/javascript-crons-upsert.mdx b/includes/javascript-crons-upsert.mdx index 4ea6d173c1bc1..81cc9d5c1cb42 100644 --- a/includes/javascript-crons-upsert.mdx +++ b/includes/javascript-crons-upsert.mdx @@ -85,7 +85,7 @@ We recommend that your check-in margin be less than or equal to your interval. `maxRuntime`: -The amount of time (in minutes) your job is allowed to run before it's considered failed. Optional. +The amount of time (in minutes) your job is allowed to run before it's considered failed. The maximum is 10080 minutes (7 days). Optional. `timezone`: From 3c774b82650a4f71485b478d6ffdd2540fb7ee6e Mon Sep 17 00:00:00 2001 From: "sentry-api-schema-updater[bot]" <271575301+sentry-api-schema-updater[bot]@users.noreply.github.com> Date: Mon, 5 Oct 2026 23:15:58 +0000 Subject: [PATCH 03/16] Bump API schema to 658c82e5 (#19816) Co-authored-by: sentry-api-schema-updater[bot] <271575301+sentry-api-schema-updater[bot]@users.noreply.github.com> --- src/build/resolveOpenAPI.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/build/resolveOpenAPI.ts b/src/build/resolveOpenAPI.ts index 0c329a242c0fb..0837b52a75468 100644 --- a/src/build/resolveOpenAPI.ts +++ b/src/build/resolveOpenAPI.ts @@ -6,7 +6,7 @@ import {DeRefedOpenAPI} from './open-api/types'; // SENTRY_API_SCHEMA_SHA is used in the sentry-docs GHA workflow in getsentry/sentry-api-schema. // DO NOT change variable name unless you change it in the sentry-docs GHA workflow in getsentry/sentry-api-schema. -const SENTRY_API_SCHEMA_SHA = '0a3f51ed3397530cdbb2de8d03f15625d0748bde'; +const SENTRY_API_SCHEMA_SHA = '658c82e501665b9a1977a0136ece4040d73efcd9'; const activeEnv = process.env.GATSBY_ENV || process.env.NODE_ENV || 'development'; From 81fcc60f9900786ac790d31cdcb4e928c6320ff6 Mon Sep 17 00:00:00 2001 From: "sentry-junior[bot]" <264270552+sentry-junior[bot]@users.noreply.github.com> Date: Tue, 6 Oct 2026 07:51:47 +0000 Subject: [PATCH 04/16] fix(python): Correct functions_to_trace option type (#19819) ## DESCRIBE YOUR PR The Python options page lists `functions_to_trace` as `list[str]` and says each entry is a string with the function's fully qualified name. The SDK actually expects `Sequence[Dict[str, str]]` and reads `function["qualified_name"]` from each entry ([`client.py` @ 2.71.0](https://github.com/getsentry/sentry-python/blob/2.71.0/sentry_sdk/client.py#L545-L547), [`consts.py`](https://github.com/getsentry/sentry-python/blob/2.71.0/sentry_sdk/consts.py#L1356)). If you pass plain strings, `sentry_sdk.init()` fails with `TypeError: string indices must be integers`. This changes the type to `list[dict[str, str]]` and describes the `qualified_name` key. That matches the example already on the [custom instrumentation page](https://docs.sentry.io/platforms/python/tracing/instrumentation/custom-instrumentation/#define-span-creation-in-a-central-place). ## IS YOUR CHANGE URGENT? - [ ] Urgent deadline (GA date, etc.): YYYY-MM-DD - [ ] Other deadline: YYYY-MM-DD - [x] No deadline: Not urgent, can wait up to 1 week+ ## PRE-MERGE CHECKLIST - [ ] Checked Vercel preview for correctness, including links - [ ] PR was reviewed and approved by any necessary SMEs (subject matter experts) - [ ] PR was reviewed and approved by a member of the [Sentry docs team](https://github.com/orgs/getsentry/teams/docs) via **Ivana Kellyer**. -- [View Junior Session](https://junior-prod.sentry.dev/conversations/agent-dispatch%3Adispatch_629c1689a0364da29b4e432b70cfeadb) [[Sentry]](https://sentry.sentry.io/explore/conversations/agent-dispatch%3Adispatch_629c1689a0364da29b4e432b70cfeadb/?project=4510944073809921) Co-authored-by: sentry-junior[bot] <264270552+sentry-junior[bot]@users.noreply.github.com> Co-authored-by: Ivana Kellyer --- docs/platforms/python/configuration/options.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/platforms/python/configuration/options.mdx b/docs/platforms/python/configuration/options.mdx index 3f9be263e3f11..786f17fc595d2 100644 --- a/docs/platforms/python/configuration/options.mdx +++ b/docs/platforms/python/configuration/options.mdx @@ -534,10 +534,10 @@ The organization ID is used for features like + An optional list of functions that should be set up for tracing. For each function in the list, a span will be created when the function is executed. -Functions in the list are represented as strings containing the fully qualified name of the function. +Each entry is a dictionary with a `qualified_name` key that holds the fully qualified name of the function, for example `{"qualified_name": "myapp.utils.my_function"}`. This is a convenient option, making it possible to have one central place for configuring what functions to trace, instead of having custom instrumentation scattered all over your code base. From 5e28dadceb050730c1b0dfa93f81b5eaf0962cd8 Mon Sep 17 00:00:00 2001 From: "sentry-junior[bot]" <264270552+sentry-junior[bot]@users.noreply.github.com> Date: Tue, 6 Oct 2026 10:01:56 +0200 Subject: [PATCH 05/16] fix(dotnet): Document EnableMetrics as obsolete and ignored (#19818) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## DESCRIBE YOUR PR The .NET metrics options say that setting `EnableMetrics` to `false` disables the `SentrySdk.Metrics` APIs. That stopped being true in 6.10.0 ([getsentry/sentry-dotnet#5509](https://github.com/getsentry/sentry-dotnet/pull/5509)). The option is now `[Obsolete]`, its getter always returns `true`, and its setter does nothing ([`SentryOptions.cs` L640–657 @ 6.12.0](https://github.com/getsentry/sentry-dotnet/blob/6.12.0/src/Sentry/SentryOptions.cs#L640-L657)). Users who follow the current docs to opt out still send every metric. This updates the description to say the option is ignored and points to `SetBeforeSendMetric` (returning `null`) as the way to drop metrics. That matches the SDK's own obsolete message. ## IS YOUR CHANGE URGENT? - [ ] Urgent deadline (GA date, etc.): YYYY-MM-DD - [ ] Other deadline: YYYY-MM-DD - [x] No deadline: Not urgent, can wait up to 1 week+ ## PRE-MERGE CHECKLIST - [ ] Checked Vercel preview for correctness, including links - [ ] PR was reviewed and approved by any necessary SMEs (subject matter experts) - [ ] PR was reviewed and approved by a member of the [Sentry docs team](https://github.com/orgs/getsentry/teams/docs) via **Ivana Kellyer**. -- [View Junior Session](https://junior-prod.sentry.dev/conversations/agent-dispatch%3Adispatch_629c1689a0364da29b4e432b70cfeadb) [[Sentry]](https://sentry.sentry.io/explore/conversations/agent-dispatch%3Adispatch_629c1689a0364da29b4e432b70cfeadb/?project=4510944073809921) Co-authored-by: sentry-junior[bot] <264270552+sentry-junior[bot]@users.noreply.github.com> Co-authored-by: Ivana Kellyer --- platform-includes/metrics/options/dotnet.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/platform-includes/metrics/options/dotnet.mdx b/platform-includes/metrics/options/dotnet.mdx index 258913932ff78..66cf538065ca1 100644 --- a/platform-includes/metrics/options/dotnet.mdx +++ b/platform-includes/metrics/options/dotnet.mdx @@ -1,6 +1,6 @@ #### EnableMetrics -Set to `false` in order to disable the `SentrySdk.Metrics` APIs. +This option is obsolete and ignored since version 6.10.0, and will be removed in version 7.0.0. Metrics sent through the `SentrySdk.Metrics` APIs are always sent, even if you set `EnableMetrics` to `false`. To drop metrics, use `SetBeforeSendMetric` and return `null`. #### SetBeforeSendMetric From 0c43324f627367e78a566a254b54b29be33fc7ab Mon Sep 17 00:00:00 2001 From: Charly Gomez Date: Tue, 6 Oct 2026 10:04:12 +0200 Subject: [PATCH 06/16] docs(js): Document tracking Statsig experiments with tags and attributes (#19770) The Statsig integration only records boolean gate evaluations, so [experiment group assignments ](https://docs.statsig.com/experiments/overview)never reach Sentry. Adding it to the integration would mean either encoding experiments as fake boolean flags or waiting until the product renders non-boolean flag values. Until then, this documents a small listener that records the assigned group as a tag (for errors) and an attribute (for spans, logs, and metrics). Refs getsentry/sentry-javascript#22170 Co-authored-by: Claude Opus 5.5 --- .../configuration/integrations/statsig.mdx | 23 +++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/docs/platforms/javascript/common/configuration/integrations/statsig.mdx b/docs/platforms/javascript/common/configuration/integrations/statsig.mdx index d76d2b8d65b8d..fc41addcd7866 100644 --- a/docs/platforms/javascript/common/configuration/integrations/statsig.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/statsig.mdx @@ -23,4 +23,27 @@ _Import name: `Sentry.statsigIntegration`_ +## Tracking Experiments + +The integration doesn't track [Statsig experiments](https://docs.statsig.com/experiments-plus/), because their assigned groups aren't boolean values. To see which experiment group a user was in when an error happened, listen to Statsig's `experiment_evaluation` event and record the group as a tag and an attribute: + +```javascript +statsigClient.on("experiment_evaluation", ({ experiment }) => { + // `groupName` is null when the user isn't part of the experiment + if (!experiment.groupName) { + return; + } + + const key = `statsig.experiment.${experiment.name}`; + // Tags are added to error events + Sentry.setTag(key, experiment.groupName); + // Attributes are added to spans, logs, and metrics + Sentry.setAttribute(key, experiment.groupName); +}); +``` + +Register the listener before calling `initializeAsync()` so evaluations made during startup are captured. You can then search for errors from a group, for example `statsig.experiment.my_experiment:Control`, and filter spans, logs, and metrics by the same attribute. + +Experiment names have to be valid [tag keys](/platforms/javascript/enriching-events/tags/). `Sentry.setAttribute` requires SDK version 10.61.0 or higher, see [Attributes](/platforms/javascript/enriching-events/attributes/). These values don't show up in the feature flag section of an issue. + From 63c786ea40e475735ef949d9ec1fd2a4d32d771c Mon Sep 17 00:00:00 2001 From: "sentry-junior[bot]" <264270552+sentry-junior[bot]@users.noreply.github.com> Date: Tue, 6 Oct 2026 10:56:22 +0200 Subject: [PATCH 07/16] fix(dotnet): Clarify that EnableLogs doesn't gate SentrySdk.Logger (#19820) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## DESCRIBE YOUR PR The .NET logs docs say `EnableLogs = true` is required to use the `SentrySdk.Logger` APIs. That stopped being true in 6.10.0 ([getsentry/sentry-dotnet#5512](https://github.com/getsentry/sentry-dotnet/pull/5512)). The option now only controls logs captured by the logging integrations (`Microsoft.Extensions.Logging`, Serilog, NLog, log4net). Logs created directly through `SentrySdk.Logger` "are always sent" ([`SentryOptions.cs` L610–620 @ 6.12.0](https://github.com/getsentry/sentry-dotnet/blob/6.12.0/src/Sentry/SentryOptions.cs#L610-L620)). This removes the claim everywhere it appears in the .NET logs docs: - **Options:** the plain .NET `EnableLogs` description now says it controls integration-captured logs, not `SentrySdk.Logger`. - **Options:** the `Microsoft.Extensions.Logging` filter note no longer says `EnableLogs = true` "keeps the `SentrySdk.Logger` APIs available." - **Setup:** the intro explains that `SentrySdk.Logger` needs no extra configuration, and integrations need `EnableLogs = true`. - **Setup (plain .NET):** the `SentrySdk.Init` snippet no longer sets `EnableLogs`, and the note says you only need it with a logging integration. - **Setup (ASP.NET Core, AWS Lambda, Azure Functions, Blazor, MAUI):** the note no longer says `EnableLogs` enables `SentrySdk.Logger`; it enables the `Microsoft.Extensions.Logging` integration. - **Usage:** the intro no longer says the feature must be enabled before using `SentrySdk.Logger`. Integration-based setup snippets still set `EnableLogs = true`, since every integration path still requires it. ## IS YOUR CHANGE URGENT? - [ ] Urgent deadline (GA date, etc.): YYYY-MM-DD - [ ] Other deadline: YYYY-MM-DD - [x] No deadline: Not urgent, can wait up to 1 week+ ## PRE-MERGE CHECKLIST - [ ] Checked Vercel preview for correctness, including links - [ ] PR was reviewed and approved by any necessary SMEs (subject matter experts) - [ ] PR was reviewed and approved by a member of the [Sentry docs team](https://github.com/orgs/getsentry/teams/docs) via Junior system actor `event`. -- [View Junior Session](https://junior-prod.sentry.dev/conversations/agent-dispatch%3Adispatch_629c1689a0364da29b4e432b70cfeadb) [[Sentry]](https://sentry.sentry.io/explore/conversations/agent-dispatch%3Adispatch_629c1689a0364da29b4e432b70cfeadb/?project=4510944073809921) --------- Co-authored-by: sentry-junior[bot] <264270552+sentry-junior[bot]@users.noreply.github.com> Co-authored-by: Ricardo Oliveira --- platform-includes/logs/options/dotnet.mdx | 6 ++++-- platform-includes/logs/setup/dotnet.mdx | 9 +++------ platform-includes/logs/usage/dotnet.mdx | 2 +- 3 files changed, 8 insertions(+), 9 deletions(-) diff --git a/platform-includes/logs/options/dotnet.mdx b/platform-includes/logs/options/dotnet.mdx index 109b4499fbb3b..ed7e850819e0d 100644 --- a/platform-includes/logs/options/dotnet.mdx +++ b/platform-includes/logs/options/dotnet.mdx @@ -1,7 +1,9 @@ #### EnableLogs -Set to `true` in order to enable the `SentrySdk.Logger` APIs. +Set to `true` to send logs captured by logging integrations, such as `Microsoft.Extensions.Logging`, Serilog, NLog, and log4net. Defaults to `false`. + +Since version 6.10.0, this option doesn't apply to logs sent through the `SentrySdk.Logger` APIs. Those logs are always sent. @@ -47,7 +49,7 @@ Use standard `Microsoft.Extensions.Logging` filtering to reduce noisy categories } ``` -Setting `Logging:Sentry:LogLevel:Default` to `None` disables logs sent through the `Microsoft.Extensions.Logging` provider for all categories, while `EnableLogs = true` keeps the `SentrySdk.Logger` APIs available. +Setting `Logging:Sentry:LogLevel:Default` to `None` disables logs sent through the `Microsoft.Extensions.Logging` provider for all categories. Logs sent through the `SentrySdk.Logger` APIs aren't affected by these filters and are still sent. Example with `EnableLogs = true` and `Logging:Sentry:LogLevel:Default = None`: diff --git a/platform-includes/logs/setup/dotnet.mdx b/platform-includes/logs/setup/dotnet.mdx index 4757af348c62e..8cbc3217063c1 100644 --- a/platform-includes/logs/setup/dotnet.mdx +++ b/platform-includes/logs/setup/dotnet.mdx @@ -1,4 +1,4 @@ -To enable logging, you need to initialize the SDK with the `EnableLogs` option set to `true`. +Logs sent through the `SentrySdk.Logger` APIs are always sent, so they don't need any extra configuration. To send logs captured by logging integrations, initialize the SDK with the `EnableLogs` option set to `true`. @@ -6,13 +6,10 @@ To enable logging, you need to initialize the SDK with the `EnableLogs` option s SentrySdk.Init(options => { options.Dsn = "___PUBLIC_DSN___"; - // Enable logs to be sent to Sentry - options.EnableLogs = true; }); ``` - -This enables the `SentrySdk.Logger` APIs. +You don't need a logs-specific option to use the `SentrySdk.Logger` APIs. Set `EnableLogs = true` only if you also send logs through a logging integration. @@ -28,7 +25,7 @@ This enables the `SentrySdk.Logger` APIs. ``` -This enables the `SentrySdk.Logger` APIs, as well as the `Microsoft.Extensions.Logging` integration. +This enables the `Microsoft.Extensions.Logging` integration. The `SentrySdk.Logger` APIs don't depend on `EnableLogs`. diff --git a/platform-includes/logs/usage/dotnet.mdx b/platform-includes/logs/usage/dotnet.mdx index 9136ca9004002..794c46b4a8ee3 100644 --- a/platform-includes/logs/usage/dotnet.mdx +++ b/platform-includes/logs/usage/dotnet.mdx @@ -1,6 +1,6 @@ -Once the feature is enabled on the SDK and the SDK is initialized, you can send logs using the `SentrySdk.Logger` APIs. +Once the SDK is initialized, you can send logs using the `SentrySdk.Logger` APIs. The `SentryStructuredLogger` type exposes six method groups that you can use to log messages at different log levels: `Trace`, `Debug`, `Info`, `Warning`, `Error`, and `Fatal`. From e447fd1d8b9e0f3f23538e3fae1578238af85c39 Mon Sep 17 00:00:00 2001 From: Ivan Tustanivskyi Date: Tue, 6 Oct 2026 12:27:44 +0300 Subject: [PATCH 08/16] docs(unreal): Document trace header propagation with baggage (#19806) The Unreal SDK now propagates the `baggage` header together with `sentry-trace`. Transactions and spans have a new `GetTraceHeaders()` method for outgoing requests, and `ContinueTrace()` uses the incoming `baggage` headers. Updates the Unreal trace propagation page to match: - Restructures it like the Unity and Android pages: extract incoming tracing information, inject it into outgoing requests, and verify. - Shows how to read `sentry-trace` and `baggage` from an HTTP response and pass them to `ContinueTrace()`, including the `nullptr` check and when it applies. - Replaces `GetTrace()` with `GetTraceHeaders()` for outgoing requests. - Notes the macOS and iOS limitation: only the sample rate and sample rand are carried over from the incoming `baggage`. ## Related Items - getsentry/sentry-unreal#1612 - getsentry/sentry-cocoa#8277 --- .../custom-instrumentation/unreal.mdx | 67 ++++++++++++++++--- 1 file changed, 57 insertions(+), 10 deletions(-) diff --git a/platform-includes/distributed-tracing/custom-instrumentation/unreal.mdx b/platform-includes/distributed-tracing/custom-instrumentation/unreal.mdx index 6c98d56c1d643..b67da3c21c5da 100644 --- a/platform-includes/distributed-tracing/custom-instrumentation/unreal.mdx +++ b/platform-includes/distributed-tracing/custom-instrumentation/unreal.mdx @@ -1,19 +1,66 @@ On this page you will learn how to manually propagate trace information into and out of your Unreal Engine game. -Continuing a trace from an upstream service requires using `ContinueTrace()`, which will create a transaction context with the provided `sentry-trace` header. This transaction starts with the transaction context will contain everything needed to continue the trace. +To set it up, make sure your game extracts incoming tracing information and attaches it again when making an outgoing request. + +## Step 1) Extract Incoming Tracing Information + +To continue a trace from another service, for example a backend that uses another Sentry SDK, pass its `sentry-trace` and `baggage` headers to `ContinueTrace()`. It returns a transaction context that continues the upstream trace, including its sampling decision: ```cpp -// Get incoming tracing information -const FString inTrace = ... -TArray inBaggage = ... +void OnResponse(FHttpRequestPtr Request, FHttpResponsePtr Response, bool bSucceeded) +{ + USentrySubsystem* SentrySubsystem = GEngine->GetEngineSubsystem(); + + const FString SentryTrace = Response->GetHeader(TEXT("sentry-trace")); + + TArray BaggageHeaders; + const FString Baggage = Response->GetHeader(TEXT("baggage")); + if (!Baggage.IsEmpty()) + { + BaggageHeaders.Add(Baggage); + } + + if (USentryTransactionContext* TransactionContext = SentrySubsystem->ContinueTrace(SentryTrace, BaggageHeaders)) + { + USentryTransaction* Transaction = SentrySubsystem->StartTransactionWithContext(TransactionContext); -USentryTransactionContext* transactionContext = - SentrySubsystem->ContinueTrace(inTrace, inBaggage); + // Process the response here... -USentryTransaction* transaction = - SentrySubsystem->StartTransactionWithContext(transactionContext); + Transaction->Finish(); + } +} ``` -To obtain trace header from a transaction or span, use `GetTrace()`. Pass the returned value to the downstream service. If communication happens over HTTP, we recommend you attach this header to the outgoing HTTP request. +The `sentry-trace` header must follow the format defined in [the telemetry docs](https://develop.sentry.dev/sdk/telemetry/traces/#header-sentry-trace): a 32-character hexadecimal `traceId`, followed by a 16-character hexadecimal `spanId`, and an optional `sampled` flag. + +Always check the result of `ContinueTrace()`. It returns `nullptr` if the SDK isn't initialized. On Android, it also returns `nullptr` if tracing is disabled, and on macOS and iOS, if the `sentry-trace` header is malformed. + + + +On macOS and iOS, only the sample rate and sample rand are taken from the incoming `baggage`, and only when the `sentry-trace` header includes a sampling decision (`-1` or `-0`). Other values, such as release and environment, aren't carried over yet. + + + +## Step 2) Inject Tracing Information to Outgoing Requests + +For distributed tracing to work, the two headers `sentry-trace` and `baggage` must also be added to outgoing requests. Get them from the current transaction or span with `GetTraceHeaders()`: + +```cpp +TSharedRef HttpRequest = FHttpModule::Get().CreateRequest(); +HttpRequest->SetURL(TEXT("https://example.com/api/action")); + +for (const TPair& Header : Transaction->GetTraceHeaders()) +{ + HttpRequest->SetHeader(Header.Key, Header.Value); +} + +HttpRequest->ProcessRequest(); +``` + +`GetTrace()` is still available, but it only returns the `sentry-trace` header. + +The two services are now connected with your custom distributed tracing implementation. + +## Verification -The format of the `sentry-trace` header should follow the one defined in [the telemetry docs](https://develop.sentry.dev/sdk/telemetry/traces/#header-sentry-trace). It should consist of a 32 character hexadecimal string for the `traceId`, followed by a 16 character hexadecimal string for the `spanId` and an optional single character for the `sampled` flag. If the given string doesn't match this format, the update is ignored and the values in the transaction context will remain unchanged. +If you make outgoing requests from your game to other services, check if the headers `sentry-trace` and `baggage` are present in the request. If so, distributed tracing is working. From 66592d98a281a7f39770cd0d5139b74233a9d4c6 Mon Sep 17 00:00:00 2001 From: "sentry-api-schema-updater[bot]" <271575301+sentry-api-schema-updater[bot]@users.noreply.github.com> Date: Tue, 6 Oct 2026 10:24:23 +0000 Subject: [PATCH 09/16] Bump API schema to 039965a8 (#19823) Co-authored-by: sentry-api-schema-updater[bot] <271575301+sentry-api-schema-updater[bot]@users.noreply.github.com> --- src/build/resolveOpenAPI.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/build/resolveOpenAPI.ts b/src/build/resolveOpenAPI.ts index 0837b52a75468..90edb11674a7d 100644 --- a/src/build/resolveOpenAPI.ts +++ b/src/build/resolveOpenAPI.ts @@ -6,7 +6,7 @@ import {DeRefedOpenAPI} from './open-api/types'; // SENTRY_API_SCHEMA_SHA is used in the sentry-docs GHA workflow in getsentry/sentry-api-schema. // DO NOT change variable name unless you change it in the sentry-docs GHA workflow in getsentry/sentry-api-schema. -const SENTRY_API_SCHEMA_SHA = '658c82e501665b9a1977a0136ece4040d73efcd9'; +const SENTRY_API_SCHEMA_SHA = '039965a844f9bbd7f90bca18fbd4f1e7ca8c64ea'; const activeEnv = process.env.GATSBY_ENV || process.env.NODE_ENV || 'development'; From 287b9604115a60ba862ee4180b039e2905b74b3d Mon Sep 17 00:00:00 2001 From: Itay Brenner Date: Tue, 6 Oct 2026 15:07:02 +0200 Subject: [PATCH 10/16] docs(apple): Update stable release cadence to weekly (#19821) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## DESCRIBE YOUR PR The Cocoa SDK now targets stable releases roughly every week instead of every month. This updates the "How often do we mark SDKs as stable?" answer on the Apple releases page to match. ## IS YOUR CHANGE URGENT? Help us prioritize incoming PRs by letting us know when the change needs to go live. Select exactly one option. For deadlines, replace `YYYY-MM-DD` with the due date. You can update this information later by editing the PR description. - [ ] Urgent deadline (GA date, etc.): YYYY-MM-DD - [ ] Other deadline: YYYY-MM-DD - [x] No deadline: Not urgent, can wait up to 1 week+ ## SLA - Teamwork makes the dream work, so please add a reviewer to your PRs. - Please give the docs team up to 1 week to review your PR unless you've supplied a deadline. Thanks in advance for your help! ## PRE-MERGE CHECKLIST _Make sure you've checked the following before merging your changes:_ - [ ] Checked Vercel preview for correctness, including links - [ ] PR was reviewed and approved by any necessary SMEs (subject matter experts) - [ ] PR was reviewed and approved by a member of the [Sentry docs team](https://github.com/orgs/getsentry/teams/docs) πŸ€– Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Fable 5.1 --- docs/platforms/apple/common/releases/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/apple/common/releases/index.mdx b/docs/platforms/apple/common/releases/index.mdx index 39f9da593d36e..6dd498c97dea3 100644 --- a/docs/platforms/apple/common/releases/index.mdx +++ b/docs/platforms/apple/common/releases/index.mdx @@ -31,7 +31,7 @@ No. Stability and performance are the top priorities for every release. The `Sta ### How often do we mark SDKs as stable? -The stable release cycle depends on a number of factors and can vary, but the target cadence is to provide stable releases roughly every month. +The stable release cycle depends on a number of factors and can vary, but the target cadence is to provide stable releases roughly every week. ### Should I only use stable releases? From 78630abf68fbbda8cc8053e508c873ea2678f1e1 Mon Sep 17 00:00:00 2001 From: Sigrid <32902192+s1gr1d@users.noreply.github.com> Date: Tue, 6 Oct 2026 15:27:51 +0200 Subject: [PATCH 11/16] docs(data-collection): Update cookie filtering examples (#19700) Update the examples based on the changes in those PRs: - https://github.com/getsentry/sentry-javascript/pull/24231 - https://github.com/getsentry/sentry-javascript/pull/24090 Based on Sentry Conventions, we don't collect cookies within their own keyed attribtue anymore. --- .../client/data-collection/index.mdx | 24 ++++++++++++++----- 1 file changed, 18 insertions(+), 6 deletions(-) diff --git a/develop-docs/sdk/foundations/client/data-collection/index.mdx b/develop-docs/sdk/foundations/client/data-collection/index.mdx index 21e123683fc14..7b203fc8c13d8 100644 --- a/develop-docs/sdk/foundations/client/data-collection/index.mdx +++ b/develop-docs/sdk/foundations/client/data-collection/index.mdx @@ -2,12 +2,15 @@ title: Data Collection description: Configuration for what data SDKs collect by default, including technical context, PII, and sensitive data. spec_id: sdk/foundations/client/data-collection -spec_version: 0.14.0 +spec_version: 0.15.0 spec_status: candidate spec_depends_on: - id: sdk/foundations/client version: ">=1.0.0" spec_changelog: + - version: 0.15.0 + date: 2026-09-29 + summary: "Attach cookie headers as one string-array span attribute (`name=value` elements) instead of one attribute per cookie name. Filter nameless cookie segments and unparseable cookie strings." - version: 0.14.0 date: 2026-09-28 summary: "Add `mcp`, defaulting to `{ inputs: true, outputs: true }`, to control collection of MCP request and response content independently of `genAI`." @@ -241,21 +244,30 @@ Cookies and URL query params may arrive as a single unparsed string (e.g., `Cook For cookies: the rules and terms as specified in `cookies` in the `dataCollection` configuration apply to cookie names. The SDK replaces values for sensitive keys with `"[Filtered]"` while keeping non-sensitive values as-is. This selective filtering retains harmless contextual information for debugging while protecting sensitive fields. -For example, a `Cookie` header parsed into individual cookies: +When SDKs parse a cookie header, the following rules apply: + +- Split the `Cookie` header on `";"`. The space after the semicolon is not guaranteed. Splitting on `"; "` could leak the previous cookie's value. +- A segment without `"="` is a nameless cookie: the bare token is its **value**, not its name ([RFC 6265bis](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-rfc6265bis)). The SDK **MUST** replace the element with `"[Filtered]"`. +- `Set-Cookie` attributes such as `Max-Age`, `Path`, or `HttpOnly` are metadata, not cookies, and **MUST NOT** appear as cookie pairs. + +For example, `Cookie: user_session=abc; theme=dark-mode;opaque-token` and `Set-Cookie: theme=light-mode; HttpOnly` become (based on [`http.request.header.`](https://getsentry.github.io/sentry-conventions/attributes/http/#http-request-header-key)): ``` -http.request.header.cookie.user_session: "[Filtered]" // matches "session" in sensitive denylist -http.request.header.cookie.theme: "dark-mode" // not sensitive β€” value sent as-is -http.request.header.set_cookie.theme: "light-mode" // not sensitive β€” value sent as-is +http.request.header.cookie: ["user_session=[Filtered]", "theme=dark-mode", "[Filtered]"] +http.request.header.set-cookie: ["theme=light-mode"] ``` +- `user_session=[Filtered]` matches "session" in the sensitive denylist +- `theme=dark-mode` not sensitive, value sent as-is +- `[Filtered]` nameless cookie, where the bare token is a value and is always filtered + For URL query parameters: the rules and terms as specified in `urlQueryParams` in the `dataCollection` configuration apply to query parameters. The SDK replaces values for sensitive keys with `"[Filtered]"` while keeping non-sensitive values as-is (see [URLs](#urls)). **When individual key-value pairs cannot be extracted** (e.g., malformed or opaque cookie string), the entire `Cookie` or `Set-Cookie` header value **MUST** be replaced with `"[Filtered]"`. This value is used as a fallback: ``` -http.request.header.cookie: "[Filtered]" // fallback: cookie header could not be parsed +http.request.header.cookie: ["[Filtered]"] // fallback: cookie header could not be parsed ``` Unfiltered, raw cookie header values **MUST NOT** be sent. When in doubt, treat the entire cookie header as sensitive and use the fallback. From 57f1b52e3c07dc1af70d65623ada8fc189cf49ac Mon Sep 17 00:00:00 2001 From: "sentry-junior[bot]" <264270552+sentry-junior[bot]@users.noreply.github.com> Date: Tue, 6 Oct 2026 15:41:59 +0200 Subject: [PATCH 12/16] docs(mobile): Update stable release cadence to weekly (#19826) ## DESCRIBE YOUR PR The mobile SDKs now aim to ship a stable release about once a week instead of once a month. This updates the "How often do we mark SDKs as stable?" answer on the Android, Flutter, and React Native releases pages. It follows #19821, which made the same change for Apple. ## IS YOUR CHANGE URGENT? Help us prioritize incoming PRs by letting us know when the change needs to go live. Select exactly one option. For deadlines, replace `YYYY-MM-DD` with the due date. You can update this information later by editing the PR description. - [ ] Urgent deadline (GA date, etc.): YYYY-MM-DD - [ ] Other deadline: YYYY-MM-DD - [x] No deadline: Not urgent, can wait up to 1 week+ ## PRE-MERGE CHECKLIST - [ ] Checked Vercel preview for correctness, including links - [ ] PR was reviewed and approved by any necessary SMEs (subject matter experts) - [ ] PR was reviewed and approved by a member of the [Sentry docs team](https://github.com/orgs/getsentry/teams/docs) via **itay**. -- [View Junior Session](https://junior-prod.sentry.dev/conversations/slack%3AG01PW6HRQNN%3A1791291980.069699) [[Sentry]](https://sentry.sentry.io/explore/conversations/slack%3AG01PW6HRQNN%3A1791291980.069699/?project=4510944073809921) Co-authored-by: sentry-junior[bot] <264270552+sentry-junior[bot]@users.noreply.github.com> Co-authored-by: Itay Brenner --- docs/platforms/android/releases/index.mdx | 2 +- docs/platforms/dart/guides/flutter/releases/index.mdx | 2 +- docs/platforms/react-native/common/releases/index.mdx | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/platforms/android/releases/index.mdx b/docs/platforms/android/releases/index.mdx index efc292f736ac0..6078d08fdf767 100644 --- a/docs/platforms/android/releases/index.mdx +++ b/docs/platforms/android/releases/index.mdx @@ -31,7 +31,7 @@ No. Stability and performance are the top priorities for every release. The `Sta ### How often do we mark SDKs as stable? -The stable release cycle depends on a number of factors and can vary, but the target cadence is to provide stable releases roughly every month. +The stable release cycle depends on a number of factors and can vary, but the target cadence is to provide stable releases roughly every week. ### Should I only use stable releases? diff --git a/docs/platforms/dart/guides/flutter/releases/index.mdx b/docs/platforms/dart/guides/flutter/releases/index.mdx index 4c9266c49e480..a2000b7a20ee1 100644 --- a/docs/platforms/dart/guides/flutter/releases/index.mdx +++ b/docs/platforms/dart/guides/flutter/releases/index.mdx @@ -31,7 +31,7 @@ No. Stability and performance are the top priorities for every release. The `Sta ### How often do we mark SDKs as stable? -The stable release cycle depends on a number of factors and can vary, but the target cadence is to provide stable releases roughly every month. +The stable release cycle depends on a number of factors and can vary, but the target cadence is to provide stable releases roughly every week. ### Should I only use stable releases? diff --git a/docs/platforms/react-native/common/releases/index.mdx b/docs/platforms/react-native/common/releases/index.mdx index 8d6f9e06eebbb..33374eb285128 100644 --- a/docs/platforms/react-native/common/releases/index.mdx +++ b/docs/platforms/react-native/common/releases/index.mdx @@ -31,7 +31,7 @@ No. Stability and performance are the top priorities for every release. The `Sta ### How often do we mark SDKs as stable? -The stable release cycle depends on a number of factors and can vary, but the target cadence is to provide stable releases roughly every month. +The stable release cycle depends on a number of factors and can vary, but the target cadence is to provide stable releases roughly every week. ### Should I only use stable releases? From 3cc950cd925234e421bf7793197d4fa745ff5da0 Mon Sep 17 00:00:00 2001 From: Charly Gomez Date: Tue, 6 Oct 2026 16:46:23 +0200 Subject: [PATCH 13/16] docs(js): Document Prisma 8 support in prismaIntegration (#19628) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## DESCRIBE YOUR PR Documents Prisma 8 support in `prismaIntegration`, available from SDK 11.1.0 (getsentry/sentry-javascript#24682). - Add Prisma 8 to the supported versions on the common and Cloudflare Prisma pages - Note that Prisma 8 spans come from channel injection, the span structure, and the unwrapped `db.sql`, `db.raw`, and `groupBy` calls - Note that CommonJS apps on Node.js 20 only get `pg` query spans - Scope the Prisma trace output link to Prisma 5 to 7 `prisma__v8.x.mdx` is intentionally unchanged: it documents SDK 8.x, not Prisma 8. --------- Co-authored-by: Claude Opus 5.5 Co-authored-by: sentry-junior[bot] <264270552+sentry-junior[bot]@users.noreply.github.com> Co-authored-by: Jan Peer StΓΆcklmair --- .../configuration/integrations/prisma.mdx | 20 ++++++++++++++++--- .../configuration/integrations/prisma.mdx | 8 +++++--- 2 files changed, 22 insertions(+), 6 deletions(-) diff --git a/docs/platforms/javascript/common/configuration/integrations/prisma.mdx b/docs/platforms/javascript/common/configuration/integrations/prisma.mdx index 1142dd1ac8d16..ccb374c85cb9c 100644 --- a/docs/platforms/javascript/common/configuration/integrations/prisma.mdx +++ b/docs/platforms/javascript/common/configuration/integrations/prisma.mdx @@ -11,7 +11,7 @@ Sentry supports tracing [Prisma ORM](https://www.prisma.io/) queries with the Pr The Prisma Integrations creates a spans for each query and reports to Sentry with relevant details inside the`description` if available. -This integration is enabled by default and supports Prisma versions 5, 6 & 7. In Prisma v5, you need to follow the instructions below to enable tracing. +This integration is enabled by default and supports Prisma versions 5, 6, 7 & 8. In Prisma v5, you need to follow the instructions below to enable tracing. If you'd like to learn how to modify your default integrations, visit the docs on Modifying Default Integrations. @@ -26,6 +26,20 @@ Sentry.init({ }); ``` +## Prisma Version 8 + + + +No configuration is required. Prisma 8 has no built-in tracing, so the SDK instruments it through diagnostics channels. If channel injection is disabled (`enableRuntimeChannelInjection: false` without build-time injection), no Prisma 8 spans are created. + +Each ORM call creates a `prisma:client:operation` span with the `pg` query spans nested underneath. `db.sql`, `db.raw`, and `groupBy` calls only create `pg` query spans. + + + +On Node.js 20, CommonJS apps only get `pg` query spans. + + + ## Prisma Version 5 To configure the integration for Prisma version 5, first add the `tracing` feature flag to the `generator` block of your Prisma schema: @@ -48,8 +62,8 @@ Sentry.init({ ## Supported Versions -- `prisma`: `5.x`, `6.x`, `7.x` +- `prisma`: `5.x`, `6.x`, `7.x`, `8.x` ## Learn More -For details on the span structure that Prisma's OpenTelemetry tracing produces (e.g., `prisma:client:operation`, `prisma:engine:db_query`), see the [Prisma trace output documentation](https://www.prisma.io/docs/orm/prisma-client/observability-and-logging/opentelemetry-tracing#trace-output). +For details on the span structure that Prisma's OpenTelemetry tracing produces in Prisma versions 5 to 7 (e.g., `prisma:client:operation`, `prisma:engine:db_query`), see the [Prisma trace output documentation](https://www.prisma.io/docs/orm/prisma-client/observability-and-logging/opentelemetry-tracing#trace-output). diff --git a/docs/platforms/javascript/guides/cloudflare/configuration/integrations/prisma.mdx b/docs/platforms/javascript/guides/cloudflare/configuration/integrations/prisma.mdx index 473ab7e74f19b..756ad4e534e7c 100644 --- a/docs/platforms/javascript/guides/cloudflare/configuration/integrations/prisma.mdx +++ b/docs/platforms/javascript/guides/cloudflare/configuration/integrations/prisma.mdx @@ -19,7 +19,7 @@ export default Sentry.defineCloudflareOptions((env) => ({ })); ``` -This integration supports Prisma versions 5, 6, and 7. In Prisma v5, you also need to add the `tracing` preview feature to the `generator` block of your Prisma schema: +This integration supports Prisma versions 5, 6, 7, and 8. In Prisma v5, you also need to add the `tracing` preview feature to the `generator` block of your Prisma schema: ```txt {tabTitle: Prisma Schema} {filename: schema.prisma} {3} generator client { @@ -28,10 +28,12 @@ generator client { } ``` +Prisma 8 has no built-in tracing, so the SDK instruments it through diagnostics channels. If channel injection is disabled (`enableRuntimeChannelInjection: false` without build-time injection), no Prisma 8 spans are created. Each ORM call creates a `prisma:client:operation` span with the `pg` query spans nested underneath. `db.sql`, `db.raw`, and `groupBy` calls only create `pg` query spans. + ## Supported Versions -- `prisma`: `5.x`, `6.x`, `7.x` +- `prisma`: `5.x`, `6.x`, `7.x`, `8.x` ## Learn More -For details on the span structure that Prisma's OpenTelemetry tracing produces (e.g., `prisma:client:operation`, `prisma:engine:db_query`), see the [Prisma trace output documentation](https://www.prisma.io/docs/orm/prisma-client/observability-and-logging/opentelemetry-tracing#trace-output). +For details on the span structure that Prisma's OpenTelemetry tracing produces in Prisma versions 5 to 7 (e.g., `prisma:client:operation`, `prisma:engine:db_query`), see the [Prisma trace output documentation](https://www.prisma.io/docs/orm/prisma-client/observability-and-logging/opentelemetry-tracing#trace-output). From 8abda566b2439259f2fd625f9e403b86fe4007d6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Josh=20Ghoulberg=20=F0=9F=91=BB?= Date: Tue, 6 Oct 2026 12:08:57 -0400 Subject: [PATCH 14/16] docs(logs): document regex search (#19808) ## DESCRIBE YOUR PR Documents regex search for logs (`key://pattern//`) on the search syntax page, with a matching example on the logs page. The API reference counterpart is getsentry/sentry#126458. Closes LOGS-1029. ## IS YOUR CHANGE URGENT? - [ ] Urgent deadline (GA date, etc.): YYYY-MM-DD - [x] Other deadline: 2026-10-08 (regex search for logs is going GA this week) - [ ] No deadline: Not urgent, can wait up to 1 week+ --------- Co-authored-by: Shannon Anahata --- docs/concepts/search/index.mdx | 49 ++++++++++++++++++++++++++++++++++ docs/product/logs/index.mdx | 1 + 2 files changed, 50 insertions(+) diff --git a/docs/concepts/search/index.mdx b/docs/concepts/search/index.mdx index badb344dc5cdd..68e3a99d55f50 100644 --- a/docs/concepts/search/index.mdx +++ b/docs/concepts/search/index.mdx @@ -140,6 +140,55 @@ You may also combine the wildcard character `*` with other operators like so: In the above example, the search query returns results which do not have message values like `ConnectionTimeout`, `ReadTimeout`, etc. +#### Regular Expressions (logs only) + +A regular expression (regex) is a pattern that describes a sequence of characters you want to find in text. They're useful when a plain value or a wildcard isn't precise enough, like finding every log message that starts with `Timeout after` followed by any number of milliseconds. + +You can match a string attribute in [logs](/product/logs/) against a regular expression. + +In the search bar, add a filter for the attribute, open its operator dropdown, and choose **matches regex**, or **does not match regex** to exclude matching values. + +In query syntax, wrap the pattern in double slashes: `key://pattern//`. + +Without any special symbols, a pattern matches anywhere in the value. This matches both `Timeout after 30ms` and `Request Timeout`: + +``` +message://Timeout// +``` + +Patterns support [RE2 syntax](https://github.com/google/re2/wiki/Syntax) to define more specific matchers. + +You can use either or both of `^` to match the start of the field's value, and/or `$` to match the end of the log. +This matches only messages that start with "Timeout": + +``` +message://^Timeout// +``` + +`\d` is a character class, meaning it matches any one character from a set. `\d` matches any digit. This matches `Timeout after 1s` and `Timeout after 234ms`, but not `Timeout after a while`: + +``` +message://^Timeout after \d// +``` + +To exclude matching values, use the negation operator `!`. +This excludes timeouts whose amounts start with `\w`, or word characters: + +``` +!message://^Timeout after \w// +``` + +Keep the following in mind when you write patterns: + +- Regular expressions only work on string attributes in logs. +- Patterns use [RE2 syntax](https://github.com/google/re2/wiki/Syntax), which doesn't support lookarounds or backreferences. +- Patterns are case sensitive. Start a pattern with `(?i)` to ignore case. +- Patterns can be up to 64 characters long. An escape sequence like `\d` counts as one character. +- Spaces and parentheses inside a pattern don't need quotes. +- A pattern ends at the first `//` followed by a space, a `)`, or the end of the query. To match `//`, escape it as `\/\/`. +- There's no list form like `key:[value1, value2]`. Use `|` inside the pattern instead. +- To search for a literal value that starts with `//`, wrap it in quotes, like `url:"//cdn.example.com/"`. + ## Page Filters Page filters allow you to narrow down the results shown on a page by selecting specific projects, environments, and date ranges. After you've set your filters, they'll persist as you navigate across pages in Sentry. diff --git a/docs/product/logs/index.mdx b/docs/product/logs/index.mdx index 814c98ef38f16..7dda832ec09e6 100644 --- a/docs/product/logs/index.mdx +++ b/docs/product/logs/index.mdx @@ -62,6 +62,7 @@ Here are some practical examples of log searches you can use: - `order.id:order_123` - Find logs related to a specific order - `severity:warn OR severity:error` - Find warnings or errors - `database:"users" query.duration_ms:>1000` - Find slow database queries on the users database +- `message://^Timeout after \d+ms//` - Find logs whose message matches a [regular expression](/concepts/search/#regular-expressions-logs-only) Learn more about [search syntax](/concepts/search/) for advanced querying. From 5e7b9969c4bb9275c3785c3704f7ce5e5e6ad699 Mon Sep 17 00:00:00 2001 From: "sentry-api-schema-updater[bot]" <271575301+sentry-api-schema-updater[bot]@users.noreply.github.com> Date: Tue, 6 Oct 2026 16:38:38 +0000 Subject: [PATCH 15/16] Bump API schema to 315d75c2 (#19827) Co-authored-by: sentry-api-schema-updater[bot] <271575301+sentry-api-schema-updater[bot]@users.noreply.github.com> --- src/build/resolveOpenAPI.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/build/resolveOpenAPI.ts b/src/build/resolveOpenAPI.ts index 90edb11674a7d..44229b44a9df8 100644 --- a/src/build/resolveOpenAPI.ts +++ b/src/build/resolveOpenAPI.ts @@ -6,7 +6,7 @@ import {DeRefedOpenAPI} from './open-api/types'; // SENTRY_API_SCHEMA_SHA is used in the sentry-docs GHA workflow in getsentry/sentry-api-schema. // DO NOT change variable name unless you change it in the sentry-docs GHA workflow in getsentry/sentry-api-schema. -const SENTRY_API_SCHEMA_SHA = '039965a844f9bbd7f90bca18fbd4f1e7ca8c64ea'; +const SENTRY_API_SCHEMA_SHA = '315d75c2793e9aacf34d6685cd6dac8e083d83b5'; const activeEnv = process.env.GATSBY_ENV || process.env.NODE_ENV || 'development'; From c07231411cdd5e23ec8f9043ed4cd50546c63ddc Mon Sep 17 00:00:00 2001 From: "sentry-api-schema-updater[bot]" <271575301+sentry-api-schema-updater[bot]@users.noreply.github.com> Date: Tue, 6 Oct 2026 17:02:48 +0000 Subject: [PATCH 16/16] Bump API schema to 096cbc78 (#19828) Co-authored-by: sentry-api-schema-updater[bot] <271575301+sentry-api-schema-updater[bot]@users.noreply.github.com> --- src/build/resolveOpenAPI.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/build/resolveOpenAPI.ts b/src/build/resolveOpenAPI.ts index 44229b44a9df8..5bc4dcee5073f 100644 --- a/src/build/resolveOpenAPI.ts +++ b/src/build/resolveOpenAPI.ts @@ -6,7 +6,7 @@ import {DeRefedOpenAPI} from './open-api/types'; // SENTRY_API_SCHEMA_SHA is used in the sentry-docs GHA workflow in getsentry/sentry-api-schema. // DO NOT change variable name unless you change it in the sentry-docs GHA workflow in getsentry/sentry-api-schema. -const SENTRY_API_SCHEMA_SHA = '315d75c2793e9aacf34d6685cd6dac8e083d83b5'; +const SENTRY_API_SCHEMA_SHA = '096cbc7896b72cc523fb422f327aae973ab0b5c4'; const activeEnv = process.env.GATSBY_ENV || process.env.NODE_ENV || 'development';