diff --git a/develop-docs/backend/application-domains/tasks/index.mdx b/develop-docs/backend/application-domains/tasks/index.mdx index 1ed27caf8b537a..c43b40e8099da2 100644 --- a/develop-docs/backend/application-domains/tasks/index.mdx +++ b/develop-docs/backend/application-domains/tasks/index.mdx @@ -270,6 +270,50 @@ This registers the task as both: - `integrations_tasks:sentry.widgets.tasks.do_work_v2` (new) - `issues_tasks:sentry.widgets.tasks.do_work` (old) +## External Tasks + +An application can create tasks for another application to execute through the usage of +**external namespaces**: + +```python +from sentry.taskworker.app import app + +# Create an external namespace +launchpad_tasks = app.create_external_namespace( + application="launchpad", + name="default" +) +``` + +With an external namespace you can register and spawn **external tasks**. + +```python +@launchpad_tasks.register(name="launchpad.task.name") +def run_process(org_id: int, project_id: int, payload: bytes) -> None: + pass + + +# Schedule the task +run_process.delay(org_id=1, project_id=123, payload=blob) +``` + +Like local tasks, external tasks can typecheck their parameters and support all +of the retry, deadline and idempotency features tasks provide. When an external +task is produced, the producing application's task router will be used to +resolve which topic external task activations are sent to. The task router will +receive an application prefixed namespace name eg. `launchpad:default`. + +External tasks have a few restrictions: + +1. They cannot be called synchronously. Eg. `external_task_func(org_id)` will + fail with an exception as external tasks do not have an implementation in the + producing application. +2. The `name` assigned to the external task **must** be the same as the task + name registered in the application that will execute the task. +3. External tasks must be mocked within a testing context manager. Within + a testing context manager, tasks become synchronous, and raise exceptions. + + ## Testing Tasks Tasks can be tested with a few different approaches. The first is with the diff --git a/develop-docs/engineering-practices/ai-assisted-development.mdx b/develop-docs/engineering-practices/ai-assisted-development.mdx index 17624ef4ef51ab..09fdb8a3924af3 100644 --- a/develop-docs/engineering-practices/ai-assisted-development.mdx +++ b/develop-docs/engineering-practices/ai-assisted-development.mdx @@ -96,10 +96,10 @@ Connect your AI assistant to the services your team already uses. These are the | Tool | What it gives you | | ---- | ----------------- | -| [Sentry MCP](https://docs.sentry.io/product/sentry-mcp/) | Query errors, search issues, analyze traces, and get root cause analysis directly from your editor. | +| [Sentry MCP](https://docs.sentry.io/ai/mcp/) | Query errors, search issues, analyze traces, and get Autofix (root cause analysis and code fixes) directly from your editor. | | [Linear MCP](https://github.com/jerhadf/linear-mcp-server) | Create, search, and update Linear issues without leaving your session. | | [Notion MCP](https://github.com/makenotion/notion-mcp-server) | Search and read Notion pages. Useful for pulling in specs, RFCs, and team docs as context. | -| [Slack MCP](https://github.com/nicholasgriffintn/slack-mcp-server) | Read Slack threads and channels. Paste a bug report thread and say "fix." | +| [Slack MCP](https://docs.slack.dev/ai/slack-mcp-server/) | Read Slack threads and channels. Paste a bug report thread and say "fix." | #### CLIs diff --git a/develop-docs/engineering-practices/commit-messages.mdx b/develop-docs/engineering-practices/commit-messages.mdx index 806994a78e1be6..2dac4dbf6dceca 100644 --- a/develop-docs/engineering-practices/commit-messages.mdx +++ b/develop-docs/engineering-practices/commit-messages.mdx @@ -16,7 +16,7 @@ sidebar_order: 10 ### Merge vs Rebase -Sentry uses a rebase workflow. That means that every commit on its own should be a clear, functional, and stable change. This means that when you’re building a new feature, you should try to pare it down into functional steps, and when that’s not reasonable, the end patch should be a single commit. This is counter to having a Pull Request which may include “fix [unmerged] behavior”. Those commits should be squashed, and the final patch when landed should be rebased. +Sentry uses a rebase workflow. That means that every commit on its own should be a clear, functional, and stable change. This means that when you’re building a new feature, you should try to parse it down into functional steps, and when that’s not reasonable, the end patch should be a single commit. This is counter to having a Pull Request which may include “fix [unmerged] behavior”. Those commits should be squashed, and the final patch when landed should be rebased. Remember: each commit should follow the commit message format and be stable (green build). diff --git a/develop-docs/sdk/foundations/trace-propagation/index.mdx b/develop-docs/sdk/foundations/trace-propagation/index.mdx index 06c6ba49cac4d4..29935c3ee890f6 100644 --- a/develop-docs/sdk/foundations/trace-propagation/index.mdx +++ b/develop-docs/sdk/foundations/trace-propagation/index.mdx @@ -128,23 +128,46 @@ This option replaces the non-standardized `tracingOrigins` option which was prev -### strictTraceContinuation +### Strict Trace Continuation -This **MUST** be a boolean value. Default is `false`. This option controls trace continuation from unknown 3rd party services that happen to be instrumented by a Sentry SDK. +The `strictTraceContinuation` option controls whether to continue a trace when **either the incoming trace or the receiving SDK has an organization ID, but not both**. This scenario typically would happen if the incoming trace originates from a third-party service instrumented with Sentry. -If the SDK is able to parse an org ID from the configured DSN, it **MUST** be propagated as a baggage entry with the key `sentry-org_id`. Given a DSN of `https://1234@o1.ingest.us.sentry.io/1`, the org ID is `1`, based on `o1`. +#### Required Configuration Options -Additionally, the SDK **MUST** be configurable with an optional `orgId: ` setting that takes precedence over the parsed value from the DSN. This option **SHOULD** be set when running a self-hosted version of Sentry or if a non-standard Sentry DSN is used, such as when using a local Relay. +SDKs **MUST** support the following configuration options: -On incoming traces, the SDK **MUST** compare the `sentry-org_id` baggage value against its own parsed value from the DSN or org setting. Only if both match, the trace is continued. If there is no match, neither the trace ID, the parent sampling decision nor the baggage **SHOULD** be taken into account. The SDK **SHOULD** behave like it is the head of trace in this case. +- `strictTraceContinuation`: **MUST** be a boolean value. Default is `false`. +- `orgId`: optional override of the organization ID [parsed from the DSN](https://develop.sentry.dev/sdk/foundations/transport/authentication/#parsing-the-dsn). + - SDK documentation for the `orgId` option **SHOULD** recommend setting `orgId` for self-hosted Sentry and local Relay setups. -This behavior can be disabled by setting `strictTraceContinuation: false` in the SDK init call. Initially, SDKs **MUST** introduce this option with a default value of `false`. Once the majority of SDKs have introduced this option, the default value will change to `true` (in a major version bump), making it opt-out. + -Regardless of `strictTraceContinuation` being set to `true` or `false`, if the SDK is either configured with an `org` or was able to parse the value from the DSN, incoming traces containing an `org` value in the baggage that does not match the one from the receiving SDK, the trace is not continued. +Once most SDKs support the `strictTraceContinuation` option, we intend to migrate the default value to `true`. As this change is breaking, it will be part of a major release. + + + +#### The SDK's Organization ID + +The SDK **MUST** determine its organization ID as follows: +- If `orgId` is present, the SDK's organization ID is the value passed to `orgId`. +- Otherwise, the SDK's organization ID is the organization ID [in the DSN](https://develop.sentry.dev/sdk/foundations/transport/authentication/#parsing-the-dsn). +- If `orgId` is absent and the DSN cannot be parsed, then the organization ID is missing. + +If the SDK has an organization ID, the SDK **MUST** propagate the organization ID in baggage as `sentry-org_id`. + +#### Continuing Traces + +On incoming traces, the SDK **MUST** compare the incoming `sentry-org_id` with its own organization ID, as defined above. + +- If both values are present and differ, the SDK **MUST NOT** continue the trace, regardless of `strictTraceContinuation`. +- If exactly one value is present, the SDK **MUST NOT** continue when `strictTraceContinuation` is `true`, and **SHOULD** continue when it is `false`. +- If both values are present and equal, or both are absent, the SDK **SHOULD** continue the trace. + +When the SDK does not continue a trace, the incoming trace ID, parent sampling decision, and incoming baggage **SHOULD** be ignored. In this case, the SDK **SHOULD** behave as the head of a trace. #### Examples -| Baggage `sentry-org` | SDK `org` | `strictTraceContinuation` | Result | +| Baggage `sentry-org_id` | SDK organization ID | `strictTraceContinuation` | Result | | --- | --- | :---: | --- | | 1 | 1 | false | continue trace | | none | 1 | false | continue trace | diff --git a/develop-docs/sdk/getting-started/ai-tools/code-review/index.mdx b/develop-docs/sdk/getting-started/ai-tools/code-review/index.mdx index 6941e37b49046a..8c3e33121a70c5 100644 --- a/develop-docs/sdk/getting-started/ai-tools/code-review/index.mdx +++ b/develop-docs/sdk/getting-started/ai-tools/code-review/index.mdx @@ -10,7 +10,7 @@ Sentry SDK repositories use AI code review tools to catch bugs, enforce standard Seer is Sentry's own AI platform. Its AI Code Review feature analyzes pull request diffs to predict errors, highlight potential bugs, and suggest improvements. It provides line-by-line comments, code summaries, risk assessments, and can even generate unit tests. -https://docs.sentry.io/product/ai-in-sentry/seer/ai-code-review/ +https://docs.sentry.io/product/ai-in-sentry/seer/code-review/ ### Activation diff --git a/develop-docs/sdk/getting-started/playbooks/coordination/triaging.mdx b/develop-docs/sdk/getting-started/playbooks/coordination/triaging.mdx index 6c9a37f54b80a8..218189d59d53ca 100644 --- a/develop-docs/sdk/getting-started/playbooks/coordination/triaging.mdx +++ b/develop-docs/sdk/getting-started/playbooks/coordination/triaging.mdx @@ -27,7 +27,7 @@ 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#triaging-sla) — 2 business day first response requirement +- [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,7 +50,7 @@ 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#triaging-sla)) +- **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. @@ -79,11 +79,24 @@ Every item **MUST** exit the triage queue via exactly one of the following paths Prevent stagnation: escalate urgent issues and communicate unresolved issues promptly. +#### 5. Respond to label states + +Labels are applied automatically to reflect where action is required: + +| Label | Meaning | +| --- | --- | +| **`Waiting for: Product Owner`** | The issue is waiting on the maintainer. This label carries a 2 business day SLA — the maintainer **MUST** respond within 2 business days each time this label is active. | +| **`Waiting for: Community`** | The maintainer has responded and is awaiting a reply, reproduction, or confirmation from the reporter or community. | + +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) + --- ## Referenced Standards -- [Triaging SLA](/sdk/getting-started/standards/coordination-maintenance#triaging-sla) — 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 820cf871020fd4..8ca8c857a7d80b 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 @@ -22,7 +22,7 @@ This playbook guides SDK maintainers through the process of adding a new depende 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#sdk-size-and-performance-budgets) — size and performance tracking requirements +- [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#sdk-size-and-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 @@ -65,7 +65,7 @@ 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#sdk-size-and-performance-budgets) — size and performance budget tracking +- [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 08948bf8c0021a..00151301303c96 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,8 +23,8 @@ 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#post-release-monitoring) — how regressions are detected -- [Rollback procedures](/sdk/getting-started/standards/coordination-maintenance#rollback-procedures) — emergency rollback process +- [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) --- @@ -50,7 +50,7 @@ You **MUST** take one of the following actions: **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#rollback-procedures) +- 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#post-release-monitoring) — monitoring that detects regressions -- [Rollback procedures](/sdk/getting-started/standards/coordination-maintenance#rollback-procedures) — emergency rollback process -- [Release Gating Criteria](/sdk/getting-started/standards/review-ci#release-gating-criteria) — 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 b495fdf7d313ef..be8d528945befa 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 @@ -35,7 +35,7 @@ Related resources: #### 1. Triage within 2 business days -([Review SLAs](/sdk/getting-started/standards/review-ci#review-slas)). 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 @@ -55,7 +55,7 @@ Review it using the standard process ([Reviewing a PR](/sdk/getting-started/play #### 6. When requesting changes -You **MUST** be specific, use LOGAF prefixes ([Review feedback conventions](/sdk/getting-started/standards/review-ci#review-feedback-conventions)), 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,8 +63,8 @@ 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#review-slas) — timely response requirements -- [Review feedback conventions](/sdk/getting-started/standards/review-ci#review-feedback-conventions) — LOGAF scale for feedback +- [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 40d4f3df49e5a0..b5bd90b75541e2 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 @@ -75,7 +75,7 @@ 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#required-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)). ## Referenced Standards @@ -87,8 +87,8 @@ If the PR touches public API, dependencies, or security-sensitive areas, you **M - [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#required-reviewers) — @sdk-seniors review triggers -- [Test requirements by change type](/sdk/getting-started/standards/code-quality#test-requirements-by-change-type) — test coverage 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 5e8472db060743..0b93ecadfddbf9 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 @@ -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#test-requirements-by-change-type)) -- Test quality — do assertions verify real behavior? ([Test quality](/sdk/getting-started/standards/code-quality#test-quality)) +- 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#required-reviewers)): 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#review-feedback-conventions)): +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,11 +78,11 @@ 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#review-feedback-conventions) — LOGAF scale and blocking criteria -- [Required reviewers](/sdk/getting-started/standards/review-ci#required-reviewers) — @sdk-seniors review triggers -- [Required CI checks baseline](/sdk/getting-started/standards/review-ci#required-ci-checks-baseline) — minimum CI requirements -- [Test requirements by change type](/sdk/getting-started/standards/code-quality#test-requirements-by-change-type) — test coverage expectations -- [Test quality](/sdk/getting-started/standards/code-quality#test-quality) — meaningful assertion 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 923b5a6a0999be..7b84b08e37af5d 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 @@ -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#test-requirements-by-change-type)), test quality ([Test quality](/sdk/getting-started/standards/code-quality#test-quality)). +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#review-feedback-conventions)) +([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#test-quality)). 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 @@ -91,9 +91,9 @@ You **SHOULD** use the [`sentry-skills:find-bugs`](https://github.com/getsentry/ ## Referenced Standards -- [Review feedback conventions](/sdk/getting-started/standards/review-ci#review-feedback-conventions) — LOGAF scale and blocking criteria -- [Test requirements by change type](/sdk/getting-started/standards/code-quality#test-requirements-by-change-type) — test coverage expectations -- [Test quality](/sdk/getting-started/standards/code-quality#test-quality) — meaningful assertion requirements +- [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 e3d92f0e62be04..d02027b079f8c4 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 @@ -23,8 +23,8 @@ spec_changelog: This playbook guides SDK maintainers through deciding whether a change is breaking and, if so, how to ship it with minimum friction for users. It covers classifying changes, estimating product impact, planning the release, and writing migration guidance. By following these steps, users will have clear migration paths and the SDK update experience will be as smooth as possible. Related resources: -- [Breaking change process](/sdk/getting-started/standards/api-architecture#breaking-change-process) — when a major release is required and what every breaking change must include -- [Deprecation lifecycle](/sdk/getting-started/standards/api-architecture#deprecation-lifecycle) — the deprecation stages and timelines +- [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 - [Release and Versioning](/sdk/getting-started/standards/release-versioning) — SemVer requirements and release tooling @@ -68,7 +68,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-change-process). 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: @@ -78,7 +78,7 @@ 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#deprecation-lifecycle): +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 @@ -120,8 +120,8 @@ 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-change-process) — when a major release is required, required artifacts, and enforcement -- [Deprecation lifecycle](/sdk/getting-started/standards/api-architecture#deprecation-lifecycle) — deprecation timeline and stages +- [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 acd028111bf2fc..14236f40c2b5e8 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 @@ -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-criteria)): +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,7 +84,7 @@ 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#post-release-monitoring)): +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 @@ -111,9 +111,9 @@ Common SDK-specific variations include: ## Referenced Standards -- [Release gating criteria](/sdk/getting-started/standards/review-ci#release-gating-criteria) — pre-release quality gates -- [Post-release monitoring](/sdk/getting-started/standards/coordination-maintenance#post-release-monitoring) — monitoring requirements and timeline -- [Rollback procedures](/sdk/getting-started/standards/coordination-maintenance#rollback-procedures) — 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 c1d6097659d711..1c38b72f279542 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,8 +25,8 @@ 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#deprecation-lifecycle) — deprecation timeline and requirements -- [Breaking change process](/sdk/getting-started/standards/api-architecture#breaking-change-process) — process for eventual API removal +- [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 --- @@ -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-change-process)) +- 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,8 +73,8 @@ For high-impact deprecations, you **SHOULD** consider a blog post or announcemen ## Referenced Standards -- [Deprecation lifecycle](/sdk/getting-started/standards/api-architecture#deprecation-lifecycle) — deprecation timeline requirements -- [Breaking change process](/sdk/getting-started/standards/api-architecture#breaking-change-process) — process for API removal in major versions +- [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/dropping-platform-support.mdx b/develop-docs/sdk/getting-started/playbooks/sdk-lifecycle/dropping-platform-support.mdx index 0abc51bdec24f1..aa82d9c5907dc0 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,8 +24,8 @@ 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-change-process) — process for removal in major versions -- [Deprecation lifecycle](/sdk/getting-started/standards/api-architecture#deprecation-lifecycle) — deprecation timeline +- [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 --- @@ -61,7 +61,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-change-process)) +- Include `BREAKING CHANGE:` in the commit footer ([Breaking change process](/sdk/getting-started/standards/api-architecture#breaking-and-deprecation)) #### 5. Provide migration guidance @@ -73,8 +73,8 @@ This helps users understand the upgrade path and avoid breaking their applicatio ## Referenced Standards -- [Breaking change process](/sdk/getting-started/standards/api-architecture#breaking-change-process) — process for removal in major versions -- [Deprecation lifecycle](/sdk/getting-started/standards/api-architecture#deprecation-lifecycle) — deprecation timeline 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 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 2cdcd3e6aa61bc..44a4566bc2d9f6 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 @@ -41,7 +41,7 @@ Related resources: 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#required-reviewers)) +- 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#agents-md)) — Use the [AGENTS.md template](/sdk/getting-started/templates/agents-md-template). 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#contributing-md)) — Use the [CONTRIBUTING.md template](/sdk/getting-started/templates/contributing-md-template), customized for this SDK. -- `.github/PULL_REQUEST_TEMPLATE.md` ([PR template](/sdk/getting-started/standards/repository-docs#pr-template)) — 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-template). 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-template), 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-formatting-ci)) -- Type checking, if applicable for the language ([Type checking in CI](/sdk/getting-started/standards/code-quality#type-checking-ci)) +- 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)) #### 4. AI context files -You **MUST** create AI context files ([AI context file maintenance](/sdk/getting-started/standards/repository-docs#ai-context-maintenance)): +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#rollback-procedures)): +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#agents-md) — AI context file requirements -- [CONTRIBUTING.md](/sdk/getting-started/standards/repository-docs#contributing-md) — contributor guidelines -- [PR template](/sdk/getting-started/standards/repository-docs#pr-template) — pull request template structure -- [AI context file maintenance](/sdk/getting-started/standards/repository-docs#ai-context-maintenance) — maintaining AI-readable documentation -- [Required reviewers](/sdk/getting-started/standards/review-ci#required-reviewers) — review approval requirements +- [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-formatting-ci) — automated code style checks -- [Type checking in CI](/sdk/getting-started/standards/code-quality#type-checking-ci) — static type verification +- [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#rollback-procedures) — release rollback documentation +- [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 67213ce13888fb..1a9c98c8b56f46 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 @@ -127,10 +127,10 @@ For the ongoing release process after setup, see "Cutting a release" (wip). ## Referenced Standards -- [Version format](/sdk/getting-started/standards/release-versioning#version-format) — SemVer requirements +- [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-criteria) — Pre-release validation requirements -- [Rollback procedures](/sdk/getting-started/standards/coordination-maintenance#rollback-procedures) — Emergency release rollback process +- [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 291cb6aba8451a..0af4b7c6d9b4c3 100644 --- a/develop-docs/sdk/getting-started/standards/api-architecture.mdx +++ b/develop-docs/sdk/getting-started/standards/api-architecture.mdx @@ -2,7 +2,7 @@ title: API and Architecture spec_id: sdk/getting-started/standards/api-architecture spec_version: 1.0.0 -spec_status: candidate +spec_status: stable spec_platforms: - all spec_changelog: @@ -16,179 +16,104 @@ sidebar_order: 1 - +These standards guide how SDKs are designed and evolved. The core philosophy: prefer server-side logic, protect public API stability, and give users smooth upgrade paths. SDKs often stay installed for years after release, so decisions made today have long-lasting consequences. -## Server-side (Relay) vs. SDK-side decision gate + -#### Rule +## Server-side (Relay) vs. SDK implementation -New processing or transformation logic **MUST** default to server-side (Relay). +When deciding where new logic should live, default to server-side (Relay). Processing data in Relay keeps behavior consistent across SDK versions and avoids duplicating logic in clients that may remain deployed indefinitely. -Logic **SHOULD** only be implemented in the SDK when it meets one of these criteria: +Put logic in the SDK only when it genuinely needs to run client-side: -- **MUST** run before data leaves the customer's application (e.g., user-controlled filtering like `before_send_*`) -- **REQUIRES** access to platform-specific APIs -- Is strictly latency-sensitive -- **MUST** function in offline scenarios +- It **MUST** run before data leaves the customer's application (e.g., user-controlled filtering like `before_send_*`) +- It requires access to platform-specific APIs +- It's strictly latency-sensitive +- It **MUST** function in offline scenarios -Transformations of data that has already been collected should be handled in Relay. This ensures consistency across SDK versions and avoids duplicating logic in clients that may remain in use indefinitely. - -#### Enforcement - -- AGENTS.md instruction -- Human review - -#### Per-SDK override - - The default is universal. Justifications are -SDK-specific. +If data has already been collected, transform it in Relay. --- - - -## SDK-side logic must not break on server changes - -#### Rule - -SDKs typically outlive individual API versions, so forward compatibility is essential to prevent ecosystem breakage. - -SDKs **MUST** remain resilient to evolving server responses: - -- Additional fields -- Missing optional fields -- New enum values -- Rate limiting - -They **MUST NOT** fail due to additive changes. Unknown fields, categories, or dimensions **SHOULD** be safely ignored rather than causing errors. + -#### Enforcement +## Forward compatibility -- Integration tests for degraded server scenarios (additional fields, missing optional fields, new enum values, rate limiting) -- Human review +SDKs typically outlive individual API versions. A user might stay on an SDK release for months or years, while server responses continue to evolve. SDKs **MUST** handle this gracefully: -#### Per-SDK override +- Ignore unknown fields, categories, or dimensions rather than erroring +- Tolerate missing optional fields +- Accept new enum values without crashing +- Handle rate limiting responses - Specific tests vary. Principle is universal. +The general principle: additive server-side changes **MUST NOT** break existing SDK versions. --- - + -## Public API change approval gate +## Public API changes -#### Rule +Any change to public API — adding, modifying, deprecating, or removing — **REQUIRES** approval from an [SDK Senior Engineer](https://github.com/orgs/getsentry/teams/sdk-seniors). -Any change to public API (add, change, deprecate, remove) **REQUIRES** @sdk-seniors approval. Public API includes anything a user can call, import, configure, subclass, or otherwise reference. If there is any doubt whether something is public, check for usage in public repositories using the SDK. When still unsure, treat it as public. +Public API includes anything a user can call, import, configure, subclass, or otherwise reference. When in doubt, check for usage in public repositories. If you're still unsure, treat it as public. -#### Enforcement - -- CI API snapshot diffs (where feasible) -- Human review gate (@sdk-seniors approval) - -#### Suggested skill(s) - -- [`sentry-skills:code-review`](https://github.com/getsentry/skills#available-skills) — flags API changes for escalation. - -#### Per-SDK override - - Detection mechanisms are language-specific. Approval -requirement is universal. +How each SDK detects API changes (CI snapshot diffs, etc.) varies by language, but the approval requirement applies everywhere. --- - + -## Semantic conventions process +## Semantic conventions -#### Rule +Semantic conventions are shared across SDKs, ingest, and the product — treat them like public API. New attributes **MUST** be defined in [sentry-conventions](https://github.com/getsentry/sentry-conventions) before SDK implementation. The process: -New attributes **MUST** first be defined in [sentry-conventions](https://github.com/getsentry/sentry-conventions). -Process: +1. Open a PR to sentry-conventions +2. Get code owner approval +3. Wait at least 3 business days +4. Implement in the SDK -1. PR to sentry-conventions -2. code owner approval -3. 3 business day minimum wait -4. SDK implementation +This ensures attributes are reviewed and consistent across the ecosystem before any SDK ships them. -#### Enforcement - -- CI validation where feasible -- Human review - -#### Per-SDK override - - +Changes to existing attributes (renaming, removing, or changing semantics) are breaking changes and **MUST** follow the [breaking change process](#breaking-and-deprecation). The sentry-conventions repo has its own deprecation lifecycle — deprecated attributes go through a `backfill` period (at least 90 days) before moving to `normalize`, and replacements and aliases **MUST** be maintained for both old and new names during the transition. --- - - -## Breaking change process + -#### Rule +## Breaking changes and deprecations -Breaking changes **MUST** follow the [breaking changes playbook](/sdk/getting-started/playbooks/sdk-lifecycle/breaking-changes). +Breaking changes and deprecations are closely linked — every breaking change goes through a deprecation period first. Both follow a lifecycle designed to give users time and guidance to migrate. -Breaking changes **MAY** only ship in a major version. They **MUST NOT** ship in minor versions. Opt-in previews are allowed in minor versions. +### Deprecation lifecycle -A deprecation period is **REQUIRED** in a prior minor version, during which dual behavior is allowed to support migration. +Deprecations of public APIs, integrations, and supported platforms follow three stages: -Every breaking change **MUST** include: - -- A migration guide with copy-pastable examples -- A changelog entry using the BREAKING CHANGE: notation -- Validation of the migration guide using an LLM to ensure it is clear and complete - -#### Enforcement - -- [Commit footer BREAKING CHANGE:](/engineering-practices/commit-messages/#footer) triggers CI checks -- Breaking changes in non-major branches are CI-blocked -- Human review +1. **Announce** in a minor release: add a runtime warning (where possible), update the changelog and docs, and publish a migration guide. Warnings **MUST** include the replacement, a code example, and a link to migration docs. +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). -#### Suggested skill(s) +Deprecating an entire SDK is a bigger deal — it requires customer impact analysis, a public announcement, updated documentation, a defined support timeline, and advance EOL notice. -- [`sentry-skills:code-review`](https://github.com/getsentry/skills#available-skills) +### Breaking changes -#### Per-SDK override - - Deprecation period timelines can vary. Process is -universal. - - - ---- +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. - - -## Deprecation lifecycle - -#### Rule - -All deprecations of public APIs, user-facing integrations, and supported platforms or frameworks follow three stages: - -1. Announce in a minor release with a runtime warning (where possible), updated changelog and documentation, and a migration guide. Warnings **MUST** include the replacement, a code example, and a link to the migration docs. -2. Keep the deprecated surface fully functional for at least one subsequent minor release (e.g., deprecated in X.Y, still supported in X.(Y+1)). -3. Remove only in the next major release (X+1.0). - -Deprecating an entire SDK **MUST NOT** be silent. It **REQUIRES** clear customer impact analysis, a public announcement, updated documentation, a defined support timeline, and advance EOL notice. - -#### Enforcement - -- CI checks deprecated APIs still have passing tests -- Human review +Every breaking change **MUST** include: -#### Per-SDK override +- A migration guide with copy-pastable examples +- A changelog entry using the `BREAKING CHANGE:` notation +- Validation of the migration guide using an LLM to ensure clarity and completeness - Minimum period can be extended. Stages are universal. +Deprecation timelines can vary by SDK, but the stages and process apply everywhere. diff --git a/develop-docs/sdk/getting-started/standards/code-quality.mdx b/develop-docs/sdk/getting-started/standards/code-quality.mdx index dbe6946265cecf..15b9e64c1a2f5e 100644 --- a/develop-docs/sdk/getting-started/standards/code-quality.mdx +++ b/develop-docs/sdk/getting-started/standards/code-quality.mdx @@ -2,7 +2,7 @@ title: Code Quality spec_id: sdk/getting-started/standards/code-quality spec_version: 1.0.0 -spec_status: candidate +spec_status: stable spec_platforms: - all spec_changelog: @@ -16,199 +16,87 @@ sidebar_order: 3 - +These standards define the baseline quality expectations for SDK code. They apply across all SDKs — specific tools and thresholds vary by language, but the principles are universal. -## Linting and Formatting in CI + -#### Rule +## Linting, formatting, and type checking -Every SDK repo **MUST** have automated linting and formatting in CI. Code that doesn't pass **MUST NOT** merge. There are no exceptions to this requirement. +Every SDK repo **MUST** enforce linting and formatting in CI. Code that doesn't pass can't merge — no exceptions. -#### Enforcement +Type checking is also **REQUIRED** in CI for statically typed languages (Java, Kotlin, Swift, C#, Go, Rust, Dart) and dynamically typed languages with established type-checking ecosystems (TypeScript, Python, PHP, Elixir). Languages without mature type-checking tooling (e.g., Ruby) may be exempt. -- CI required status check (language-specific linters) - -#### Suggested skill(s) - -- [`sentry-skills:claude-settings-audit`](https://github.com/getsentry/skills#available-skills) - detects tech stack and recommends linter configuration. - -#### Per-SDK override - - Linter choice, rules, strictness. The standard is -that a linter exists and is enforced. - - - ---- - - - -## Type Checking in CI - -#### Rule - -Type checking is **REQUIRED** in CI for: - -- All statically typed languages (Java, Kotlin, Swift, C#, Go, Rust, Dart) -- Dynamically typed languages with an established type-checking ecosystem (TypeScript, Python, PHP, Elixir) - -Dynamically typed languages without an established type-checking system (e.g., Ruby) are TBD or **MAY** be exempt with a valid reason. - -#### Enforcement - -- CI required status check - -#### Per-SDK override - - Configuration and strictness. Gradual typing allowed -with a tracked plan. - - - ---- - - - -## Test Requirements by Change Type - -#### Rule - -- **Bug fix**: regression test (fails without fix, passes with it). -- **New feature**: unit tests + integration tests where applicable. -- **Refactor**: existing tests pass; no new tests required unless coverage was missing. -- **Performance change**: benchmark or measurable evidence. -- **Breaking change**: update/remove old tests, add new tests. - -#### Enforcement - -- AGENTS.md instruction -- Human review - -#### Suggested skill(s) - -- [`sentry-skills:code-review`](https://github.com/getsentry/skills#available-skills) - includes test coverage in checklist -- [`sentry-skills:find-bugs`](https://github.com/getsentry/skills#available-skills) - identifies untested paths - -#### Per-SDK override - - Test categories and boundaries are SDK-specific. +Which linter, what rules, and how strict — that's up to each SDK. The standard is that automated checks exist and block merges. --- - + -## Test Quality +## Testing -#### Rule +### What to test -Tests **MUST** assert meaningful behavior: +The type of change determines what tests are needed: -- Assertions **MUST** fail if the tested behavior breaks -- "No exception thrown" assertions are only acceptable when exception handling is the behavior being tested -- Snapshot tests **MUST** be reviewed for correctness, not auto-accepted -- AI-generated tests **REQUIRE** extra scrutiny for: - - Hardcoded values - - Implementation-detail testing - - Tests that pass regardless of behavior +- **Bug fix**: a regression test that fails without the fix and passes with it +- **New feature**: unit tests, plus integration tests where applicable +- **Refactor**: existing tests should still pass; add new tests only if coverage was missing +- **Performance change**: benchmark or measurable evidence +- **Breaking change**: update or remove old tests, add new ones -#### Enforcement +### Test quality -- AGENTS.md: "Every test must answer: what user-visible behavior would break if this test were deleted?" -- Human review +Tests should assert meaningful behavior. Ask yourself: *what user-visible behavior would break if this test were deleted?* If the answer is "nothing," the test isn't useful. -#### Suggested skill(s) +Some specific things to watch for: -- [`sentry-skills:code-review`](https://github.com/getsentry/skills#available-skills) -- [`sentry-skills:find-bugs`](https://github.com/getsentry/skills#available-skills) - -#### Per-SDK override - - Principle is universal. Language-specific -anti-patterns documented per-SDK in AGENTS.md. +- "No exception thrown" is only a valid assertion when exception handling is the behavior under test +- Snapshot tests need to be reviewed for correctness, not auto-accepted +- AI-generated tests need extra scrutiny — look for hardcoded values, implementation-detail testing, and tests that pass regardless of behavior --- - - -## Dependency Management - -#### Rule - -- New dependency **REQUIRES** explicit justification in the PR description -- Dependencies **MUST** be pinned to a version range (not floating versions) -- Transitive dependency behavior changes **MUST** receive the same scrutiny as direct dependency additions -- Dependency audits **MUST** be conducted quarterly at minimum - -#### Enforcement + -- CI detection of new dependency manifest entries -- Human review +## Dependencies -#### Suggested skill(s) +Adding a dependency is a decision that affects every user of the SDK, so it deserves scrutiny. New dependencies **REQUIRE** explicit justification in the PR description. Pin them to a version range — no floating versions. -- [`sentry-skills:security-review`](https://github.com/getsentry/skills#available-skills) +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 also: [Adding a Dependency](/sdk/getting-started/playbooks/development/adding-a-dependency) for the step-by-step approval and evaluation workflow. - -#### Per-SDK override - - Tooling varies. Approval requirement is universal. +See [Adding a Dependency](/sdk/getting-started/playbooks/development/adding-a-dependency) for the step-by-step evaluation and approval workflow. --- - - -## SDK Size and Performance Budgets - -#### Rule - -Each SDK **MUST** define and track: - -- Package/binary size budget -- Initialization time budget -- Memory overhead budget (where applicable) + -#### Enforcement +## Size and performance budgets -- CI check where feasible (size comparison, benchmarks); advisory initially, path toward blocking +Each SDK **MUST** define and track budgets for: -#### Per-SDK override +- Package/binary size (where applicable) +- Initialization time +- Memory overhead - Budgets and measurement are SDK-specific. The -standard is that budgets exist and are tracked. +The specific numbers are up to each SDK. The standard is that budgets exist, are tracked, and are visible in CI. --- - - -## Security Practices - -#### Rule - -No secrets, credentials, or PII in code or commits. Data handling follows the [data handling spec](/sdk/foundations/data-scrubbing/). Security-sensitive changes **REQUIRE** explicit review from someone with security context. Vulnerability patch SLAs: critical 48h, high 1 week, medium next release. Dependency vulnerability alerts **MUST NOT** be ignored or silently dismissed. - -#### Enforcement - -- CI secret scanning -- Dependency scanning (GitHub Security Advisories / Dependabot alerts) -- Human review - -#### Suggested skill(s) + -- [`sentry-skills:security-review`](https://github.com/getsentry/skills#available-skills) -- [`sentry-skills:find-bugs`](https://github.com/getsentry/skills#available-skills) +## Security -#### Per-SDK override +No secrets, credentials, or PII in code or commits. Data handling follows the [data handling spec](/sdk/foundations/data-scrubbing/). - Vulnerability SLAs can be adjusted. Data handling requirements are universal. +Security-sensitive changes **REQUIRE** review from someone with security context. Dependency vulnerability alerts **MUST NOT** be ignored or silently dismissed. diff --git a/develop-docs/sdk/getting-started/standards/code-submission.mdx b/develop-docs/sdk/getting-started/standards/code-submission.mdx index df476e2a996c7f..1aa418ccf12d22 100644 --- a/develop-docs/sdk/getting-started/standards/code-submission.mdx +++ b/develop-docs/sdk/getting-started/standards/code-submission.mdx @@ -1,11 +1,14 @@ --- title: Code Submission spec_id: sdk/getting-started/standards/code-submission -spec_version: 1.1.0 -spec_status: candidate +spec_version: 1.2.0 +spec_status: stable spec_platforms: - all spec_changelog: + - version: 1.2.0 + date: 2026-03-18 + summary: Remove username prefix from branch naming convention - version: 1.1.0 date: 2026-03-04 summary: Add username prefix and type descriptions to branch naming @@ -19,11 +22,13 @@ sidebar_order: 2 - +These standards cover how code gets into SDK repositories — from branch names and commit messages through to PR descriptions and changelogs. The goal is consistency across SDKs so that contributors and reviewers can move between repos without friction. -## Commit message format + -#### Rule +## Commit messages + +Follow the [conventional commit](https://www.conventionalcommits.org/) format: ``` (): @@ -35,199 +40,87 @@ sidebar_order: 2 **Header** (max 100 chars total): -- **Type**: one of: - - `feat` – New user-facing functionality - - `fix` – Broken behavior now works - - `ref` – Same behavior, different structure - - `perf` – Same behavior, faster - - `style` – CSS, formatting, visual-only - - `docs` – Documentation only - - `test` – Tests only - - `ci` – CI/CD config - - `build` – Build system - - `chore` – Deps, config, version bumps, updating existing tooling — no new logic - - `meta` – Repo metadata changes - - `license` – License changes -- **Subject**: imperative mood, capitalize first letter, no trailing period, max 70 chars - -**Body**: explain what and why, not how. - -**Footer** (one or more of): - -- Issue references: `Fixes SENTRY-1234`, `Fixes GH-1234`, `Refs LINEAR-ABC-123` -- Breaking change notices: `BREAKING CHANGE:` -- AI attribution (see [AI attribution](#ai-attribution)) - -For additional context on commit message best practices, see [Commit Messages](/engineering-practices/commit-messages/). - -#### Enforcement - -- [commitlint](https://github.com/conventional-changelog/commitlint) in CI +- **Type**: one of `feat`, `fix`, `ref`, `perf`, `style`, `docs`, `test`, `ci`, `build`, `chore`, `meta`, `license` +- **Scope**: optional, SDK-specific +- **Subject**: imperative mood ("Add feature" not "Added feature"), capitalize first letter, no trailing period, max 70 chars -#### Suggested skill(s) +The **body** should explain what changed and why — not how. The code shows how. -- [`sentry-skills:commit`](https://github.com/getsentry/skills#available-skills) +The **footer** is for issue references (`Fixes SENTRY-1234`, `Refs LINEAR-ABC-123`), breaking change notices (`BREAKING CHANGE:`), and [AI attribution](#ai-attribution). -#### Per-SDK override - - Scope values are SDK-specific. +See [Commit Messages](/engineering-practices/commit-messages/) for more examples and guidance. --- - + ## Branch naming -#### Rule - -`//` (e.g., `theo/feat/add-client-reports`, `alice/fix/rate-limit-parsing`). - -- **username**: GitHub username (e.g., from `gh api user --jq .login`) -- **type**: same types as [commit messages](#commit-message-format) -- **short-description**: overview of the change, in kebab-case - -#### Enforcement - -- CI advisory (non-blocking) - -#### Suggested skill(s) - -- [`sentry-skills:create-branch`](https://github.com/getsentry/skills#available-skills) - -#### Per-SDK override - - - - - ---- - - - -## PR description quality - -#### Rule - -Every PR **MUST** include a description with: - -- What the PR does -- Why these changes are being made -- Links to relevant issues or tickets (**REQUIRED** except for typo fixes and one-line doc changes) -- Alternative approaches considered (if any) -- Additional context reviewers need - -Test plan sections, checkbox lists, and boilerplate are not allowed. The tests in the diff serve as the test plan. Blank descriptions, template-only descriptions, and AI-generated filler are not acceptable. PR descriptions **MUST NOT** include any customer data or sensitive information. - -#### Enforcement +Use the format `/`: -- PR template -- CI bot check: non-empty, issue reference present, override via `trivial` label +- **type**: same types as commit messages (`feat`, `fix`, `ref`, etc.) +- **short-description**: what the change is about, in kebab-case -#### Suggested skill(s) - -- [`sentry-skills:create-pr`](https://github.com/getsentry/skills#available-skills) - -#### Per-SDK override - - Template wording can vary. Linked-issue and non-empty -requirements are universal. +For example: `feat/add-client-reports` or `fix/rate-limit-parsing`. --- - - -## PR draft mode - -#### Rule - -PRs **MUST** be created as drafts. Mark ready when CI passes and description is complete. - -#### Enforcement - -- Convention -- AGENTS.md - -#### Suggested skill(s) - -- [`sentry-skills:create-pr`](https://github.com/getsentry/skills#available-skills) - -#### Per-SDK override - - - - + ---- +## Pull requests - +### Start as a draft -## Changelog entry +Create PRs as drafts. Mark them ready for review once CI passes and the description is complete. -#### Rule +### Write a useful description -User-facing changes (`feat`, `fix`, `perf`, breaking) **REQUIRE** a changelog entry. Internal changes exempt. Override with `skip-changelog` label. +Every PR needs a description that tells reviewers: -#### Enforcement +- What the PR does and why +- Links to relevant issues or tickets (required except for typo fixes and one-line doc changes) +- Alternative approaches considered, if any +- Additional context reviewers need -- CI check +Skip boilerplate, checkbox lists, and template filler. Don't include customer data or sensitive information. The tests in the diff are the test plan — no need to restate them in the description. -#### Per-SDK override +### Keep PRs focused - Format and location vary. Requirement is universal. +A PR should do one thing well. Don't mix functional changes with unrelated refactors or cleanup. If the work naturally splits into distinct categories, make separate PRs. Smaller, focused PRs are easier to review, reason about, and revert if needed. --- - - -## Keep PRs focused - -#### Rule - -A PR **SHOULD** do one thing — and do it well. Avoid mixing functional changes with unrelated refactors, cleanup, or reorganizations. If the work falls into distinct categories, split it into multiple PRs. Smaller, focused PRs are easier to review, reason about, and revert. - -#### Enforcement - -- Human review + AGENTS.md -- CI advisory for size + -#### Suggested skill(s) +## Changelog entries -- [`sentry-skills:code-review`](https://github.com/getsentry/skills#available-skills) +User-facing changes (`feat`, `fix`, `perf`, breaking changes) need a changelog entry. Internal changes are exempt. If a user-facing change truly doesn't warrant a changelog entry, use the `skip-changelog` label to opt out. -#### Per-SDK override - - Size thresholds are SDK-specific. +The format and location of changelog entries varies by SDK, but the requirement itself is universal. --- - + ## AI attribution -#### Rule - -AI-generated changes get `Co-Authored-By` in commit footer (e.g., `Co-Authored-By: Claude `). This is the only AI involvement indicator. "Generated by AI" or similar markers **MUST NOT** appear anywhere. - -#### Enforcement - -- AGENTS.md instruction +AI models improve over time, and future models will understand the shortcomings of earlier versions. Tagging commits with the model that produced them gives useful signal when debugging — if you know a commit was generated by an older model, you can focus on the kinds of mistakes that model was prone to. -#### Suggested skill(s) +When AI generates or substantially contributes to a commit, add a `Co-Authored-By` line in the commit footer: -- [`sentry-skills:commit`](https://github.com/getsentry/skills#available-skills) - adds attribution automatically. -- [`sentry-skills:agents-md`](https://github.com/getsentry/skills#available-skills) - ensures AGENTS.md includes the convention. - -#### Per-SDK override +``` +Co-Authored-By: Claude +``` - +This is the only indicator of AI involvement. Don't add "Generated by AI", "Written with Claude", or similar markers anywhere else in the commit. diff --git a/develop-docs/sdk/getting-started/standards/coordination-maintenance.mdx b/develop-docs/sdk/getting-started/standards/coordination-maintenance.mdx index d22a203f61ffbd..2eba9dc76f9dbe 100644 --- a/develop-docs/sdk/getting-started/standards/coordination-maintenance.mdx +++ b/develop-docs/sdk/getting-started/standards/coordination-maintenance.mdx @@ -2,7 +2,7 @@ title: Coordination and Maintenance spec_id: sdk/getting-started/standards/coordination-maintenance spec_version: 1.0.0 -spec_status: candidate +spec_status: stable spec_platforms: - all spec_changelog: @@ -16,157 +16,92 @@ sidebar_order: 7 - +These standards cover how SDK teams coordinate across repositories, respond to users, and keep things running after code ships. The common thread: don't let things fall through the cracks. -## Cross-SDK Coordination Protocol + -#### Rule +## Cross-SDK changes -Multi-SDK changes follow: +When a change affects multiple SDKs, follow this sequence: -1. Proposal (RFC/issue) -2. Cross-SDK Review (1 week minimum) -3. Sequencing Decision -4. Tracking as Linear Initiative -5. Coordinated communication +1. **Proposal** — RFC or issue describing the change +2. **Cross-SDK review** — at least 1 week for feedback +3. **Sequencing decision** — agree on rollout order +4. **Tracking** — set up as a Linear initiative +5. **Communication** — coordinate announcements -#### Enforcement - -- Human process -- Templates for Proposals - -See also: [Aligning Cross-SDK Changes](/sdk/getting-started/playbooks/coordination/aligning-cross-sdk-changes) — step-by-step playbook for coordinating a change across multiple SDKs. [Managing Linear Projects](/sdk/getting-started/playbooks/coordination/managing-linear-projects) — setting up and running each per-SDK project. - -#### Per-SDK override - - Timing varies. Process is universal. +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. --- - + -## Triaging SLA +## Issue triage -#### Rule +All user-reported issues **MUST** get a substantive first response within 2 business days. "Substantive" means acknowledging the problem, asking for reproduction steps, confirming it as a known issue, or explaining the resolution — not just a thumbs-up emoji. -All user-reported issues **MUST** receive substantive first response within 2 business days. -Substantive means acknowledging the problem, asking for reproduction steps, confirming it as a known issue, or explaining the resolution. +Issues on GitHub and Linear are automatically labeled to track where action is needed: -#### Enforcement +- **`Waiting for: Product Owner`** — the maintainer **MUST** respond within 2 business days. The SLA restarts each time this label becomes active. +- **`Waiting for: Community`** — the maintainer has responded and is waiting for a reply or reproduction from the reporter. No SLA while this label is active. -- Automated labeling -- Dashboard tracking +Labels are managed automatically and reset on state transitions. Both are removed when the issue is closed. -See also: [Triaging SDK Issues](/sdk/getting-started/playbooks/coordination/triaging) for the full triage workflow. - -#### Per-SDK override - - Stricter SLAs allowed. Baseline is universal. +See the [Triaging playbook](/sdk/getting-started/playbooks/coordination/triaging) for the full workflow. --- - - -## Platform/language version support policy + -#### Rule +## Platform and language version support -- Supported versions documented in README and docs -- Dropping support is a breaking change ([Breaking change process](/sdk/getting-started/standards/api-architecture#breaking-change-process)) following the deprecation lifecycle ([Deprecation lifecycle](/sdk/getting-started/standards/api-architecture#deprecation-lifecycle)) -- Requires evidence: usage data, upstream EOL, maintenance burden -- Announced at least one minor release before the major that drops +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. -#### Enforcement - -- CI matrix tests supported versions -- Human process for changes - -#### Per-SDK override - - Each SDK owns its matrix. Process for changing it is -universal. +Each SDK owns its version matrix. CI should test all supported versions. --- - + -## Post-release monitoring +## Post-release monitoring and regression handling -#### Rule +### Monitoring -After each release: +After each release, watch for problems: - Monitor SDK crash detection -- Verify dogfooding picks up new version -- Watch issue tracker for 48h -- Patch critical regressions within 48h - -#### Enforcement - -- Automated alerting -- Human monitoring - -#### Per-SDK override - - Tooling varies. Commitment and SLA are universal. +- Verify dogfooding picks up the new version +- Watch the issue tracker for 48 hours +- Patch critical regressions within 48 hours - - ---- - - - -## Rollback procedures - -#### Rule - -Every SDK **MUST** have documented rollback: +### Handling regressions -- How to yank/unpublish -- How to cut revert release -- Who has permissions (plus backup) at least two people can publish/yank per SDK -- Communication template -- Annual drill **RECOMMENDED** +Every SDK **MUST** have a documented regression handling plan covering: -#### Enforcement +- How to yank or unpublish a release +- How to cut a revert release +- Who has permissions — at least two people per SDK must be able to publish and yank +- A communication template for notifying users -- Documentation exists -- Permissions verified - -See also: [Setting up release infrastructure playbook](/sdk/getting-started/playbooks/setup/setting-up-release-infrastructure) for initial release setup with appropriate permissions. - -#### Per-SDK override - - Per-registry mechanics. Requirement to have a plan is universal. +An annual regression handling drill is recommended. See [Setting up release infrastructure](/sdk/getting-started/playbooks/setup/setting-up-release-infrastructure) for initial setup. --- - - -## Decision Documentation - -#### Rule - -- **Before a decision**: reference or create a Linear or GitHub issue to anchor the discussion. -- **If a meeting occurs**: notes or a recording **MUST** be enabled; key decisions **MUST** be summarized and linked to the issue. -- **After a decision**: update the issue immediately; link supporting docs; assign action items with owners. -- Slack **MAY** be used for coordination. Outcomes **MUST** be moved to the system of record (Linear, GitHub, Develop Docs) before the thread is considered closed. - -#### Enforcement + -- Human process +## Documenting decisions -#### Per-SDK override +Decisions should be traceable. Before making one, reference or create a Linear or GitHub issue to anchor the discussion. If a meeting happens, enable notes or recording — key decisions **MUST** be summarized and linked to the issue afterward. - Applies universally. +Slack is fine for coordination, but outcomes **MUST** be moved to the system of record (Linear, GitHub, or Develop Docs) before the thread is considered closed. Update the issue immediately, link supporting docs, and assign action items with owners. diff --git a/develop-docs/sdk/getting-started/standards/planning-scoping.mdx b/develop-docs/sdk/getting-started/standards/planning-scoping.mdx index f376aeafb03fc0..4d6b633ea72381 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#test-requirements-by-change-type) 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: diff --git a/develop-docs/sdk/getting-started/standards/release-versioning.mdx b/develop-docs/sdk/getting-started/standards/release-versioning.mdx index 64d57eb98dc740..e410f5e613fe48 100644 --- a/develop-docs/sdk/getting-started/standards/release-versioning.mdx +++ b/develop-docs/sdk/getting-started/standards/release-versioning.mdx @@ -2,7 +2,7 @@ title: Release and Versioning spec_id: sdk/getting-started/standards/release-versioning spec_version: 1.0.0 -spec_status: candidate +spec_status: stable spec_platforms: - all spec_changelog: @@ -16,11 +16,11 @@ sidebar_order: 99 - +These standards define how SDK versions are numbered and how releases are built and published. All SDKs use semantic versioning and shared release tooling to keep the process consistent. -## Version Format + -#### Rule +## Versioning All SDK versions **MUST** follow [semantic versioning (SemVer)](https://semver.org/): @@ -28,134 +28,39 @@ All SDK versions **MUST** follow [semantic versioning (SemVer)](https://semver.o ..(-)?(-)? ``` -Major, minor, and patch are **REQUIRED**. Pre-release and build identifiers are **OPTIONAL** and can be combined. +### Pre-release identifiers -#### Enforcement +Pre-release identifiers **MUST** be one of: `preview`, `pre`, `rc`, `dev`, `alpha`, `beta`, `unstable`, `a`, `b`. Arbitrary strings are not accepted — anything unrecognized (like `-foo` or `-canary.0`) will be treated as a stable release by the release tooling. -- [Craft](https://github.com/getsentry/craft) validates version format at release time. +Pre-releases don't receive a `latest` tag in package registries and are not inserted into the internal release-registry used by Sentry product, docs, and tooling. -#### Per-SDK override +Valid examples: `1.0.0-preview`, `1.0.0-alpha.0`, `1.0.0-beta.1`, `1.0.0-rc.20` - Format is universal. Language-specific conventions -around SemVer (if applicable) are allowed. +**Python note:** Python post-releases use a numeric-only suffix (e.g., `1.0.0-1`). Since this doesn't match any pre-release identifier, craft treats them as stable releases. - - ---- - - - -## Pre-Release Identifiers - -#### Rule - -Pre-release identifiers **MUST** be one of: `preview`, `pre`, `rc`, `dev`, `alpha`, `beta`, `unstable`, `a`, `b`. Arbitrary strings are not accepted. - -Pre-releases: - -- Do not receive a `latest` tag in package registries -- Are not inserted into the internal release-registry (used by Sentry product, docs, and tooling) - -Valid examples: - -``` -1.0.0-preview -1.0.0-alpha.0 -1.0.0-beta.1 -1.0.0-rc.20 -``` - -Invalid (treated as stable): - -``` -1.0.0-foo -1.0.0-canary.0 -``` +### Build identifiers -**Python post-releases:** Python has the concept of post-releases indicated by a numeric-only suffix (e.g., `1.0.0-1`). Since this doesn't match any valid pre-release identifier, craft treats post-releases as stable releases. - -#### Enforcement - -- Craft rejects unrecognized identifiers or treats them as stable releases. - -#### Per-SDK override - - +Build identifiers are optional and used for platform or architecture variants (e.g., `1.0.0+x86_64`). When combined with pre-release identifiers, the pre-release comes first: `1.0.0-rc.1+x86_64`. --- - - -## Build Identifiers - -#### Rule - -Build identifiers **MAY** be appended for platform or architecture variants. When combined with pre-release identifiers, the pre-release **MUST** come first. - -Valid examples: - -``` -1.0.0+x86_64 -1.0.0-rc.1+x86_64 -``` - -Invalid: - -``` -1.0.0+rc.1+x86_64 -1.0.0+x86_64-beta.0 -``` - -#### Enforcement - -- Craft validates format at release time. + -#### Per-SDK override +## Release tooling - Usage depends on whether the SDK publishes -platform-specific artifacts. - - - ---- - - - -## Release Tooling - -#### Rule - -SDKs **MUST** use [craft](https://github.com/getsentry/craft) for release preparation and [publish](https://github.com/getsentry/publish) for release approval. Every SDK repo **MUST** have: +SDKs **MUST** use [craft](https://github.com/getsentry/craft) for release preparation and [publish](https://github.com/getsentry/publish) for release approval. Every SDK repo needs: - `.craft.yml` — release configuration - `scripts/bump-version.sh` — version bump script invoked by craft - `.github/workflows/release.yml` — GitHub Actions workflow to trigger releases -See the [setting up release infrastructure](/sdk/getting-started/playbooks/setup/setting-up-release-infrastructure) playbook for setup instructions. - -#### Enforcement - -- Craft enforces configuration at release time. -- Publish requires approval label before artifacts are published. - -#### Per-SDK override - - Craft targets and bump-version logic are -SDK-specific. Toolchain is universal. - - - ---- - - +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 +### Merge target -#### Rule - -By default, releases are merged to the repository's default branch (usually `main`). To override this, pass the `merge_target` input in the release workflow: +By default, releases merge to the repository's default branch (usually `main`). To override this, pass the `merge_target` input in the release workflow: ```yaml - name: Prepare release @@ -169,27 +74,9 @@ By default, releases are merged to the repository's default branch (usually `mai Add a corresponding `merge_target` input to the workflow's `workflow_dispatch.inputs` block. The same input is available in the [reusable workflow](https://craft.sentry.dev/github-actions/#option-1-reusable-workflow-recommended). -#### Enforcement - -- Craft handles branch targeting at release time. - -#### Per-SDK override - - Depends on branching strategy. - - - ---- - - - -## Multiple Craft Configs Per Repository - -#### Rule - -When a repository maintains multiple major versions (e.g., v7 and v8) with diverging publishing targets, it can opt into using the `.craft.yml` from the merge target branch instead of the default branch. +### Multiple craft configs -**Release preparation:** Add `craft_config_from_merge_target: true` when calling `getsentry/craft` in the release workflow: +When a repository maintains multiple major versions (e.g., v7 and v8) with diverging publishing targets, it can use the `.craft.yml` from the merge target branch instead of the default branch. Add `craft_config_from_merge_target: true` to the craft step: ```yaml - name: Prepare release @@ -198,9 +85,7 @@ When a repository maintains multiple major versions (e.g., v7 and v8) with diver craft_config_from_merge_target: true ``` -This input is also available in the [reusable workflow](https://craft.sentry.dev/github-actions/#option-1-reusable-workflow-recommended). - -**Publish configuration:** Register the branch in the `publish.yml` workflow in `getsentry/publish`: +For the publish side, register the branch in the `publish.yml` workflow in `getsentry/publish`: ```yaml - name: Set target repo checkout branch @@ -208,16 +93,9 @@ This input is also available in the [reusable workflow](https://craft.sentry.dev fromJSON(steps.inputs.outputs.result).repo == 'sentry-javascript' && fromJSON(steps.inputs.outputs.result).merge_target == 'v7' ``` -The registered branches **MUST** be protected in the target repository — disable direct pushing and require PR approvals before merging. - -#### Enforcement - -- Craft validates config from the specified branch. -- Publish workflow enforces branch protection requirement. - -#### Per-SDK override +The registered branches **MUST** be protected — disable direct pushing and require PR approvals before merging. - Only needed for repos maintaining multiple major versions. +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 ce522380330af1..0b4f6754122c9a 100644 --- a/develop-docs/sdk/getting-started/standards/repository-docs.mdx +++ b/develop-docs/sdk/getting-started/standards/repository-docs.mdx @@ -2,7 +2,7 @@ title: Repository and Documentation spec_id: sdk/getting-started/standards/repository-docs spec_version: 1.1.0 -spec_status: candidate +spec_status: stable spec_platforms: - all spec_changelog: @@ -19,45 +19,26 @@ sidebar_order: 5 - +These standards define what every SDK repository should contain beyond the code itself — the files that help humans and AI tools understand, contribute to, and maintain the project. -## AGENTS.md + -#### Rule +## Required repository files -Every SDK repo **MUST** have `AGENTS.md` covering: +### AGENTS.md + +Every SDK repo **MUST** have an `AGENTS.md` covering: - Architecture overview - Testing conventions - Build instructions - Contribution expectations -- Commit attribution convention ([AI attribution](/sdk/getting-started/standards/code-submission#ai-attribution)) -- SDK-specific standard overrides - updated in same PR as architectural changes - -#### Enforcement - -- CI file existence check -- Human review for staleness - -#### Suggested skill(s) - -- [`sentry-skills:agents-md`](https://github.com/getsentry/skills#available-skills) - -#### Per-SDK override - - Content is SDK-specific. Requirement is universal. +- [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 -## CONTRIBUTING.md - -#### Rule - -Every SDK repo **MUST** have `CONTRIBUTING.md` covering: +Every SDK repo **MUST** have a `CONTRIBUTING.md` covering: - Setup instructions - Development workflow @@ -65,120 +46,42 @@ Every SDK repo **MUST** have `CONTRIBUTING.md` covering: - Discussion-first policy - AI tools section -#### Enforcement - -- CI file existence check -- AGENTS.md for update checking -- Content quality is human-reviewed +### PR template -#### Per-SDK override - - Setup/workflow are SDK-specific. Quality bar and AI -sections use shared template. +Every SDK repo **MUST** have a GitHub PR template with description structure guidance and a linked-issue reminder. Keep it minimal — provide guidance rather than enforcing rigid structure with mandatory sections. --- - - -## PR Template - -#### Rule - -Every SDK repo **MUST** have a GitHub PR template with description structure guidance and linked-issue reminder. The template **SHOULD** be minimal, providing guidance rather than enforcing rigid structure with mandatory sections. + -#### Enforcement +## Documentation ships with code -- File existence +User-facing changes need corresponding docs: -#### Suggested skill(s) +- **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)) +- **New config option**: docs entry -- [`sentry-skills:create-pr`](https://github.com/getsentry/skills#available-skills) - -#### Per-SDK override - - Wording varies. Linked-issue prompt is universal. +The SDK PR should link to the docs PR. Neither merges without the other being at least approved. --- - - -## Documentation-with-Code - -#### Rule - -User-facing changes **REQUIRE** corresponding docs: - -- **New feature**: Docs PR to [sentry-docs](https://github.com/getsentry/sentry-docs/) -- **Behavior change**: Docs update, -- **Deprecation** Migration guide ([Deprecation lifecycle](/sdk/getting-started/standards/api-architecture#deprecation-lifecycle)) -- **New config option**: Docs entry - -SDK PR links to docs PR. Neither merges without the other being at least approved. - -#### Enforcement - -- AGENTS.md instruction -- Human review - -#### Per-SDK override - - - - - ---- - - - -## AI Context File Maintenance - -#### Rule - -AI context files (AGENTS.md, `.cursorrules`, `.github/copilot-instructions.md`, CLAUDE.md) **MUST** be maintained as living documentation: updated with architectural changes, reviewed quarterly, periodically tested by having an AI tool attempt a contribution. - -#### Enforcement - -- Human review -- Quarterly review reminder - -#### Suggested skill(s) - -- [`sentry-skills:agents-md`](https://github.com/getsentry/skills#available-skills) - -#### Per-SDK override - - Which files exist varies. AGENTS.md is required ([AGENTS.md required](#agentsmd)); others recommended. - - - ---- - - - -## AI Skills - -#### Rule - -SDK repos **SHOULD** have dotagents configured with skills from [`getsentry/skills`](https://github.com/getsentry/skills) and [`getsentry/sdk-skills`](https://github.com/getsentry/sdk-skills). Commit `agents.toml` and `agents.lock` so every engineer on the team gets the same skills automatically. - -Rules files (e.g. `.claude/rules/`, `.cursor/rules/`) **SHOULD** be used for fixed workflow conventions that apply to a specific task or directory. - -#### Enforcement + -- `agents.toml` / `agents.lock` presence in repo -- Human review +## AI context files -#### Suggested skill(s) +AI context files — `AGENTS.md`, `.cursorrules`, `.github/copilot-instructions.md`, `CLAUDE.md` — are living documentation. Keep them up to date with architectural changes, review them quarterly, and periodically test them by having an AI tool attempt a contribution. -- [`sentry-skills:agents-md`](https://github.com/getsentry/skills#available-skills) +`AGENTS.md` is [required](#repo-files). The others are recommended. -#### Per-SDK override +SDK repos **SHOULD** also have [dotagents](https://github.com/getsentry/dotagents) configured with skills from [`getsentry/skills`](https://github.com/getsentry/skills) and [`getsentry/sdk-skills`](https://github.com/getsentry/sdk-skills). Commit `agents.toml` and `agents.lock` so every engineer on the team gets the same skills automatically. See the [dotagents documentation](https://docs.sentry.io/ai/dotagents/) for setup instructions. - Which skills are active and which rules files exist are SDK-specific. +Rules files (e.g., `.claude/rules/`, `.cursor/rules/`) **SHOULD** be used for fixed workflow conventions that apply to a specific task or directory. diff --git a/develop-docs/sdk/getting-started/standards/review-ci.mdx b/develop-docs/sdk/getting-started/standards/review-ci.mdx index a89c35f64929f0..4c76ce2b7cb29c 100644 --- a/develop-docs/sdk/getting-started/standards/review-ci.mdx +++ b/develop-docs/sdk/getting-started/standards/review-ci.mdx @@ -2,7 +2,7 @@ title: Review and CI spec_id: sdk/getting-started/standards/review-ci spec_version: 1.1.0 -spec_status: candidate +spec_status: stable spec_platforms: - all spec_changelog: @@ -19,181 +19,89 @@ sidebar_order: 4 - +These standards cover how code gets reviewed and what CI must check before anything merges or ships. The goal: catch problems early, keep reviews useful, and make sure releases are safe. -## Required Reviewers + -#### Rule +## Code review -Every PR **REQUIRES** at least one approving review. -@sdk-seniors review **REQUIRED** for: +### Who needs to review -- Public API ([Public API change approval gate](/sdk/getting-started/standards/api-architecture#public-api-change-approval-gate)) -- New dependencies ([Dependency management](/sdk/getting-started/standards/code-quality#dependency-management)) -- Security-sensitive code ([Security practices](/sdk/getting-started/standards/code-quality#security-practices)) -- Schema changes -- Frameworks/architectural shifts. - External contributor PRs **REQUIRE** review from someone with area context. - -#### Enforcement - -- GitHub branch protection -- CODEOWNERS file - -#### Suggested skill(s) - -- [`sentry-skills:code-review`](https://github.com/getsentry/skills#available-skills) - -#### Per-SDK override - - CODEOWNERS and reviewer count are team-specific. - - - ---- - - - -## Review SLAs - -#### Rule - -Internal PRs: first review within 1 business day. -External PRs: first response within 2 business days. - -"First review" means substantive feedback, not just a reaction. - -If an area has only a single reviewer or if that reviewer lacks capacity, the reviewer **MUST** proactively find coverage (another reviewer or AI assist). The PR author **SHOULD** also help identify an appropriate reviewer to avoid blocking the PR. - -#### Enforcement - -- Dashboard tracking -- Periodic reporting - -#### Per-SDK override - - Teams can set stricter SLAs. Baseline is universal. - - - ---- - - - -## Review Feedback Conventions +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): -#### Rule - -LOGAF scale: +- [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 -- `h:` (high) — must fix (bugs, security, breakage, data loss) -- `m:` (medium) — should fix (design, missing tests, clarity) -- `l:` (low) — optional nit (style, minor suggestions) +PRs from external contributors need review from someone with context on the affected area. -Comments without a prefix are treated as `m:` (medium). A PR **MUST NOT** be merged if it has any unresolved `h:` comments. +### Turnaround time -#### Enforcement +Internal PRs should get a first substantive review within 1 business day. External PRs should get a first response within 2 business days. "First review" means real feedback, not just a reaction. -- Convention +If you're the sole reviewer for an area and don't have capacity, proactively find coverage — another reviewer or AI assist. PR authors should also help identify an appropriate reviewer to avoid blocking. -#### Suggested skill(s) +### Feedback conventions -- [`sentry-skills:iterate-pr`](https://github.com/getsentry/skills#available-skills) — triages by LOGAF level. -- [`sentry-skills:code-review`](https://github.com/getsentry/skills#available-skills) — uses LOGAF in feedback. +Use the LOGAF scale to signal the weight of your feedback: -#### Per-SDK override +- **`h:`** (high) — must fix: bugs, security issues, breakage, data loss +- **`m:`** (medium) — should fix: design, missing tests, clarity +- **`l:`** (low) — optional nit: style, minor suggestions - +Comments without a prefix are treated as medium. A PR **MUST NOT** merge with unresolved `h:` comments. --- - + -## Required CI Checks Baseline +## CI checks -#### Rule - -Every SDK repo **MUST** have as required status checks: +Every SDK repo **MUST** have these as required status checks: 1. Build -2. Lint ([Linting and formatting in CI](/sdk/getting-started/standards/code-quality#linting-and-formatting-in-ci)) -3. Type check where applicable ([Type checking in CI](/sdk/getting-started/standards/code-quality#type-checking-in-ci)) +2. Lint +3. Type check (where applicable) 4. Tests -5. Commit message structure and content ([Commit message structure and content](/sdk/getting-started/standards/code-submission#commit-message-structure-and-content)). - -Optional/**RECOMMENDED**: +5. Secret Scanning -- Size/Performance Check ([SDK size and performance budgets](/sdk/getting-started/standards/code-quality#sdk-size-and-performance-budgets)) -- API Snapshot ([Public API change approval gate](/sdk/getting-started/standards/api-architecture#public-api-change-approval-gate)) -- Changelog Check ([Changelog entry](/sdk/getting-started/standards/code-submission#changelog-entry)) -- Secret Scanning ([Security practices](/sdk/getting-started/standards/code-quality#security-practices)). +These are also recommended but not yet required everywhere: -#### Enforcement +- Commit message validation +- Size and performance checks +- API snapshot diffs +- Changelog validation -- GitHub branch protection + -#### Suggested skill(s) +--- -- [`sentry-skills:claude-settings-audit`](https://github.com/getsentry/skills#available-skills) + -#### Per-SDK override +## Warden - Additional checks per SDK. Baseline is universal. +SDK repos **SHOULD** have [Warden](https://warden.sentry.dev/) configured in CI via the Warden GitHub Action. Warden runs AI-powered skills against PR diffs to enforce SDK-specific conventions that static linters can't express. Which skills are active varies by SDK. --- - + -## Release Gating Criteria - -#### Rule +## Release gating A release **MUST NOT** ship if: - Any required CI check fails -- Any `h:` comment remains unresolved on merged PRs since last release +- Any `h:` review comment remains unresolved on merged PRs since the last release - The changelog is empty for user-facing changes - Any known regression remains unresolved -#### Enforcement - -- Release tooling checks -- Human judgment for regressions - -See also: [Setting up release infrastructure playbook](/sdk/getting-started/playbooks/setup/setting-up-release-infrastructure) for initial release setup. - -#### Per-SDK override - - Additional gates per SDK possible (e.g., beta/rc periods). - - - ---- - - - -## Warden - -#### Rule - -SDK repos **SHOULD** have [Warden](https://warden.sentry.dev/) configured in CI via the Warden GitHub Action. Warden runs AI-powered skills against PR diffs to enforce SDK-specific conventions that static linters cannot express. - -#### Enforcement - -- GitHub Actions (Warden GitHub Action) -- Human review for follow-up on findings - -#### Suggested skill(s) - -- [`sentry-skills:warden-lint-judge`](https://github.com/getsentry/skills#available-skills) — converts findings into permanent lint rules. - -#### Per-SDK override - - Which Warden skills are active varies per SDK. +See [Setting up release infrastructure](/sdk/getting-started/playbooks/setup/setting-up-release-infrastructure) for initial release setup. diff --git a/develop-docs/sdk/getting-started/templates/contributing-md-template.mdx b/develop-docs/sdk/getting-started/templates/contributing-md-template.mdx deleted file mode 100644 index 1294c15085c8b9..00000000000000 --- a/develop-docs/sdk/getting-started/templates/contributing-md-template.mdx +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: CONTRIBUTING.md -sidebar_order: 20 ---- - - - -TBD - - diff --git a/develop-docs/sdk/getting-started/templates/contributing-md.mdx b/develop-docs/sdk/getting-started/templates/contributing-md.mdx new file mode 100644 index 00000000000000..bcb6a48f964e72 --- /dev/null +++ b/develop-docs/sdk/getting-started/templates/contributing-md.mdx @@ -0,0 +1,101 @@ +--- +title: CONTRIBUTING.md +sidebar_order: 20 +description: Boilerplate CONTRIBUTING.md template for Sentry SDK repositories. Tells contributors how to set up, develop, test, and submit changes. +--- + +`CONTRIBUTING.md` is a Markdown file at the root of your repository that orients both external contributors and Sentry engineers before they open their first PR. GitHub surfaces it automatically on the Issues and Pull Requests tabs. + +**Keep it short.** Detailed process lives on [develop.sentry.dev](https://develop.sentry.dev/sdk/) — link there, don't duplicate it. Target 100–200 lines. + +## What Belongs in CONTRIBUTING.md + +- **Welcome + issue-first policy** — ask contributors to open an issue before a non-trivial PR. Link to the [handling external contributor PRs playbook](https://develop.sentry.dev/sdk/getting-started/playbooks/development/handling-external-contributor-pr/). +- **Getting started** — environment setup steps specific to this repo. Refer readers to the README for general project overview; CONTRIBUTING.md covers what's extra. +- **Development workflow** — commit format, branch naming, and changelog requirement. Link to the [code submission standard](https://develop.sentry.dev/sdk/getting-started/standards/code-submission/) rather than restating it. +- **Testing** — exact commands to run the test suite, a subset, and lint. Include platform-specific notes (tox environments, Gradle tasks, Xcode schemes, etc.). +- **Submitting a PR** — open as draft until ready; fill out the PR template. Link to the [opening a PR playbook](https://develop.sentry.dev/sdk/getting-started/playbooks/development/opening-a-pr/). +- **Code review** — LOGAF scale (`h:`/`m:`/`l:`), expected SLAs (1 business day internal / 2 business days external). Link to the [reviewing a PR playbook](https://develop.sentry.dev/sdk/getting-started/playbooks/development/reviewing-a-pr/). +- **AI-assisted contributions** — `Co-Authored-By` attribution required per the [AI attribution standard](https://develop.sentry.dev/sdk/getting-started/standards/code-submission/#ai-attribution). Point maintainers to the [reviewing AI-generated code playbook](https://develop.sentry.dev/sdk/getting-started/playbooks/development/reviewing-ai-generated-code/). +- **Getting help** — Discord server link, `#sdk-[language]` support channel. +- **Code of conduct** — link to [Sentry's Code of Conduct](https://open.sentry.io/code-of-conduct/). + +**Do NOT include:** + +- Full environment setup (belongs in README) +- Release / publish process (internal; link to sdk-lifecycle playbooks instead) +- Architecture or API design decisions (belongs in AGENTS.md) +- Verbatim copies of content already on develop.sentry.dev + +## Good Examples in SDK Repositories + +Check if the repository already has one before starting from scratch. The following repos have well-structured examples worth referencing: + +- [`getsentry/sentry-python`](https://github.com/getsentry/sentry-python/blob/master/CONTRIBUTING.md) — clear integration development principles; good separation between user and contributor setup +- [`getsentry/sentry-javascript`](https://github.com/getsentry/sentry-javascript/blob/master/CONTRIBUTING.md) — Volta pin for Node/yarn, concise monorepo workflow, explicit PR draft rule +- [`getsentry/sentry-go`](https://github.com/getsentry/sentry-go/blob/master/CONTRIBUTING.md) — explicit LOGAF scale usage, craft release-notes requirement called out +- [`getsentry/sentry-cocoa`](https://github.com/getsentry/sentry-cocoa/blob/main/CONTRIBUTING.md) — LOGAF examples with descriptions, copyright header rule +- [`getsentry/sentry-java`](https://github.com/getsentry/sentry-java/blob/main/CONTRIBUTING.md) — API compatibility validation workflow, clear step-by-step setup + +## Template + +Use the [`sentry-sdk-skills:contributing-md`](https://github.com/getsentry/sdk-skills/tree/main/plugins/sentry-sdk-skills/skills/contributing-md) skill to create or update your `CONTRIBUTING.md` — it detects commands, CI config, and ecosystem from the repo, fills in the placeholders below, and preserves any SDK-specific sections already present. + +Remove sections that don't apply and replace all `[placeholder]` values with real content. + + + +# Contributing to \[SDK name\] + +We welcome contributions! Before submitting a non-trivial change, please open an issue +so we can align on scope and approach. Want to understand how we work? Our +[SDK development docs](https://develop.sentry.dev/sdk/) cover our engineering process +in detail. + +## Getting Started + +1. Fork the repository and clone your fork. +2. \[SDK-specific setup steps — e.g. install language runtime, create virtualenv, etc.\] +3. Install dependencies: `[install command]` + +## Development Workflow + +See our [principles](https://develop.sentry.dev/sdk/getting-started/principles/) and [standards](https://develop.sentry.dev/sdk/getting-started/standards/) for SDK development. + +## Testing + +Run the full test suite: `[full test command]` + +Run a single test / test file: `[single test command]` + +Lint and format: `[lint command]` / `[format command]` + +\[Optional: platform-specific notes, e.g. tox environments, Gradle tasks, Xcode schemes, +required env vars, or native dependency setup for React Native (sentry-cocoa, sentry-java).\] + +## Submitting a Pull Request + +Open as a **draft**, fill in the PR description, and ensure CI passes before marking ready. + +## Code Review + +We use the **LOGAF scale** to signal comment weight: + +- `h:` (high) — must fix: bugs, security, breakage +- `m:` (medium) — should fix: design, missing tests, clarity +- `l:` (low) — optional nit: style, minor suggestions + + +## AI-Assisted Contributions + +AI-generated code is welcome — include a `Co-Authored-By` trailer per the [AI attribution standard](https://develop.sentry.dev/sdk/getting-started/standards/code-submission/#ai-attribution). + +## Getting Help + +Have a question? Join the [Sentry Discord](https://discord.com/invite/sentry) in **#sdk-\[language\]** or open a GitHub issue. + +## Code of Conduct + +This project follows the [Sentry Code of Conduct](https://open.sentry.io/code-of-conduct/). + + diff --git a/develop-docs/sdk/telemetry/attachments.mdx b/develop-docs/sdk/telemetry/attachments.mdx index ea79d38e580696..e6d13d4be7c237 100644 --- a/develop-docs/sdk/telemetry/attachments.mdx +++ b/develop-docs/sdk/telemetry/attachments.mdx @@ -255,7 +255,7 @@ SDKs **SHOULD** send placeholders in the same envelope as the event the file is | `attachment_length` | Integer | **REQUIRED** | Size of the referenced attachment in bytes. | | `filename` | String | **REQUIRED** | The name of the uploaded file without a path component. | -The item header **MAY** also contain `attachment_type` and the original file's `content_type` as an additional field (see [Standard Attachment Item](#standard-attachment-item)). +The item header **MUST** also contain the original file's `attachment_type` if it was set. The item payload **MUST** contain the original file's `content_type` as a field in the JSON object (see [Standard Attachment Item](#standard-attachment-item)). **Item payload:** diff --git a/develop-docs/sdk/telemetry/traces/modules/ai-agents.mdx b/develop-docs/sdk/telemetry/traces/modules/ai-agents.mdx index bcfdbc985ea49c..000d1f4d04056b 100644 --- a/develop-docs/sdk/telemetry/traces/modules/ai-agents.mdx +++ b/develop-docs/sdk/telemetry/traces/modules/ai-agents.mdx @@ -11,7 +11,7 @@ For your AI agents data to show up in the Sentry [AI Agents Insights](https://se We try to follow [v1.36.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.36.0/docs/gen-ai/README.md) of the [OpenTelemetry Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/) for Generative AI as close as possible. Being 100% compatible is not yet possible, because OpenTelemetry has "Span Events" which Sentry does not support. The input from/output to an AI model is stored in span events in OpenTelemetry. Since this is not possible in Sentry, we add this data onto span attributes as a list. -The [Sentry Conventions](https://getsentry.github.io/sentry-conventions/generated/attributes/) have all the detailed specifications for `"gen_ai.*"` span attributes. +The [Sentry Conventions](https://github.com/getsentry/sentry-conventions/) have all the detailed specifications for `"gen_ai.*"` span attributes. Sentry Conventions is the single source of truth. diff --git a/docs/ai/agent-skills.mdx b/docs/ai/agent-skills.mdx index 2dda3d05cb2344..16b385f9248d5c 100644 --- a/docs/ai/agent-skills.mdx +++ b/docs/ai/agent-skills.mdx @@ -16,7 +16,7 @@ keywords: - OpenCode --- -Agent skills are instruction sets that teach AI coding assistants how to perform specific tasks. Sentry's official agent skills give your AI assistant the knowledge to set up and configure Sentry in your projects with no manual configuration required. Use [workflow skills](/ai/agent-skills/#workflow-skills) to debug and fix issues in your projects. +Agent skills are instruction sets that teach AI coding assistants how to perform specific tasks. Sentry's official agent skills give your AI assistant the knowledge to set up and configure Sentry in your projects with no manual configuration required. Use [workflow skills](https://skills.sh/getsentry/sentry-for-ai/sentry-workflow) to debug and fix issues in your projects. diff --git a/docs/ai/index.mdx b/docs/ai/index.mdx index f8c3291a43e931..087484ca85dbf9 100644 --- a/docs/ai/index.mdx +++ b/docs/ai/index.mdx @@ -2,7 +2,6 @@ title: Sentry for AI sidebar_order: 1 description: "Connect Sentry to your AI coding assistants and workflows. Install agent skills, use the MCP server, or add monitoring to your AI applications." -new: true keywords: - AI - artificial intelligence @@ -56,25 +55,25 @@ keywords: href="/ai/sentry-cli/" iconSrc="/ai/img/IconTerminal.svg" title="Sentry CLI" - description="A natural-language CLI for developers and AI agents. List issues, get root cause analysis from Seer, and manage your Sentry projects from the terminal." + description="A natural-language CLI for developers and AI agents. List issues, use Seer's Autofix, and manage your Sentry projects from the terminal." className="w-full md:w-[calc(50%-12px)]" /> ## AI In Sentry -Looking for Sentry's AI-powered debugging features? Sentry uses AI to help you debug faster with automated root cause analysis, fix suggestions, and AI-powered PR reviews. [Learn more about AI In Sentry](/product/ai-in-sentry/). +Looking for Sentry's AI-powered debugging features? Sentry uses AI to help you debug faster with Autofix, fix suggestions, and AI-powered PR reviews. [Learn more about AI In Sentry](/product/ai-in-sentry/). - Monitor past conversations with your AI assistants. Replay every message and tool call to understand what happened and where things went wrong. diff --git a/docs/ai/sentry-cli.mdx b/docs/ai/sentry-cli.mdx index ab14408969a521..24d2d7e13e3f25 100644 --- a/docs/ai/sentry-cli.mdx +++ b/docs/ai/sentry-cli.mdx @@ -2,7 +2,7 @@ title: Sentry CLI sidebar_order: 25 new: true -description: "A natural-language CLI for developers and AI agents. Investigate issues, get AI-powered root cause analysis, and manage Sentry projects from your terminal." +description: "A natural-language CLI for developers and AI agents. Investigate issues, use Seer's Autofix, and manage Sentry projects from your terminal." keywords: - CLI - Sentry CLI @@ -14,7 +14,7 @@ keywords: - agentic --- -The [Sentry CLI](https://cli.sentry.dev) is a command-line tool built for developers and AI agents. It auto-detects your project from `.env` files and the local codebase, so you don't need config files or flags. Type natural commands, investigate issues, get AI-powered root cause analysis from [Seer](/product/ai-in-sentry/seer/), and manage your Sentry projects directly from the terminal. +The [Sentry CLI](https://cli.sentry.dev) is a command-line tool built for developers and AI agents. It auto-detects your project from `.env` files and the local codebase, so you don't need config files or flags. Type natural commands, investigate issues, use [Seer's Autofix](/product/ai-in-sentry/seer/autofix/), and manage your Sentry projects directly from the terminal. For full documentation, visit [cli.sentry.dev](https://cli.sentry.dev). @@ -84,7 +84,7 @@ sentry issue list ### Investigate an Issue -Get AI-powered root cause analysis from Seer: +Use Seer's Autofix to analyze an issue: ```bash sentry issue explain diff --git a/docs/cli/releases.mdx b/docs/cli/releases.mdx index 49f5db9ac1ac34..7f79ca0add9b2c 100644 --- a/docs/cli/releases.mdx +++ b/docs/cli/releases.mdx @@ -117,7 +117,7 @@ You can upload sourcemaps via the `sentry-cli sourcemaps upload` command: sentry-cli sourcemaps upload /path/to/sourcemaps ``` -This command provides several options and attempts as much auto detection as possible. By default, it will scan the provided path for files and upload them named by their path with a `~/` prefix. It will also attempt to figure out references between minified files and source maps based on the filename. So if you have a file named `foo.min.js` which is a minified JavaScript file and a source map named `foo.min.map` for example, it will send a long a `Sourcemap` header to associate them. This works for files the system can detect a relationship of. +This command provides several options and attempts as much auto detection as possible. By default, it will scan the provided path for files and upload them named by their path with a `~/` prefix. It will also attempt to figure out references between minified files and source maps based on the filename. So if you have a file named `foo.min.js` which is a minified JavaScript file and a source map named `foo.min.map` for example, it will send along a `Sourcemap` header to associate them. This works for files the system can detect a relationship of. By default, `sentry-cli` rewrites source maps before upload: diff --git a/docs/organization/early-adopter-features/index.mdx b/docs/organization/early-adopter-features/index.mdx index 4d9c534d961e27..6d919bffe4a777 100644 --- a/docs/organization/early-adopter-features/index.mdx +++ b/docs/organization/early-adopter-features/index.mdx @@ -18,10 +18,10 @@ Limitations: ## Current Early Adopter Features -- [Issue Views](/product/issues/issue-views/) -- [Issue Status](/product/issues/states-triage/) tags -- [Span Summary](/product/insights/overview/transaction-summary/#span-summary) -- [Dynamic Alerts](/product/alerts/create-alerts/metric-alert-config/#dynamic-alerts) -- [New Trace Explorer With Span Metrics](/product/explore/new-trace-explorer/) -- [Size Analysis](/product/size-analysis/) -- [Uptime Monitoring Verification](/product/alerts/create-alerts/uptime-alert-config/#5-verification) +### AI & Automation + +- [Seer Slack Workflows](/product/ai-in-sentry/seer/autofix/#autofix-in-slack-beta) + +### Dashboards + +- [Prebuilt Sentry Dashboards](/product/dashboards/sentry-dashboards/) \ No newline at end of file diff --git a/docs/organization/integrations/cursor/index.mdx b/docs/organization/integrations/cursor/index.mdx index fd845fc9ef8288..ddfe3a26ae9704 100644 --- a/docs/organization/integrations/cursor/index.mdx +++ b/docs/organization/integrations/cursor/index.mdx @@ -7,7 +7,7 @@ description: >- og_image: /og-images/organization-integrations-cursor.png --- -You can trigger Cursor Cloud Agents from your [Seer Root Cause Analysis](/product/ai-in-sentry/seer/root-cause-analysis/) tab. The Cloud Agents will be provided with Seer's Root Cause Analysis alongside the issue context to help the Cloud Agent understand the issue and generate a solution. +You can trigger Cursor Cloud Agents from your [Seer Autofix](/product/ai-in-sentry/seer/autofix/) tab. The Cloud Agents will be provided with Seer's Autofix output alongside the issue context to help the Cloud Agent understand the issue and generate a solution. ## Install and Configure diff --git a/docs/organization/integrations/integration-platform/webhooks/seer.mdx b/docs/organization/integrations/integration-platform/webhooks/seer.mdx index 6b1eaf85672cec..f2db66b5d4eb2d 100644 --- a/docs/organization/integrations/integration-platform/webhooks/seer.mdx +++ b/docs/organization/integrations/integration-platform/webhooks/seer.mdx @@ -4,7 +4,7 @@ sidebar_order: 7 description: "Learn more about Sentry's integration platform Seer webhooks for Issue Fix analysis notifications." --- -Sentry integrations that have subscribed to Seer webhooks can receive notifications about the Seer [Root Cause Analysis](/product/ai-in-sentry/seer/root-cause-analysis/) process. These webhooks allow you to track the progress of automated root cause analysis, solution generation, and code fixes. +Sentry integrations that have subscribed to Seer webhooks can receive notifications about the Seer [Autofix](/product/ai-in-sentry/seer/autofix/) process. These webhooks allow you to track the progress of root cause analysis, solution generation, and code fixes. ## Sentry-Hook-Resource Header @@ -22,8 +22,8 @@ Seer webhooks support seven different event types that track the complete lifecy - `seer.solution_started` - Triggered when solution generation begins - `seer.solution_completed` - Triggered when a solution has been generated -### Code Generation -- `seer.coding_started` - Triggered when code generation/fixing begins +### Coding +- `seer.coding_started` - Triggered when the coding step (code fix generation) begins - `seer.coding_completed` - Triggered when code changes are ready - `seer.pr_created` - Triggered when pull request(s) are created @@ -175,7 +175,7 @@ Includes the generated solution details: ### Coding Started -Minimal payload indicating code generation has begun: +Minimal payload indicating the coding step has begun: ```json { @@ -272,4 +272,4 @@ Seer webhooks enable you to: ## Best Practices - Store the `run_id` to correlate related webhook events -- Use the `group_id` to link webhooks back to the original Sentry issue \ No newline at end of file +- Use the `group_id` to link webhooks back to the original Sentry issue diff --git a/docs/organization/integrations/source-code-mgmt/github/index.mdx b/docs/organization/integrations/source-code-mgmt/github/index.mdx index 93778f094f1772..18a9486460a75c 100644 --- a/docs/organization/integrations/source-code-mgmt/github/index.mdx +++ b/docs/organization/integrations/source-code-mgmt/github/index.mdx @@ -235,9 +235,9 @@ GitHub Enterprise should now be enabled for all projects under your Sentry organ ## Configure GitHub Integration -Use GitHub to [track commits](#commit-tracking), identify [suspect commits](#suspect-commits-and-suggested-assignees), [resolve via commit or PR](#resolve-via-commit-or-pull-request), [manage issues](#issue-management), and use AI for code review. +Use GitHub to [track commits](#commit-tracking), identify [suspect commits](#suspect-commits-and-suggested-assignees), [resolve via commit or PR](#resolve-via-commit-or-pull-request), and [manage issues](#issue-management). -To enable [AI Code Review](/product/ai-in-sentry/seer/ai-code-review), turn on the `Show Generative AI Features` and `Enable AI Code Review` settings in your [organization settings](https://sentry.io/orgredirect/settings/:orgslug/). +If you have added [Seer](/product/ai-in-sentry/seer/) to your organization, you can enable [Issue Autofix](/product/ai-in-sentry/seer/autofix/) and [Code Review](/product/ai-in-sentry/seer/code-review/) in your [organization settings](https://sentry.io/orgredirect/organizations/:orgslug/settings/seer/). ### Commit Tracking diff --git a/docs/platforms/android/user-feedback/configuration/index.mdx b/docs/platforms/android/user-feedback/configuration/index.mdx index 3702cc9474eb99..d9302195e9b6e8 100644 --- a/docs/platforms/android/user-feedback/configuration/index.mdx +++ b/docs/platforms/android/user-feedback/configuration/index.mdx @@ -99,6 +99,7 @@ You can customize which form elements are shown, whether they are required, and | `showName` | `Bool` | `true` | Displays the name field on the feedback form. Ignored if `isNameRequired` is `true`. | | `isEmailRequired` | `Bool` | `false` | Requires the email field on the feedback form to be filled in. | | `showEmail` | `Bool` | `true` | Displays the email field on the feedback form. Ignored if `isEmailRequired` is `true`. | +| `useShakeGesture` | `Bool` | `false` | Opens the feedback form when the user shakes the device. Uses the accelerometer and requires no additional permissions. | | `useSentryUser` | `Bool` | `true` | Sets the `email` and `name` fields to the corresponding Sentry SDK user fields that were called with `SentrySDK.setUser`. | Example: @@ -111,6 +112,7 @@ Example: + ``` ```java @@ -121,6 +123,7 @@ SentryAndroid.init(context, options -> { options.getFeedbackOptions().setShowEmail(false); options.getFeedbackOptions().setUseSentryUser(false); options.getFeedbackOptions().setShowBranding(false); + options.getFeedbackOptions().setUseShakeGesture(true); }); ``` ```kotlin @@ -131,6 +134,7 @@ SentryAndroid.init(this) { options -> options.feedbackOptions.isShowEmail = false options.feedbackOptions.isUseSentryUser = false options.feedbackOptions.isShowBranding = false + options.feedbackOptions.isUseShakeGesture = true } ``` diff --git a/docs/platforms/android/user-feedback/index.mdx b/docs/platforms/android/user-feedback/index.mdx index 90b4692e5fb990..b3ecd26742a969 100644 --- a/docs/platforms/android/user-feedback/index.mdx +++ b/docs/platforms/android/user-feedback/index.mdx @@ -44,6 +44,26 @@ val widget = SentryUserFeedbackButton(context) ``` +## Shake to Report + +You can enable shake-to-report so that shaking the device opens the User Feedback form. This uses the device's accelerometer and does not require any additional permissions. + +```java +SentryAndroid.init(context, options -> { + options.getFeedbackOptions().setUseShakeGesture(true); +}); +``` +```kotlin +SentryAndroid.init(this) { options -> + options.feedbackOptions.isUseShakeGesture = true +} +``` +```xml {filename:AndroidManifest.xml} + + + +``` + ## User Feedback Form The User Feedback form allows users to submit feedback from anywhere inside your application. diff --git a/docs/platforms/javascript/guides/angular/index.mdx b/docs/platforms/javascript/guides/angular/index.mdx index 72389d55aa207e..1c326463a5be89 100644 --- a/docs/platforms/javascript/guides/angular/index.mdx +++ b/docs/platforms/javascript/guides/angular/index.mdx @@ -32,7 +32,7 @@ npx @sentry/wizard@latest -i angular The wizard then guides you through the setup process, asking you to enable additional (optional) Sentry features for your application beyond error monitoring. - + This guide assumes that you enable all features and allow the wizard to add an example component to your application. You can add or remove features at any time, but setting them up now will save you the effort of configuring them manually later. @@ -71,7 +71,7 @@ Now, head over to your project on [Sentry.io](https://sentry.io) to view the col - + ## Next Steps diff --git a/docs/platforms/javascript/guides/angular/manual-setup.mdx b/docs/platforms/javascript/guides/angular/manual-setup.mdx index e26fcc61d13e39..16ac0887997cc8 100644 --- a/docs/platforms/javascript/guides/angular/manual-setup.mdx +++ b/docs/platforms/javascript/guides/angular/manual-setup.mdx @@ -75,7 +75,7 @@ Choose the features you want to configure, and this guide will show you how: ]} /> - + The main configuration should happen as early as possible in your app's lifecycle. Typically that means in your `main.ts` file. In addition, you'll need to register some providers to fully instrument your application. @@ -414,7 +414,7 @@ Open the page in a browser and click the button to trigger a frontend error and Now, head over to your project on [Sentry.io](https://sentry.io/) to view the collected data (it takes a couple of moments for the data to appear). - + ## Next Steps diff --git a/docs/platforms/javascript/guides/astro/index.mdx b/docs/platforms/javascript/guides/astro/index.mdx index 40ba29240c5dc8..e8f35f030fd57d 100644 --- a/docs/platforms/javascript/guides/astro/index.mdx +++ b/docs/platforms/javascript/guides/astro/index.mdx @@ -41,9 +41,6 @@ Choose the features you want to configure, and this guide will show you how: ]} /> - + diff --git a/docs/platforms/javascript/guides/azure-functions/index.mdx b/docs/platforms/javascript/guides/azure-functions/index.mdx index 8aa7e62e94c78c..ae6e4d59587338 100644 --- a/docs/platforms/javascript/guides/azure-functions/index.mdx +++ b/docs/platforms/javascript/guides/azure-functions/index.mdx @@ -19,7 +19,7 @@ Choose the features you want to configure, and this guide will show you how: options={["error-monitoring", "performance", "profiling", "logs"]} /> - + ### Install the Sentry SDK @@ -173,7 +173,7 @@ Deploy and trigger your function to start a child span. Now, head over to your project on [Sentry.io](https://sentry.io/) to view the collected data (it takes a couple of moments for the data to appear). - + ## Next Steps diff --git a/docs/platforms/javascript/guides/bun/index.mdx b/docs/platforms/javascript/guides/bun/index.mdx index 7829ca4f6e412e..a9018d52c22d59 100644 --- a/docs/platforms/javascript/guides/bun/index.mdx +++ b/docs/platforms/javascript/guides/bun/index.mdx @@ -19,7 +19,7 @@ Choose the features you want to configure, and this guide will show you how: options={["error-monitoring", "performance", "logs"]} /> - + ### Install the SDK @@ -134,7 +134,7 @@ Sentry.startSpan( Finally, head over to your project on [Sentry.io](https://sentry.io/) to view the collected data (it takes a couple of moments for the data to appear). - + ## Next Steps diff --git a/docs/platforms/javascript/guides/capacitor/index.mdx b/docs/platforms/javascript/guides/capacitor/index.mdx index 8045dd63039b16..23be2a15706588 100644 --- a/docs/platforms/javascript/guides/capacitor/index.mdx +++ b/docs/platforms/javascript/guides/capacitor/index.mdx @@ -58,7 +58,7 @@ Choose the features you want to configure, and this guide will show you how: ]} /> - + ### Initialize the Sentry SDK @@ -260,7 +260,7 @@ Open the page in a browser and click the button to trigger a frontend error and Now, head over to your project on [Sentry.io](https://sentry.io/) to view the collected data (it takes a couple of moments for the data to appear). - + ## Next Steps diff --git a/docs/platforms/javascript/guides/cloudflare/frameworks/astro.mdx b/docs/platforms/javascript/guides/cloudflare/frameworks/astro.mdx index 638681c2dc85af..e344a20999b9fd 100644 --- a/docs/platforms/javascript/guides/cloudflare/frameworks/astro.mdx +++ b/docs/platforms/javascript/guides/cloudflare/frameworks/astro.mdx @@ -80,6 +80,9 @@ export const onRequest = [ ]} /> - + - + diff --git a/docs/platforms/javascript/guides/cloudflare/frameworks/hono.mdx b/docs/platforms/javascript/guides/cloudflare/frameworks/hono.mdx index f4364bdbe918b1..6482572677c46d 100644 --- a/docs/platforms/javascript/guides/cloudflare/frameworks/hono.mdx +++ b/docs/platforms/javascript/guides/cloudflare/frameworks/hono.mdx @@ -6,10 +6,10 @@ description: "Learn how to instrument your Hono app on Cloudflare Workers and ca - The community-maintained `@hono/sentry` middleware that uses `toucan-js` has been deprecated in favor of - using `@sentry/cloudflare` directly. - If you're currently using the `@hono/sentry` middleware with `toucan-js`, you should migrate to - `@sentry/cloudflare` directly as shown in this guide. + The community-maintained `@hono/sentry` middleware that uses `toucan-js` has + been deprecated in favor of using `@sentry/cloudflare` directly. If you're + currently using the `@hono/sentry` middleware with `toucan-js`, you should + migrate to `@sentry/cloudflare` directly as shown in this guide. ## Step 1: Install @@ -20,7 +20,7 @@ Choose the features you want to configure, and this guide will show you how: options={["error-monitoring", "performance", "logs"]} /> - + ### Install the Sentry SDK @@ -83,6 +83,8 @@ export default Sentry.withSentry( platform="javascript.hono" /> + + ## Next Steps At this point, you should have integrated Sentry and should already be sending data to your Sentry project. diff --git a/docs/platforms/javascript/guides/cloudflare/frameworks/hydrogen-react-router.mdx b/docs/platforms/javascript/guides/cloudflare/frameworks/hydrogen-react-router.mdx index 534beca39954c6..48b293c2154537 100644 --- a/docs/platforms/javascript/guides/cloudflare/frameworks/hydrogen-react-router.mdx +++ b/docs/platforms/javascript/guides/cloudflare/frameworks/hydrogen-react-router.mdx @@ -30,10 +30,7 @@ Choose the features you want to configure, and this guide will show you how: ]} /> - + ### Install the Sentry SDK @@ -360,7 +357,7 @@ Open the `/sentry-test` route in your browser. You should start a trace and trig Now, head over to your project on [Sentry.io](https://sentry.io) to view the collected data (it takes a couple of moments for the data to appear). - + ## Next Steps diff --git a/docs/platforms/javascript/guides/cloudflare/frameworks/remix.mdx b/docs/platforms/javascript/guides/cloudflare/frameworks/remix.mdx index 6d2cd091124701..98de8efa12dbdc 100644 --- a/docs/platforms/javascript/guides/cloudflare/frameworks/remix.mdx +++ b/docs/platforms/javascript/guides/cloudflare/frameworks/remix.mdx @@ -22,10 +22,7 @@ Choose the features you want to configure, and this guide will show you how: ]} /> - + ### Install the Sentry SDK diff --git a/docs/platforms/javascript/guides/cloudflare/index.mdx b/docs/platforms/javascript/guides/cloudflare/index.mdx index 01e8df9a36dc56..91b792cbd2e87b 100644 --- a/docs/platforms/javascript/guides/cloudflare/index.mdx +++ b/docs/platforms/javascript/guides/cloudflare/index.mdx @@ -34,7 +34,7 @@ Choose the features you want to configure, and this guide will show you how: options={["error-monitoring", "performance", "logs"]} /> - + ### Install the Sentry SDK @@ -213,7 +213,7 @@ export async function onRequest(context) { Now, head over to your project on [Sentry.io](https://sentry.io) to view the collected data (it takes a couple of moments for the data to appear). - + ## Known Limitations diff --git a/docs/platforms/javascript/guides/deno/index.mdx b/docs/platforms/javascript/guides/deno/index.mdx index 6976988e763f0e..91f6f55a6c1287 100644 --- a/docs/platforms/javascript/guides/deno/index.mdx +++ b/docs/platforms/javascript/guides/deno/index.mdx @@ -25,7 +25,7 @@ Choose the features you want to configure, and this guide will show you how: options={["error-monitoring", "performance", "logs"]} /> - + ### Import the Sentry SDK @@ -136,7 +136,7 @@ Sentry.startSpan({ Finally, head over to your project on [Sentry.io](https://sentry.io/) to view the collected data (it takes a couple of moments for the data to appear). - + ## Next Steps diff --git a/docs/platforms/javascript/guides/electron/index.mdx b/docs/platforms/javascript/guides/electron/index.mdx index 9a7498e4ea236d..995152113344a3 100644 --- a/docs/platforms/javascript/guides/electron/index.mdx +++ b/docs/platforms/javascript/guides/electron/index.mdx @@ -41,7 +41,7 @@ Choose the features you want to configure, and this guide will show you how: ]} /> - + You should initialize the SDK in both the `main` process and every `renderer` process you spawn. @@ -252,7 +252,7 @@ Start your app and trigger two errors that Sentry will capture: one from the mai Now, head over to your project on [Sentry.io](https://sentry.io/) to view the collected data (it takes a couple of moments for the data to appear). - + ## Next Steps diff --git a/docs/platforms/javascript/guides/ember/index.mdx b/docs/platforms/javascript/guides/ember/index.mdx index 4d4d61e9a6fb1f..b6bbd83d70dba6 100644 --- a/docs/platforms/javascript/guides/ember/index.mdx +++ b/docs/platforms/javascript/guides/ember/index.mdx @@ -31,7 +31,7 @@ Choose the features you want to configure, and this guide will show you how: ]} /> - + ### Initialize the SDK @@ -173,7 +173,7 @@ Open the page in a browser and click the button to trigger a frontend error and Now, head over to your project on [Sentry.io](https://sentry.io) to view the collected data (it takes a couple of moments for the data to appear). - + ## Next Steps diff --git a/docs/platforms/javascript/guides/firebase/index.mdx b/docs/platforms/javascript/guides/firebase/index.mdx index c56bf0719647dd..bb9328810896b3 100644 --- a/docs/platforms/javascript/guides/firebase/index.mdx +++ b/docs/platforms/javascript/guides/firebase/index.mdx @@ -33,7 +33,7 @@ Choose the features you want to configure, and this guide will show you how: options={["error-monitoring", "performance", "profiling", "logs"]} /> - + ### Install the Sentry SDK @@ -176,7 +176,7 @@ exports.tracedFunction = onRequest(async (request, response) => { Now, head over to your project on [Sentry.io](https://sentry.io/) to view the collected data (it takes a couple of moments for the data to appear). - + ## Next Steps diff --git a/docs/platforms/javascript/guides/gatsby/index.mdx b/docs/platforms/javascript/guides/gatsby/index.mdx index 2fdc357a800b45..bff36acdc743b1 100644 --- a/docs/platforms/javascript/guides/gatsby/index.mdx +++ b/docs/platforms/javascript/guides/gatsby/index.mdx @@ -76,7 +76,7 @@ Choose the features you want to configure, and this guide will show you how: ]} /> - + ### Initialize the Sentry SDK @@ -196,7 +196,7 @@ Open the page in a browser and click the button to trigger a frontend error and Now, head over to your project on [Sentry.io](https://sentry.io/) to view the collected data (it takes a couple of moments for the data to appear). - + ## Next Steps diff --git a/docs/platforms/javascript/guides/gcp-functions/index.mdx b/docs/platforms/javascript/guides/gcp-functions/index.mdx index 77dc7aa54be8dd..84340b5685eddb 100644 --- a/docs/platforms/javascript/guides/gcp-functions/index.mdx +++ b/docs/platforms/javascript/guides/gcp-functions/index.mdx @@ -31,7 +31,7 @@ Choose the features you want to configure, and this guide will show you how: options={["error-monitoring", "performance", "profiling", "logs"]} /> - + ### Install the Sentry SDK @@ -133,7 +133,7 @@ exports.helloEvent = Sentry.wrapCloudEventFunction(async (context) => { Now, head over to your project on [Sentry.io](https://sentry.io/) to view the collected data (it takes a couple of moments for the data to appear). - + ## Next Steps diff --git a/docs/platforms/javascript/guides/nestjs/index.mdx b/docs/platforms/javascript/guides/nestjs/index.mdx index 3a5dd57bc8195b..6c9f102d6f53d0 100644 --- a/docs/platforms/javascript/guides/nestjs/index.mdx +++ b/docs/platforms/javascript/guides/nestjs/index.mdx @@ -29,7 +29,7 @@ Choose the features you want to configure, and this guide will show you how: options={["error-monitoring", "performance", "profiling", "logs"]} /> - + ### Initialize the Sentry SDK @@ -103,7 +103,7 @@ Let's test your setup and confirm that Sentry is working correctly and sending d Now, head over to your project on [Sentry.io](https://sentry.io/) to view the collected data (it takes a couple of moments for the data to appear). - + ## Next Steps diff --git a/docs/platforms/javascript/guides/nuxt/index.mdx b/docs/platforms/javascript/guides/nuxt/index.mdx index 2fe4b2165d7752..d9c87244201d34 100644 --- a/docs/platforms/javascript/guides/nuxt/index.mdx +++ b/docs/platforms/javascript/guides/nuxt/index.mdx @@ -20,7 +20,7 @@ npx @sentry/wizard@latest -i nuxt The wizard then guides you through the setup process, asking you to enable additional (optional) Sentry features for your application beyond error monitoring. - + This guide assumes that you enable all features and allow the wizard to create an example page or component. You can add or remove features at any time, but setting them up now will save you the effort of configuring them manually later. @@ -55,9 +55,10 @@ To test Sentry, you can run your Nuxt application in either production or develo We **recommend testing in production mode** as it most closely resembles your deployed application's environment. - By default, the SDK will add the server config as `sentry.server.config.mjs` to the build. - To find the exact path to this file, enable `debug` mode in your Sentry configuration within `nuxt.config.ts`. - Sentry will then print the exact path during the build process. + By default, the SDK will add the server config as `sentry.server.config.mjs` + to the build. To find the exact path to this file, enable `debug` mode in your + Sentry configuration within `nuxt.config.ts`. Sentry will then print the exact + path during the build process. ### Run in Production Mode (Recommended) @@ -95,7 +96,7 @@ Now, head over to your project on [Sentry.io](https://sentry.io/) to view the co - + ## Next Steps diff --git a/docs/platforms/javascript/guides/react-router/index.mdx b/docs/platforms/javascript/guides/react-router/index.mdx index 7504409b216c7c..100de8b26a1631 100644 --- a/docs/platforms/javascript/guides/react-router/index.mdx +++ b/docs/platforms/javascript/guides/react-router/index.mdx @@ -84,7 +84,7 @@ Select which Sentry features you'd like to install in addition to Error Monitori ]} /> - + @@ -248,7 +248,7 @@ Now, head over to your project on [Sentry.io](https://sentry.io) to view the col - + ## Next Steps diff --git a/docs/platforms/javascript/guides/react-router/manual-setup.mdx b/docs/platforms/javascript/guides/react-router/manual-setup.mdx index 799694929c3216..f9e75753ddc7bc 100644 --- a/docs/platforms/javascript/guides/react-router/manual-setup.mdx +++ b/docs/platforms/javascript/guides/react-router/manual-setup.mdx @@ -73,7 +73,7 @@ Choose the features you want to configure, and this guide will show you how: ]} /> - + ### Expose Entry Point Files @@ -565,7 +565,7 @@ Open the route in your browser. You should start a trace and trigger an error. Now, head over to your project on [Sentry.io](https://sentry.io) to view the collected data (it takes a couple of moments for the data to appear). - + ## Next Steps diff --git a/docs/platforms/javascript/guides/react/index.mdx b/docs/platforms/javascript/guides/react/index.mdx index 84db6936f704a8..8ee2dc94081fb4 100644 --- a/docs/platforms/javascript/guides/react/index.mdx +++ b/docs/platforms/javascript/guides/react/index.mdx @@ -14,6 +14,7 @@ categories: If you're using Next.js, Remix, or another framework with server-side rendering, use the dedicated SDK instead: + - [Next.js](/platforms/javascript/guides/nextjs/) - [Remix](/platforms/javascript/guides/remix/) - [Gatsby](/platforms/javascript/guides/gatsby/) @@ -54,7 +55,7 @@ Choose the features you want to configure: ]} /> - + @@ -172,7 +173,7 @@ const container = document.getElementById("app"); const root = createRoot(container, { // Callback called when an error is thrown and not caught by an ErrorBoundary. onUncaughtError: Sentry.reactErrorHandler((error, errorInfo) => { - console.warn('Uncaught error', error, errorInfo.componentStack); + console.warn("Uncaught error", error, errorInfo.componentStack); }), // Callback called when React catches an error in an ErrorBoundary. onCaughtError: Sentry.reactErrorHandler(), @@ -295,10 +296,7 @@ import * as Sentry from "@sentry/react"; const sentryEnhancer = Sentry.createReduxEnhancer(); -const store = createStore( - rootReducer, - compose(sentryEnhancer) -); +const store = createStore(rootReducer, compose(sentryEnhancer)); ``` diff --git a/docs/platforms/javascript/guides/remix/index.mdx b/docs/platforms/javascript/guides/remix/index.mdx index 0557f18f365721..d5ed822cf07dfa 100644 --- a/docs/platforms/javascript/guides/remix/index.mdx +++ b/docs/platforms/javascript/guides/remix/index.mdx @@ -21,7 +21,7 @@ npx @sentry/wizard@latest -i remix The wizard then guides you through the setup process, asking you to enable additional (optional) Sentry features for your application beyond error monitoring. - + This guide assumes that you enable all features and allow the wizard to create an example page. You can add or remove features at any time, but setting them up now will save you the effort of configuring them manually later. @@ -95,7 +95,7 @@ Now, head over to your project on [Sentry.io](https://sentry.io) to view the col - + ## Next Steps diff --git a/docs/platforms/javascript/guides/remix/manual-setup.mdx b/docs/platforms/javascript/guides/remix/manual-setup.mdx index 35e1a936fcfd55..9657c824380268 100644 --- a/docs/platforms/javascript/guides/remix/manual-setup.mdx +++ b/docs/platforms/javascript/guides/remix/manual-setup.mdx @@ -29,7 +29,7 @@ Choose the features you want to configure, and this guide will show you how: ]} /> - + ### Install the Sentry SDK diff --git a/docs/platforms/javascript/guides/solid/index.mdx b/docs/platforms/javascript/guides/solid/index.mdx index 7e2f7607c51071..b8d79b3a780d84 100644 --- a/docs/platforms/javascript/guides/solid/index.mdx +++ b/docs/platforms/javascript/guides/solid/index.mdx @@ -44,7 +44,7 @@ Choose the features you want to configure, and this guide will show you how: ]} /> - + ### Initialize the Sentry SDK @@ -190,7 +190,7 @@ Open the page in a browser and click the button to trigger a frontend error and Now, head over to your project on [Sentry.io](https://sentry.io/) to view the collected data (it takes a couple of moments for the data to appear). - + ## Next Steps diff --git a/docs/platforms/javascript/guides/solidstart/index.mdx b/docs/platforms/javascript/guides/solidstart/index.mdx index 8fbef30f0787f0..b04bdb221d94bf 100644 --- a/docs/platforms/javascript/guides/solidstart/index.mdx +++ b/docs/platforms/javascript/guides/solidstart/index.mdx @@ -35,7 +35,7 @@ Choose the features you want to configure, and this guide will show you how: ]} /> - + ### Install the Sentry SDK @@ -368,7 +368,7 @@ Open the page in the browser and click the button to trigger a frontend error, a Now, head over to your project on [Sentry.io](https://sentry.io) to view the collected data (it takes a couple of moments for the data to appear). - + ## Next Steps diff --git a/docs/platforms/javascript/guides/svelte/index.mdx b/docs/platforms/javascript/guides/svelte/index.mdx index 09fa9131a98c23..feb8cdae7f8ae9 100644 --- a/docs/platforms/javascript/guides/svelte/index.mdx +++ b/docs/platforms/javascript/guides/svelte/index.mdx @@ -51,7 +51,7 @@ Choose the features you want to configure, and this guide will show you how: ]} /> - + To use the SDK, initialize it in your Svelte entry point before bootstrapping your app. In a typical Svelte project, that is your `main.js` or `main.ts` file. @@ -283,7 +283,7 @@ Open the page in a browser and click the button to trigger a frontend error and Now, head over to your project on [Sentry.io](https://sentry.io/) to view the collected data (it takes a couple of moments for the data to appear). - + ## Next Steps diff --git a/docs/platforms/javascript/guides/sveltekit/index.mdx b/docs/platforms/javascript/guides/sveltekit/index.mdx index 61ae03e43d1f44..84f33a11652a5b 100644 --- a/docs/platforms/javascript/guides/sveltekit/index.mdx +++ b/docs/platforms/javascript/guides/sveltekit/index.mdx @@ -23,7 +23,7 @@ npx @sentry/wizard@latest -i sveltekit The wizard then guides you through the setup process, asking you to enable additional (optional) Sentry features for your application beyond error monitoring. - + This guide assumes that you enable all features and allow the wizard to create an example page. You can add or remove features at any time, but setting them up now will save you the effort of configuring them manually later. @@ -66,7 +66,7 @@ Now, head over to your project on [Sentry.io](https://sentry.io) to view the col - + ## Next Steps diff --git a/docs/platforms/javascript/guides/sveltekit/manual-setup__v10.7.0.mdx b/docs/platforms/javascript/guides/sveltekit/manual-setup__v10.7.0.mdx index e87c2ac008fa47..00c0ef1df68368 100644 --- a/docs/platforms/javascript/guides/sveltekit/manual-setup__v10.7.0.mdx +++ b/docs/platforms/javascript/guides/sveltekit/manual-setup__v10.7.0.mdx @@ -15,7 +15,7 @@ You need: - A Sentry [account](https://sentry.io/signup/) and [project](/product/projects/) - Your application up and running -- SvelteKit version `2.0.0`+ +- SvelteKit version `2.0.0`+ - Vite version `4.2`+ @@ -49,7 +49,7 @@ Choose the features you want to configure, and this guide will show you how: ]} /> - + ### Install the Sentry SDK @@ -323,7 +323,7 @@ Additionally, this starts a trace to measure the time it takes for the API reque Now, head over to your project on [Sentry.io](https://sentry.io) to view the collected data (it takes a couple of moments for the data to appear). - + ## Next Steps diff --git a/docs/platforms/javascript/guides/tanstackstart-react/index.mdx b/docs/platforms/javascript/guides/tanstackstart-react/index.mdx index b710e5821ec898..fe05168eb4c34f 100644 --- a/docs/platforms/javascript/guides/tanstackstart-react/index.mdx +++ b/docs/platforms/javascript/guides/tanstackstart-react/index.mdx @@ -28,7 +28,7 @@ Choose the features you want to configure, and this guide will show you how: ]} /> - + ### Install the Sentry SDK @@ -443,7 +443,7 @@ Additionally, this starts a performance trace to measure the time it takes for t Now, head over to your project on [Sentry.io](https://sentry.io) to view the collected data (it takes a couple of moments for the data to appear). - + ## Next Steps diff --git a/docs/platforms/javascript/guides/vue/index.mdx b/docs/platforms/javascript/guides/vue/index.mdx index bc62cca30cf78f..dcf83089c37eea 100644 --- a/docs/platforms/javascript/guides/vue/index.mdx +++ b/docs/platforms/javascript/guides/vue/index.mdx @@ -41,7 +41,7 @@ Choose the features you want to configure, and this guide will show you how: ]} /> - + To initialize Sentry in your Vue application, add the following code snippet to your `main.js`: @@ -296,7 +296,7 @@ Open the page in a browser and click the button to trigger a frontend error and Now, head over to your project on [Sentry.io](https://sentry.io/) to view the collected data (it takes a couple of moments for the data to appear). - + ## Next Steps diff --git a/docs/platforms/javascript/guides/wasm/index.mdx b/docs/platforms/javascript/guides/wasm/index.mdx index edd06a8484f6f9..02dff63aea87e2 100644 --- a/docs/platforms/javascript/guides/wasm/index.mdx +++ b/docs/platforms/javascript/guides/wasm/index.mdx @@ -25,7 +25,7 @@ Choose the features you want to configure, and this guide will show you how: options={["error-monitoring", "performance", "logs"]} /> - + ### Install the Sentry SDK @@ -193,7 +193,7 @@ function testWasmTracing() { Now, head over to your project on [Sentry.io](https://sentry.io/) to view the collected data (it takes a couple of moments for the data to appear). - + ## Next Steps diff --git a/docs/platforms/python/integrations/fastapi/index.mdx b/docs/platforms/python/integrations/fastapi/index.mdx index 81eebc71901d5c..6a4afc05dc7e5e 100644 --- a/docs/platforms/python/integrations/fastapi/index.mdx +++ b/docs/platforms/python/integrations/fastapi/index.mdx @@ -19,17 +19,6 @@ uv add sentry-sdk ## Configure -Choose the features you want to configure, and this guide will show you how: - - - If you have the `fastapi` package in your dependencies, the FastAPI integration will be enabled automatically when you initialize the Sentry SDK. diff --git a/docs/platforms/python/integrations/flask/index.mdx b/docs/platforms/python/integrations/flask/index.mdx index 94dab73874af0e..7cfcc4ca0e286b 100644 --- a/docs/platforms/python/integrations/flask/index.mdx +++ b/docs/platforms/python/integrations/flask/index.mdx @@ -18,17 +18,6 @@ uv add sentry-sdk ## Configure -Choose the features you want to configure, and this guide will show you how: - - - If you have the `flask` package in your dependencies, the Flask integration will be enabled automatically when you initialize the Sentry SDK. diff --git a/docs/platforms/python/tracing/instrumentation/custom-instrumentation/ai-agents-module.mdx b/docs/platforms/python/tracing/instrumentation/custom-instrumentation/ai-agents-module.mdx index d1df34c061fab3..e284a8dff3bf00 100644 --- a/docs/platforms/python/tracing/instrumentation/custom-instrumentation/ai-agents-module.mdx +++ b/docs/platforms/python/tracing/instrumentation/custom-instrumentation/ai-agents-module.mdx @@ -136,7 +136,7 @@ with sentry_sdk.start_span(op="gen_ai.invoke_agent", name="invoke_agent Travel A Tracking Conversations has **alpha** stability. Configuration options and behavior may change. -For AI applications that involve multi-turn conversations, you can use `sentry_sdk.ai.set_conversation_id()` to associate all AI spans from the same conversation. This enables you to track and analyze complete conversation flows within Sentry. +For AI applications that involve multi-turn conversations, you can use `sentry_sdk.ai.set_conversation_id()` to associate all AI spans from the same conversation. This enables you to track and analyze complete conversation flows within Sentry. The conversation ID is set as the `gen_ai.conversation.id` attribute on all AI-related spans in the current scope. To remove the conversation ID, use the `remove_conversation_id()` method on the `Scope`. diff --git a/docs/platforms/react-native/manual-setup/expo.mdx b/docs/platforms/react-native/manual-setup/expo.mdx index 3afafffef16bb0..d7159b016a6b81 100644 --- a/docs/platforms/react-native/manual-setup/expo.mdx +++ b/docs/platforms/react-native/manual-setup/expo.mdx @@ -148,9 +148,20 @@ To verify that everything is working as expected, build the `Release` version of ## Next Steps -- [Learn how to upload source maps for native builds and Expo Updates](/platforms/react-native/sourcemaps/uploading/expo/) -- [Add automatic tracing with Expo Router](/platforms/react-native/tracing/instrumentation/expo-router/) -- [Configure the Sentry Android Gradle Plugin](/platforms/react-native/manual-setup/expo/gradle/) +### Expo-Specific Features + +- [Expo Updates](/platforms/react-native/manual-setup/expo/expo-updates/) — Automatic OTA update context, searchable tags, and emergency launch alerts +- [EAS Build Hooks](/platforms/react-native/manual-setup/expo/eas-build-hooks/) — Capture build failures and lifecycle events from EAS Build +- [Sentry Android Gradle Plugin](/platforms/react-native/manual-setup/expo/gradle/) — Advanced Android build configuration + +### Source Maps and Releases + +- [Upload source maps for native builds and Expo Updates](/platforms/react-native/sourcemaps/uploading/expo/) + +### Performance + +- [Expo Router tracing](/platforms/react-native/tracing/instrumentation/expo-router/) — Navigation transitions, performance spans, and prefetch instrumentation +- [Expo Image and Asset tracing](/platforms/react-native/tracing/instrumentation/expo-resources/) — Automatic spans for `expo-image` and `expo-asset` ## Notes diff --git a/docs/platforms/react-native/manual-setup/expo/eas-build-hooks.mdx b/docs/platforms/react-native/manual-setup/expo/eas-build-hooks.mdx new file mode 100644 index 00000000000000..06cc812ad7ebea --- /dev/null +++ b/docs/platforms/react-native/manual-setup/expo/eas-build-hooks.mdx @@ -0,0 +1,79 @@ +--- +title: EAS Build Hooks +description: "Capture EAS build failures and lifecycle events in Sentry." +sidebar_order: 10 +--- + +EAS Build runs your app builds on Expo's infrastructure. When a build fails, the error can be hard to diagnose — it happens outside your local environment and outside your app. EAS Build Hooks let you send build lifecycle events directly to Sentry so you can track failures, correlate them with releases, and get notified when production builds break. + +## Setup + +Add the Sentry EAS build hook scripts to your `package.json`: + +```json {filename:package.json} +{ + "scripts": { + "eas-build-on-error": "sentry-eas-build-on-error", + "eas-build-on-success": "sentry-eas-build-on-success", + "eas-build-on-complete": "sentry-eas-build-on-complete" + } +} +``` + +EAS Build automatically runs `package.json` scripts with these names at the corresponding lifecycle events. See the [Expo npm hooks documentation](https://docs.expo.dev/build-reference/npm-hooks/) for more details. + +Set your DSN as an EAS secret or environment variable so it's available during builds: + +```bash +eas secret:create --scope project --name SENTRY_DSN --value +``` + +## What Gets Captured + +**`eas-build-on-error`** — Sends an `EASBuildError` event to Sentry when a build fails. The event includes: + +- Build platform (`ios` / `android`) +- Build profile (for example, `production`, `preview`) +- Build ID, project ID, git commit hash +- Whether the build ran on CI + +**`eas-build-on-success`** — Optionally sends an info event when a build succeeds. Disabled by default; enable it with `SENTRY_EAS_BUILD_CAPTURE_SUCCESS=true`. + +**`eas-build-on-complete`** — A single hook that captures either a failure or success event depending on the build outcome. Use this instead of `on-error` + `on-success` if you prefer a single hook entry point. + +All events are tagged with `eas.*` tags so you can filter and group them in Sentry. + +## Environment Variables + +| Variable | Required | Description | +|---|---|---| +| `SENTRY_DSN` | Yes | Your project's DSN | +| `SENTRY_EAS_BUILD_CAPTURE_SUCCESS` | No | Set to `true` to capture successful builds | +| `SENTRY_EAS_BUILD_TAGS` | No | JSON object of additional tags, for example `{"team":"mobile"}` | +| `SENTRY_EAS_BUILD_ERROR_MESSAGE` | No | Custom error message for failed builds | +| `SENTRY_EAS_BUILD_SUCCESS_MESSAGE` | No | Custom message for successful builds | +| `SENTRY_RELEASE` | No | Override the release name (defaults to `{appVersion}+{buildNumber}`) | + +## Environment Files + +The hook automatically loads environment variables from the following sources (without overwriting values already set by EAS): + +1. `@expo/env` (if available) +2. `.env` file in the project root (via `dotenv`, if available) +3. `.env.sentry-build-plugin` file in the project root + +This means you can store the DSN in `.env.sentry-build-plugin` locally, and use an EAS secret in CI — the hook will use whichever value is already set. + +## Using `on-complete` Instead of Separate Hooks + +If you only need to track failures but want the option to add success tracking later, `eas-build-on-complete` is the most flexible option. It reads `EAS_BUILD_STATUS` (set by EAS) to determine the outcome and captures the appropriate event: + +```json {filename:package.json} +{ + "scripts": { + "eas-build-on-complete": "sentry-eas-build-on-complete" + } +} +``` + +To also capture successful builds, set `SENTRY_EAS_BUILD_CAPTURE_SUCCESS=true` in your build environment. diff --git a/docs/platforms/react-native/manual-setup/expo/expo-updates.mdx b/docs/platforms/react-native/manual-setup/expo/expo-updates.mdx new file mode 100644 index 00000000000000..0035f49ded7383 --- /dev/null +++ b/docs/platforms/react-native/manual-setup/expo/expo-updates.mdx @@ -0,0 +1,74 @@ +--- +title: Expo Updates +description: "Automatic context and alerts for Expo OTA updates." +sidebar_order: 20 +--- + +When you ship OTA updates with Expo Updates, events captured by Sentry are automatically enriched with information about which update is running. This lets you filter issues by update channel, runtime version, or update ID — and get alerted when an emergency launch occurs. + +These integrations are enabled by default in Expo projects. No additional setup is required. + +## Expo Updates Context + +Every Sentry event includes an `ota_updates` context with the current update state: + +| Field | Description | +|---|---| +| `update_id` | UUID of the currently running OTA update | +| `channel` | Expo Updates channel (for example, `production`, `staging`) | +| `runtime_version` | Runtime version of the update | +| `is_enabled` | Whether Expo Updates is enabled | +| `is_embedded_launch` | Whether the app launched from the embedded bundle | +| `is_using_embedded_assets` | Whether the app is using embedded assets | +| `is_emergency_launch` | Whether this was an emergency launch (fallback to embedded) | +| `emergency_launch_reason` | Reason for the emergency launch (if applicable) | +| `check_automatically` | Automatic update check policy | +| `launch_duration` | How long the update launch took (ms) | +| `created_at` | When the update was created | + +## Searchable Tags + +The SDK also sets the following tags on every event so you can filter and group issues in Sentry: + +| Tag | Value | +|---|---| +| `expo.updates.update_id` | UUID of the running update | +| `expo.updates.channel` | Update channel name | +| `expo.updates.runtime_version` | Runtime version string | + +To find all issues from a specific update channel, use `expo.updates.channel:production` in the Sentry issue search. + +## Emergency Launch Warnings + +Expo Updates performs an _emergency launch_ when it fails to load the latest OTA update and falls back to the embedded bundle. This can silently degrade user experience. + +When the SDK detects an emergency launch at startup, it automatically sends a `warning`-level event to Sentry with: + +- Message: `Expo Updates emergency launch: ` (or `Expo Updates emergency launch` if no reason is available) +- Tag: `expo.updates.emergency_launch: true` + +You can set up a Sentry alert on this tag to get notified whenever an emergency launch happens in production. + + + +Emergency launch detection only runs in native builds, not in Expo Go. + + + +## Expo Constants Context + +The SDK automatically captures Expo Constants as an `expo_constants` context on every event. This provides metadata about the execution environment and app configuration: + +| Field | Description | +|---|---| +| `execution_environment` | Where the app is running (`storeClient`, `standalone`, `bare`) | +| `app_ownership` | Whether the app runs in Expo Go or standalone | +| `debug_mode` | Whether debug mode is enabled | +| `expo_version` | Expo client version | +| `expo_runtime_version` | Runtime version from app config | +| `session_id` | Current session ID | +| `app_name` | App name from `app.json` | +| `app_slug` | App slug from `app.json` | +| `app_version` | App version from `app.json` | +| `expo_sdk_version` | Expo SDK version | +| `eas_project_id` | EAS project ID | diff --git a/docs/platforms/react-native/tracing/instrumentation/expo-resources.mdx b/docs/platforms/react-native/tracing/instrumentation/expo-resources.mdx new file mode 100644 index 00000000000000..8f4a1fd993cbf7 --- /dev/null +++ b/docs/platforms/react-native/tracing/instrumentation/expo-resources.mdx @@ -0,0 +1,44 @@ +--- +title: Expo Image and Asset Instrumentation +description: "Automatic performance spans for expo-image and expo-asset." +sidebar_order: 70 +--- + +Image and asset loading times directly affect how quickly your app feels responsive. The SDK can automatically create performance spans for `expo-image` and `expo-asset` operations so you can see exactly how long prefetching and loading takes within your existing traces. + +## Expo Image + +Wrap the `Image` class from `expo-image` once at app startup to instrument `Image.prefetch()` and `Image.loadAsync()`: + +```javascript {filename:App.js} +import { Image } from 'expo-image'; +import * as Sentry from '@sentry/react-native'; + +Sentry.wrapExpoImage(Image); +``` + +After wrapping, every call to `Image.prefetch()` creates a `resource.image.prefetch` span, and every call to `Image.loadAsync()` creates a `resource.image.load` span. The spans are automatically linked to the active trace. + +Span attributes include: + +- `image.url` — the image URL (for single-image operations) +- `image.url_count` — number of URLs (for batch prefetch) + +## Expo Asset + +Wrap the `Asset` class from `expo-asset` once at app startup to instrument `Asset.loadAsync()`: + +```javascript {filename:App.js} +import { Asset } from 'expo-asset'; +import * as Sentry from '@sentry/react-native'; + +Sentry.wrapExpoAsset(Asset); +``` + +After wrapping, every call to `Asset.loadAsync()` creates a `resource.asset` span with an `asset.count` attribute. + +## Notes + +- Both `wrapExpoImage` and `wrapExpoAsset` are safe to call multiple times — the SDK guards against double-wrapping. +- Spans are only created when a trace is active. If you're not using [tracing](/platforms/react-native/tracing/), no spans are created and there's no overhead. +- `expo-image` and `expo-asset` are peer dependencies — the SDK does not require them to be installed. diff --git a/docs/platforms/react-native/tracing/instrumentation/expo-router.mdx b/docs/platforms/react-native/tracing/instrumentation/expo-router.mdx index 06bb3ed948a508..aee83eb1a7f5ca 100644 --- a/docs/platforms/react-native/tracing/instrumentation/expo-router.mdx +++ b/docs/platforms/react-native/tracing/instrumentation/expo-router.mdx @@ -69,6 +69,34 @@ This option will enable automatic measuring of the time to initial display for e This ensures that transactions that are from routes that've been seen and don't have any spans, are not being sampled. This removes a lot of clutter, making it so that most back navigation transactions are now ignored. The default value is `true`. +## Prefetch Instrumentation + + + +`router.prefetch()` requires **Expo Router v5 (Expo SDK 53) or later**. On older versions the method does not exist; calling it will throw a runtime error. + + + +Expo Router's `router.prefetch()` preloads a route before the user navigates to it. By default, these prefetch calls are invisible in your traces. Wrapping the router with `Sentry.wrapExpoRouter()` adds an automatic `navigation.prefetch` span for each call so you can see prefetch timing alongside your other navigation spans. + +```javascript {filename:app/(tabs)/index.tsx} +import { useRouter } from 'expo-router'; +import * as Sentry from '@sentry/react-native'; + +function HomeScreen() { + const router = Sentry.wrapExpoRouter(useRouter()); + + return ( + - ) : section.label === 'More' ? ( + ) : section.label === 'Manage' ? (
{ @@ -320,7 +320,7 @@ export default function TopNavClient({platforms}: {platforms: Platform[]}) { ref={moreBtnRef} className={`text-[var(--gray-12)] transition-all duration-150 inline-block py-2 px-1 rounded-t-md flex items-center gap-1 text-[0.875rem] font-normal border-b-2 ${ mainSections - .find(s => s.label === 'More') + .find(s => s.label === 'Manage') ?.dropdown?.some(d => pathname?.startsWith(d.href)) ? 'border-[var(--accent-purple)]' : moreDropdownOpen @@ -576,7 +576,7 @@ export default function TopNavClient({platforms}: {platforms: Platform[]}) { } `} {mainSections - .find(s => s.label === 'More') + .find(s => s.label === 'Manage') ?.dropdown?.map(dropdown => ( { + describe('headings', () => { + it.each([ + ['h1', '# text\n\n'], + ['h2', '## text\n\n'], + ['h3', '### text\n\n'], + ['h4', '#### text\n\n'], + ['h5', '##### text\n\n'], + ['h6', '###### text\n\n'], + ])('converts %s', (tag, expected) => { + expect(domToMarkdown(parse(`<${tag}>text`))).toBe(expected); + }); + }); + + describe('inline formatting', () => { + it.each([ + ['bold', '**bold**'], + ['bold', '**bold**'], + ['italic', '*italic*'], + ['italic', '*italic*'], + ['foo()', '`foo()`'], + ])('converts %s', (html, expected) => { + expect(domToMarkdown(parse(html))).toBe(expected); + }); + + it('converts a', () => { + expect(domToMarkdown(parse('link'))).toBe( + '[link](https://example.com)' + ); + }); + }); + + describe('block elements', () => { + it('converts p', () => { + expect(domToMarkdown(parse('

hello

'))).toBe('hello\n\n'); + }); + it('converts ul with li', () => { + expect(domToMarkdown(parse('
  • a
  • b
'))).toBe('- a\n- b\n\n'); + }); + it('converts ol with li', () => { + expect(domToMarkdown(parse('
  1. first
  2. second
'))).toBe( + '1. first\n2. second\n\n' + ); + }); + }); + + describe('checkboxes', () => { + it('converts unchecked checkbox', () => { + expect(domToMarkdown(parse(''))).toBe('[ ] '); + }); + it('converts checked checkbox', () => { + const div = parse(''); + (div.querySelector('input') as HTMLInputElement).checked = true; + expect(domToMarkdown(div)).toBe('[x] '); + }); + }); + + describe('document structure', () => { + it('preserves heading prefixes in a full document', () => { + const result = domToMarkdown( + parse('

Title

Section

Body text.

') + ); + expect(result).toBe('# Title\n\n## Section\n\nBody text.\n\n'); + }); + }); +}); diff --git a/src/components/copyableCard.tsx b/src/components/copyableCard.tsx index 9c77bc67283347..71f4bb78e43c4c 100644 --- a/src/components/copyableCard.tsx +++ b/src/components/copyableCard.tsx @@ -11,7 +11,7 @@ import Chevron from 'sentry-docs/icons/Chevron'; * preserve formatting (checkboxes, bold, links, lists) when pasted * into GitHub's markdown editor. */ -function domToMarkdown(node: Node): string { +export function domToMarkdown(node: Node): string { if (node.nodeType === Node.TEXT_NODE) { return node.textContent ?? ''; } @@ -34,6 +34,18 @@ function domToMarkdown(node: Node): string { const childText = Array.from(el.childNodes).map(domToMarkdown).join(''); switch (tag) { + case 'h1': + return `# ${childText}\n\n`; + case 'h2': + return `## ${childText}\n\n`; + case 'h3': + return `### ${childText}\n\n`; + case 'h4': + return `#### ${childText}\n\n`; + case 'h5': + return `##### ${childText}\n\n`; + case 'h6': + return `###### ${childText}\n\n`; case 'strong': case 'b': return `**${childText}**`; diff --git a/src/components/featureInfo.tsx b/src/components/featureInfo.tsx new file mode 100644 index 00000000000000..efb752616b2abe --- /dev/null +++ b/src/components/featureInfo.tsx @@ -0,0 +1,181 @@ +import type {ReactNode} from 'react'; +import {Fragment} from 'react'; + +import {ExternalLink} from './externalLink'; + +type FeatureKey = + | 'issues' + | 'tracing' + | 'sessionReplay' + | 'logs' + | 'profiling' + | 'userFeedback' + | 'metrics'; + +const FEATURE_DATA: Record< + FeatureKey, + { + findInSentry: ReactNode; + learnMore: ReactNode; + link: string; + title: string; + } +> = { + issues: { + title: 'Issues', + link: '/product/issues', + learnMore: + "Sentry's core error monitoring product that automatically reports errors, uncaught exceptions, and unhandled rejections. If you have something that looks like an exception, Sentry can capture it.", + findInSentry: ( + + Open the{' '} + + Issues + {' '} + page and select an error from the issues list to view the full details and context + of this error. For more details, see this{' '} + + interactive walkthrough + + . + + ), + }, + tracing: { + title: 'Tracing', + link: '/product/tracing', + learnMore: + 'Track software performance while seeing the impact of errors across multiple systems. For example, distributed tracing allows you to follow a request from the frontend to the backend and back.', + findInSentry: ( + + Open the{' '} + + Traces + {' '} + page and select a trace to reveal more information about each span, its duration, + and any errors. For an interactive UI walkthrough, click{' '} + + here + + . + + ), + }, + sessionReplay: { + title: 'Session Replay', + link: '/product/explore/session-replay/web', + learnMore: + "Get to the root cause of an issue faster by viewing a video-like reproduction of what was happening in the user's browser before, during, and after the problem.", + findInSentry: ( + + Open the{' '} + + Replays + {' '} + page and select an entry from the list to get a detailed view where you can replay + the interaction and get more information to help you troubleshoot. + + ), + }, + logs: { + title: 'Logs', + link: '/product/explore/logs', + learnMore: + "Centralize and analyze your application logs to correlate them with errors and performance issues. Search, filter, and visualize log data to understand what's happening in your applications.", + findInSentry: ( + + Open the{' '} + + Logs + {' '} + page and filter by service, environment, or search keywords to view log entries + from your application. For an interactive UI walkthrough, click{' '} + here. + + ), + }, + profiling: { + title: 'Profiling', + link: '/product/explore/profiling/', + learnMore: + 'Gain deeper insight than traditional tracing without custom instrumentation, letting you discover slow-to-execute or resource-intensive functions in your app.', + findInSentry: ( + + Open the{' '} + + Profiles + {' '} + page, select a transaction, and then a profile ID to view its flame graph. For + more information, click{' '} + here. + + ), + }, + userFeedback: { + title: 'User Feedback', + link: '/product/user-feedback', + learnMore: + 'Collect feedback directly from users when they encounter errors, allowing them to describe what happened and provide context that helps you understand and resolve issues faster.', + findInSentry: ( + + Open the{' '} + + User Feedback + {' '} + page and click on individual feedback to see more details all in one view. For + more information, click here. + + ), + }, + metrics: { + title: 'Metrics', + link: '/product/explore/metrics', + learnMore: + "Track and analyze custom metrics, such as response times and database query durations, to understand trends and patterns in your application's performance and behavior over time.", + findInSentry: ( + + Open the{' '} + + Metrics + {' '} + page to view and analyze your custom metrics. For more details, see this{' '} + interactive walkthrough. + + ), + }, +}; + +type FeatureInfoProps = { + features: FeatureKey[]; + type: 'learnMore' | 'findInSentry'; +}; + +/** + * FeatureInfo displays information about Sentry features in list format. + * For example, we use it in our quick start guides to show helpful information about features + * + * @param features - Array of feature keys to display + * @param type - learnMore shows feature descriptions, findInSentry shows navigation help + */ +export function FeatureInfo({features, type}: FeatureInfoProps) { + return ( +
    + {features.map(key => { + const feature = FEATURE_DATA[key]; + + if (type === 'learnMore') { + return ( +
  • + + {feature.title} + + {key === 'issues' && ' (always enabled)'}: {feature.learnMore} +
    • + ); + } + + return
  • {feature.findInSentry}
    • ; + })} +
+ ); +} diff --git a/src/components/home.tsx b/src/components/home.tsx index 8b0baf39a51116..76c56ac3f6952c 100644 --- a/src/components/home.tsx +++ b/src/components/home.tsx @@ -269,21 +269,21 @@ export async function Home() { > Seer - . Use{' '} + . Have Seer{' '} - AI-powered root cause analysis + fix issues {' '} - in debugging your issues. Use{' '} + by running Autofix to generate fixes, and{' '} - code review + review code changes {' '} - to review your PRs and prevent errors. + before merging PRs.

diff --git a/src/components/navigationData.ts b/src/components/navigationData.ts index 08f40007b1c087..c15e361c5ba652 100644 --- a/src/components/navigationData.ts +++ b/src/components/navigationData.ts @@ -17,7 +17,7 @@ export const conceptsSections: NavSection[] = [ {label: 'Sentry CLI', href: '/cli/'}, ]; -// "More" sub-sections (combines Admin + Security, Legal, & PII) +// "Manage" sub-sections (combines Admin + Security, Legal, & PII) export const moreSections: NavSection[] = [ {label: 'Account Settings', href: '/account/'}, {label: 'Organization Settings', href: '/organization/'}, @@ -34,7 +34,7 @@ export const mainSectionsWithDropdowns: NavSection[] = [ {label: 'Guides', href: '/guides/'}, {label: 'Concepts', href: '/concepts/', dropdown: conceptsSections}, {label: 'API', href: '/api/'}, - {label: 'More', href: '/organization/', dropdown: moreSections}, + {label: 'Manage', href: '/organization/', dropdown: moreSections}, ]; // Main navigation sections as simple links (used in mobile nav, header, sidebar) diff --git a/src/components/sidebar/SidebarMoreLinks.tsx b/src/components/sidebar/SidebarMoreLinks.tsx index 420aa416f32aae..f2ae0c28a955ce 100644 --- a/src/components/sidebar/SidebarMoreLinks.tsx +++ b/src/components/sidebar/SidebarMoreLinks.tsx @@ -26,7 +26,7 @@ export function SidebarMoreLinks() { className="font-bold" /> - {/* Collapsible "More" section - styled to match SidebarLink */} + {/* Collapsible "Manage" section - styled to match SidebarLink */}