Merge remote-tracking branch 'origin/master' into sentry-in-ai

* origin/master:
  docs(sdk): coordination and maintenance standards (#16463)
  docs(sdk): add spec format components and migrate check-ins (#16461)
  docs(sdk): repository and documentation standards (#16462)
  docs(sdk): Add issue saved replies and simplify CopyableCard (#16459)
  docs(sdk): add review & ci standard (#16458)
  fix(unity): correct lifecycle breadcrumbs docs (#16456)
  docs(sdk): add code quality standard (#16455)
  docs(sdk): migrate releases process to playbook and standard (#16447)
  docs(sdk): merge basics.mdx into overview.mdx (#16446)
  docs(sdk): remove old triaging process page (#16448)
  docs(dart): Update stacktrace info for the logging integration (#16401)
  docs(dart): Fix user attributes gated behind `sendDefaultPii` (#16407)
  feat(playstation): Add symbols documentation for dumps (#16454)
  feat(develop-docs): Restore Sentry Voice guidelines page (#16453)

# Conflicts:
#	app/[[...path]]/page.tsx

Author: codyde

.gitignore

@@ -91,6 +91,9 @@ public/mdx-images/*
 public/og-images/*
 !public/og-images/README.md
 
+# Ignore LLM plans
+/docs/plans/
+
 # yalc
 .yalc
 yalc.lock

app/[[...path]]/page.tsx

@@ -11,6 +11,9 @@ import {Home} from 'sentry-docs/components/home';
 import {Include} from 'sentry-docs/components/include';
 import {PageLoadMetrics} from 'sentry-docs/components/pageLoadMetrics';
 import {PlatformContent} from 'sentry-docs/components/platformContent';
+import {SpecChangelog} from 'sentry-docs/components/specChangelog';
+import {isSpecStatus} from 'sentry-docs/components/specConstants';
+import {SpecMeta} from 'sentry-docs/components/specMeta';
 import {
   DocNode,
   getCurrentPlatformOrGuide,
@@ -47,25 +50,58 @@ export async function generateStaticParams() {
 export const dynamicParams = false;
 export const dynamic = 'force-static';
 
-const mdxComponentsWithWrapper = {
-  ...mdxComponents(
-    {Include, PlatformContent},
-    ({children, frontMatter, nextPage, previousPage}) => (
+function mdxComponentsForFrontMatter(frontMatter: Record<string, unknown>) {
+  const specOverrides: Record<string, unknown> = {};
+  const changelog = Array.isArray(frontMatter.spec_changelog)
+    ? (frontMatter.spec_changelog as Array<Record<string, unknown>>)
+        .filter(
+          entry => entry.version != null && entry.date != null && entry.summary != null
+        )
+        .map(entry => ({
+          version: String(entry.version),
+          date:
+            entry.date instanceof Date
+              ? entry.date.toISOString().split('T')[0]
+              : String(entry.date),
+          summary: String(entry.summary),
+        }))
+    : undefined;
+  if (changelog && changelog.length > 0) {
+    specOverrides.SpecChangelog = function () {
+      return <SpecChangelog changelog={changelog} />;
+    };
+  }
+  if (frontMatter.spec_version && isSpecStatus(frontMatter.spec_status)) {
+    const boundProps = {
+      version: String(frontMatter.spec_version),
+      status: frontMatter.spec_status,
+    };
+    specOverrides.SpecMeta = function () {
+      return <SpecMeta {...boundProps} />;
+    };
+  }
+  return mdxComponents(
+    {Include, PlatformContent, ...specOverrides},
+    ({children, frontMatter: fm, nextPage, previousPage}) => (
       <DocPage
-        frontMatter={frontMatter}
+        frontMatter={fm}
         nextPage={nextPage}
         previousPage={previousPage}
-        fullWidth={frontMatter.fullWidth}
+        fullWidth={fm.fullWidth}
       >
         {children}
       </DocPage>
     )
-  ),
-};
+  );
+}
 
 function MDXLayoutRenderer({mdxSource, ...rest}) {
   const MDXLayout = useMemo(() => getMDXComponent(mdxSource), [mdxSource]);
-  return <MDXLayout components={mdxComponentsWithWrapper} {...rest} />;
+  const components = useMemo(
+    () => mdxComponentsForFrontMatter(rest.frontMatter || {}),
+    [rest.frontMatter]
+  );
+  return <MDXLayout components={components} {...rest} />;
 }
 
 export default async function Page(props: {params: Promise<{path?: string[]}>}) {

develop-docs/frontend/sentry-voice.mdx

@@ -0,0 +1,105 @@
+---
+title: Content & Voice
+sidebar_order: 25
+---
+
+There are two different ways to write copy within the Sentry app. There's normal **plain speech**, and there's our branded, personality-rich "**Sentry Voice**." Sentry Voice is a little snarky (but never mean), jokey, and quick-witted. The jokes should be simple, if it needs explanation, it isn't gonna work.
+
+Generally, you should default to plain and clear speech in the product. This includes page names, table headings, widgets, CTAs, Seer responses, and descriptive text. Occasionally it will be appropriate to use the "Sentry Voice," like on 404 pages, new product announcements and other areas that don't directly interfere with someone's workflow. Within the product, assume users are frustrated and in a hurry — above all our goal is to make sure they can find what they are looking for quickly, and explain what is happening clearly.
+
+### Examples
+
+**Plain speech**
+
+> Issues are groups of errors that have a similar stacktrace. Set an alert for new issues, when an issue changes state, frequency of errors, or users affected by an issue.
+
+**Sentry Voice**
+
+> 404, Page not found. We looked. And then we gave up. [Button: *Return to a Real Page*]
+
+> Sentry Rollback is here. Forgot everything you did this year? Don't worry—we have the receipts. Take a look back at your 2024 with Sentry.
+
+## When to Use "Sentry Voice" vs. Plain Speech
+
+**Do** use Sentry Voice for…
+
+- Designing a new product tour
+- Descriptions in the "What's New" feature
+- Adding personality to a long (30+ second) loading state
+- High level loading states (404, 500, This Page Does Not Exist)
+- Onboarding, but use it sparingly. Make sure it is not getting in the way of helping users actually configure their account.
+- Empty states, also case-dependent. These should always have an actionable first line, but can have a snarky heading or second sentence.
+
+**Don't** use Sentry Voice (and use plain speech instead) for…
+
+- Product UI. This includes page titles, labels, filters, search, table headings, CTAs, toasts, alerts, and callouts.
+- Non-marketing emails. Emails generated by weekly summaries or alerts should be straightforward and direct.
+- Settings pages. These are already complicated enough.
+- Documentation. Users are here to find information quickly and they need to be easily searchable.
+
+## Writing in "Sentry Voice"
+
+You should not be using this voice within regular workflows, or when someone is trying to complete a task. Even when using Sentry Voice make sure to front-load main information, and not let personality get in the way of content. For example in an error message, make sure the first few words of the body capture the problem first (_404 Page not found_. We looked. And then we gave up.).
+
+Here are three things to keep in mind when writing with personality on behalf of Sentry:
+
+1. **We have empathy for our users**: they should feel understood and like we appropriately grasp the gravity of their situation. Whatever they're going through, we get it. When we are snarky we are snarky towards the situation they are in, not towards the user themself.
+2. **We're self-aware**: look, we know were not curing cancer over here. We help developers, but we're not changing the world. Don't make bold claims with aspirational copy.
+3. **We have fun**: this stuff is dry, so look for opportunity to have fun with the copy (while keeping everything above in mind).
+4. **If you feel confused or unsure where and how to use Sentry Voice, ask our in-house copy writer in the `#discuss-design` Slack channel.**
+
+<Alert>
+  If you're looking for more information, this was modified from the <a href="https://brand.getsentry.com/document/5#/style-guides/writing-style-guide">brand identity writing style guide</a>.
+</Alert>
+
+## General Copywriting Guidelines
+
+**Keep it simple**&mdash;avoid jargon and don't get fancy. If you are referencing new words or concepts explain them or link out to documentation.
+
+**Be informative**. Always provide straightforward, accurate information, we don't manipulate people into believing we're anything more than we actually are.
+
+**Use American spelling**. Apologies to our colleagues who prefer the Queen's English.
+
+**Avoid emotional punctuation**; for example use `!` sparingly.
+
+**Don't use weird punctuation** like the interrobang `‽`. Not everyone shares your affinity for esoteric glyphs.
+
+**Be consistent.** Reference our [Icons + CTA Copy Table](https://sentry.sentry.io/stories/core/button#icons) to make sure you are using agreed upon terms in CTA Buttons.
+For example, Dashboards, Views, Monitors, and Automations are always "Edited" and use the pencil icon.
+When a user is creating a new Dashboard, View, or Monitor, the language should always be "Create [Object]" with a plus icon.
+
+**Use punctuation thoughtfully**. If you don't know how to use colons `:` or semicolons `;` it is better not to try. Alternatively, ask a copywriter for help.
+
+<Alert>
+  <strong>A brief aside on dashes</strong>
+
+  Hyphens, the `-` or `&hyphen;` symbol, are used to join words together or write compound numbers (_sixty-five_, _self-serve_).
+
+  En-dashes, the `–` or `&ndash;` symbol, are most commonly used for time ranges (_2020–2022_, _September 1–September 3)_.
+  Insert these without a space on either side.
+
+  Em-dashes, the `—` or `&mdash;` symbol, are the longest of the three and act more like true punctuation.
+  You can use these in place of a comma or parentheses, or to indicate when a sentence is taking a new turn.
+  (_We want to introduce users to Seer&mdash;a new name for our old AI product&mdash;which we have rebranded this month_.)
+
+  For additional information, refer to <a href="https://www.merriam-webster.com/grammar/em-dash-en-dash-how-to-use">Merriam Webster</a>.
+</Alert>
+
+## Use Title Case for Titles and Headings
+
+Within the app we use title case for all headings, CTAs and labels (including: chart titles, table, chart axes, chart legends, table titles, table column headers, form fields labels, anything in the sidebar).
+This means the first letter of every word is capitalized, except for conjunctions and "minor" words.
+
+This is true for `<Heading>`, as well as all CTAs, table headers, and default widgets. As a rule, we **never** use all caps in the product. If you see `text-transform: uppercase` anywhere, you should remove it.
+
+**Examples**
+
+> Last Seen (column header)
+
+> Save As… (CTA Button)
+
+> Errors and Outages (sidebar item & H1)
+
+> Most Frozen Frames (default widget title)
+
+Not sure how to convert something? Refer to [capitalizemytitle.com](https://capitalizemytitle.com/) for a quick gut check.

develop-docs/sdk/foundations/overview.mdx

@@ -4,6 +4,10 @@ description: What an SDK is, what it does, and how end-users interact with it.
 sidebar_order: 1
 ---
 
+<Alert>
+  This document uses key words such as "MUST", "SHOULD", and "MAY" as defined in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) to indicate requirement levels.
+</Alert>
+
 ## Writing an SDK
 
 At its core an SDK is a set of utilities for capturing data about an exceptional state in an application. Given this data, it then builds and sends a JSON payload to the Sentry server.
@@ -89,3 +93,55 @@ a basic message or exception:
 
 -   `Sentry.captureMessage(message)`
 -   `Sentry.captureException(exception)`
+
+## Run a Local Relay
+
+You do not need a local Sentry instance for SDK development, but you will want to run a local
+[relay](https://docs.sentry.io/product/relay/).  The reason for this is that Sentry's
+main ingestion endpoint is not intended for development but for high throughput
+production use.  What this means is that a lot of the event processing is happening
+after the event has already been accepted by the system so you won't be able to see
+errors when sending the HTTP request.
+
+If you haven't used relay yet, have a look at the [getting started](https://docs.sentry.io/product/relay/getting-started/)
+docs for relay.  Once installed you will want to turn up the log level in your
+`.relay/config.yml` file:
+
+```yaml
+logging:
+  level: trace
+```
+
+Make sure your relay is running whenever you're doing development:
+
+```shell
+relay run
+```
+
+When sending events just substitute `orgXXX.ingest.sentry.io` with `localhost:3000` or
+whichever port you chose.  Also note that a local relay will out of the box
+be available via HTTP only so don't try to send HTTPS requests there.
+
+## Consult Existing SDKs
+
+While we're trying to keep the docs up to date about all important things, it's usually
+a good idea to refer to already existing Sentry SDKs for input.  In particular the
+transport design is not part of the documentation but generally quite similar between
+SDKs.
+
+## Define Conventions and Types Before Shipping
+
+Before shipping new or changed SDK behavior, make sure the relevant definitions exist outside your SDK first:
+
+- **Semantic conventions:** New or changed attributes **MUST** first be defined in [sentry-conventions](https://github.com/getsentry/sentry-conventions/). If the convention you need doesn't exist yet, open a PR there to propose it. Only after the convention has been merged should you implement it in an SDK. This ensures all SDKs use consistent naming and semantics.
+
+  The merge process for sentry-conventions PRs:
+  1. Open a PR with the proposed convention.
+  2. Get an approval from at least one code owner.
+  3. Wait at least 3 business days after the first approval to give other code owners a chance to review.
+
+- **Context types:** Any newly added [context](https://develop.sentry.dev/sdk/foundations/data-model/event-payloads/contexts/) **SHOULD** also be typed out in [Relay](https://github.com/getsentry/relay/tree/master/relay-event-schema/src/protocol/contexts) so that the schema stays in sync with what SDKs emit.
+
+## Join us on Discord
+
+You can reach out to Sentry open source contributors and talk with other SDK maintainers on the [Sentry Discord server](https://discord.gg/sentry).

develop-docs/sdk/getting-started/playbooks/setting-up-release-infrastructure.mdx

@@ -0,0 +1,108 @@
+---
+title: Setting Up Release Infrastructure
+---
+
+## Steps
+
+#### 1. Create the Initial Tag
+
+A tag must exist for the first commit of the repository due to a [craft limitation](https://github.com/getsentry/craft/issues/342). Tag the first commit before any meaningful history so the first changelog includes useful context.
+
+```bash
+git tag 0.0.0 "$(git log -1 --reverse --format=%h)"
+git push origin --tags
+```
+
+#### 2. Set Up CI for Release Branches
+
+Ensure the repository's CI responds to `release/**` branches and produces a named artifact. See [sentry-python's build workflow](https://github.com/getsentry/sentry-python/blob/master/.github/workflows/build.yml) for an example.
+
+#### 3. Configure Craft (`.craft.yml`)
+
+Create a `.craft.yml` with targets for your package registry and GitHub releases:
+
+```yaml
+minVersion: 0.28.1
+targets:
+  - name: pypi
+  - name: github
+```
+
+See the [Craft configuration docs](https://craft.sentry.dev/configuration/) for all available targets and options.
+
+#### 4. Add Version Bump Script (`scripts/bump-version.sh`)
+
+Craft invokes this script when bumping the version. The script receives the old version as `$1` and the new version as `$2`:
+
+```bash
+#!/usr/bin/env bash
+set -euxo pipefail
+
+sed -i "s/^version =.*/version = $2/" setup.cfg
+```
+
+For a real-world example with multiple version locations, see [sentry-python's bump-version.sh](https://github.com/getsentry/sentry-python/blob/master/scripts/bump-version.sh).
+
+#### 5. Add Release Workflow (`.github/workflows/release.yml`)
+
+This workflow triggers releases from the GitHub UI. It uses `vars.SENTRY_RELEASE_BOT_CLIENT_ID` and `secrets.SENTRY_RELEASE_BOT_PRIVATE_KEY` which are available to repositories in the `getsentry` org automatically. These are needed because [GitHub prevents `GITHUB_TOKEN` from triggering downstream workflows](https://docs.github.com/en/actions/reference/events-that-trigger-workflows).
+
+```yaml
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: Version to release
+        required: false
+      force:
+        description: Force a release even when there are release-blockers (optional)
+        required: false
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    name: "Release a new version"
+    steps:
+      - name: Get auth token
+        id: token
+        uses: actions/create-github-app-token@5d869da34e18e7287c1daad50e0b8ea0f506ce69 # v1.11.0
+        with:
+          app-id: ${{ vars.SENTRY_RELEASE_BOT_CLIENT_ID }}
+          private-key: ${{ secrets.SENTRY_RELEASE_BOT_PRIVATE_KEY }}
+      - uses: actions/checkout@v6
+        with:
+          token: ${{ steps.token.outputs.token }}
+          fetch-depth: 0
+      - name: Prepare release
+        uses: getsentry/craft@v2
+        env:
+          GITHUB_TOKEN: ${{ steps.token.outputs.token }}
+        with:
+          version: ${{ github.event.inputs.version }}
+          force: ${{ github.event.inputs.force }}
+```
+
+For full details on all available options including auto-versioning, changelog preview, merge targets, and multiple craft configs, see [Craft's GitHub Actions documentation](https://craft.sentry.dev/github-actions/). Repositories outside the `getsentry` org can use the simpler [reusable workflow](https://craft.sentry.dev/github-actions/#option-1-reusable-workflow-recommended) which handles token management automatically via `secrets: inherit`.
+
+#### 6. Set Repository Permissions
+
+Give the `engineering` team write access via your repository's settings page: `https://github.com/getsentry/REPONAME_HERE/settings/access`
+
+#### 7. Create Branch Ruleset
+
+Download the [default ruleset template](/json/Default_ruleset.json). Import it at `https://github.com/getsentry/REPONAME_HERE/settings/rules` via **New ruleset** > **Import a ruleset**. You can adjust settings but do not remove the App in the Bypass List.
+
+#### 8. Cut Your First Release
+
+Navigate to the Actions tab, locate the Release workflow, and trigger it. This creates an [issue in `getsentry/publish`](https://github.com/getsentry/publish/issues) which requires an approver to add a label before artifacts are published.
+
+For the ongoing release process after setup, see "Cutting a release" (wip).
+
+## Referenced Standards
+
+- [Version format](/sdk/getting-started/standards/release-versioning#version-format)
+- [Release tooling](/sdk/getting-started/standards/release-versioning#release-tooling)
+- Release gating criteria (wip)
+- Rollback procedures (wip)