@danieljvdm/dev-kit 1.0.2 → 2.0.0

package/skills/sentry/references/releases/suspect-commits.md

@@ -0,0 +1,155 @@
+# Suspect commits, code mappings, and resolve-by-commit
+
+“Which change caused this?”
+is the payoff of releases.
+It is also the part most likely to be half-configured, because it runs on **two
+independent mechanisms** and people assume they’re the same one.
+
+## The two mechanisms
+
+**1. SCM integration + code mappings + blame (the primary path).** With a GitHub or
+GitLab integration installed and valid code mappings, Sentry takes the in-app frames
+from the stack trace and asks the provider for blame on that exact file and line.
+If the most recent commit there is less than a year old, it’s a suspect commit.
+This path does **not** need releases at all.
+
+**2. Release commit data (the fallback).** If mechanism 1 isn’t available or fails,
+Sentry falls back to the commits you associated with the release (`set-commits`) and
+matches files touched by those commits against files in the stack trace.
+This is the path for orgs that don’t want Sentry connecting to their repo — send commit
+metadata explicitly and skip the integration.
+
+Sentry tries mechanism 1 by default and falls back to 2. Which one you’re relying on
+determines what to fix when it’s empty.
+
+## Prerequisites for either mechanism
+
+- **Readable in-app frames.** Both mechanisms work off file paths in the stack trace.
+  Minified or unsymbolicated frames have nothing usable, so source maps (JavaScript) or
+  debug files (native/mobile) come first.
+  That is a separate procedure — say so and get it done before promising suspect
+  commits.
+- **Frames marked in-app.** A trace where everything is vendor code yields no suspect
+  commit.
+- **Events created after setup.** Sentry does not backfill: issues that existed before
+  the integration was connected won’t gain suspect commits.
+
+## Connecting the repository (the step you can’t do)
+
+Installing the SCM integration is an OAuth flow in the Sentry UI. **The agent cannot do
+this** — hand it to the user explicitly rather than leaving it implied:
+
+1. **Settings → Integrations**, pick GitHub or GitLab.
+2. Configure/install it, granting access to the relevant org.
+3. **Add the repository** for this project.
+
+Then `sentry-cli repos list` confirms it from the terminal, and the repo name it prints
+(`owner-name/repo-name`) is the exact string `--commit "repo@sha"` expects.
+
+## Code mappings
+
+A code mapping translates the path prefix in a stack trace to the path prefix in the
+repository. Without one, blame lookups can’t find the file.
+
+**Often already done:** Sentry auto-creates code mappings for JavaScript, Python, Java,
+PHP, Ruby, Go, C#, and Kotlin projects in orgs with the GitHub integration installed.
+Check before building any.
+
+### Deriving the two roots from a real frame
+
+1. Open an event and find an **in-app** frame.
+   Take its `filename` — the `{}` event-JSON view shows `filename` and `abs_path`
+   verbatim if the UI truncates it.
+   Say it’s `src/main.py`.
+2. Find that same file in the repository.
+   Say it lives at `flask/src/main.py` (the repo name itself is not part of the path).
+3. The shared suffix tells you the pair: **Stack Trace Root** `src/`, **Source Code
+   Root** `flask/src/`.
+
+Prefer a non-empty stack trace root.
+Java and other package-name platforms need extra care — the prefix is a package path
+(`io/sentry/android/core`), not a file path.
+
+### In the UI
+
+**Settings → Integrations → [your SCM] → Configurations → Configure → Code Mappings →
+Add Mapping.** Fields: project, repo, default branch (the fallback when commit tracking
+isn’t set up), stack trace root, source code root.
+One mapping per repo per project — a project fed by several repos needs several.
+
+### In bulk, from the CLI
+
+`sentry-cli code-mappings upload` (CLI 3.3.4+) keeps mappings in version control and
+lets CI resync them as the repo layout moves.
+It needs an **organization token with the `org:ci` scope**:
+
+```bash
+sentry-cli code-mappings upload ./mappings.json
+```
+
+```json
+[
+  {
+    "stackRoot": "io/sentry/android/core",
+    "sourceRoot": "sentry-android-core/src/main/java/io/sentry/android/core"
+  },
+  { "stackRoot": "io/sentry", "sourceRoot": "sentry/src/main/java/io/sentry" }
+]
+```
+
+Several mappings may share a `stackRoot` with different `sourceRoot`s — that’s how
+monorepos with a repeated package prefix work.
+Sentry evaluates from most specific to least specific and takes the first that resolves
+to a real file.
+
+Code mappings also power source context and CODEOWNERS-based ownership, so they’re worth
+getting right beyond suspect commits.
+
+## Resolve by commit and by PR
+
+Once commits are associated, the commit message closes the loop:
+
+```
+Prevent empty queries on users
+
+Fixes PROJECT-NAME-12A
+```
+
+Sentry links the commit to the issue immediately, but **does not resolve it yet** — it
+marks the issue resolved when a release containing that commit is created.
+`fixes <SHORT-ID>` in a PR title or description works the same way, resolving when the
+merge commit lands in a release.
+The short ID is at the top of the Issue Details page.
+
+This is the mechanism that closes issues by shipping rather than by a manual status
+change, and it is dead weight without commit association — worth mentioning to the user
+as a reason to finish this setup.
+
+## Auto-assignment
+
+**[Project] → Settings → Ownership Rules → “Auto-assign to suspect commits”** assigns
+new issues to the suspect commit’s author.
+Caveats worth stating up front:
+
+- A manually assigned issue is never reassigned.
+- The author must be a member of the Sentry org, matched by commit email.
+- Assignment can be skipped under high new-issue rates, retried on the next event.
+- On GitHub, “Keep my email address private” in the author’s account settings prevents
+  the match.
+
+## When suspect commits are missing
+
+Work down this list; it’s ordered by how often it’s the cause:
+
+1. The stack trace has no in-app frames, or no stack trace at all.
+2. Code mappings are missing or wrong, so no in-app frame resolves to a repo file.
+3. The issue predates the integration.
+4. Blame on those lines is older than a year.
+5. The SCM integration got disconnected (re-check **Settings → Integrations**).
+6. You’re on the fallback path and `set-commits` never ran, or ran without `patch_set`
+   data — file-level changes are what power suggested assignees.
+
+## Related
+
+- [`ci-pipeline.md`](ci-pipeline.md) — `set-commits`, the fallback mechanism’s input.
+- [`troubleshooting.md`](troubleshooting.md) — the wider failure table.

package/skills/sentry/references/releases/tagging.md

@@ -0,0 +1,131 @@
+# Release tagging (`release` and `environment` on events)
+
+Tagging every event with the version it came from is the SDK half of releases, and the
+half that is pure configuration — one or two `init` options, no CI, no integrations.
+It is worth doing as soon as anything ships to production: without it every event is
+“unknown release” and regression detection, crash-free rates, and suspect commits have
+nothing to attach to.
+
+This file covers the tag itself.
+Creating the release _object_ — associating commits, finalizing it, recording deploys —
+is a CI-side job: [`ci-pipeline.md`](ci-pipeline.md).
+
+## The invariant
+
+**The release name the SDK tags events with must be byte-identical to the name CI
+creates the release under.** If they differ by a `v` prefix, a short vs.
+full SHA, or a trailing build number, you get two releases: one with commits and a
+deploy but no events, and one with events but no commits.
+Nothing errors — the features just stay empty.
+
+Pick the name **once**, in one place, and derive both sides from it.
+In CI that usually means computing it into an environment variable that the build and
+the release step both read.
+This matters even if you are only doing the tagging half today: choose a name a future
+CI step can reproduce exactly.
+
+## Naming rules
+
+Release names are **global per Sentry organization**, not per project.
+Two projects that both ship `1.0.0` will collide into one release, so prefix with
+something project-specific (`checkout-api@1.0.0`, not `1.0.0`).
+
+A name cannot:
+
+- contain newlines, tabs, forward slashes (`/`), or backslashes (`\`)
+- be entirely `.`, `..`, or a space
+- exceed 200 characters
+
+Avoid `1.0.0 (42)` — parentheses are how Sentry _displays_ `foo@1.0+2`, so using them in
+the name itself errors.
+
+## Two naming strategies
+
+**Semantic versioning** — `package@version` or `package@version+build`, e.g.
+`my.project.name@2.3.12+1234`. This is the right choice for anything with a user-facing
+version, and required for mobile, where `package` is the bundle/package id, `version` is
+`CFBundleShortVersionString` / `versionName`, and `build` is `CFBundleVersion` /
+`versionCode`.
+
+**Commit SHA** — the full hash, e.g. `da39a3ee5e6b4b0d3255bfef95601890afd80709`. The
+right choice for continuously-deployed services with no meaningful version number.
+`sentry-cli releases propose-version` derives it for you.
+
+The choice has a side effect worth knowing: Sentry auto-detects whether a project is
+using semver by looking at recent releases, and **regression detection and
+`release:latest` sorting behave differently** between semver and SHA/time-based
+projects. Don’t switch schemes casually mid-project.
+
+## Getting the name onto events
+
+Tagging events is the SDK’s half.
+Most SDKs already produce _some_ release name — the table below is as much about knowing
+what the default is as about overriding it, because a default you didn’t know about is
+exactly what breaks the invariant above.
+
+| Platform                                                                                                               | Default when you set nothing                                                                                                                                                                                         | How to set it explicitly                                                                              |
+| ---------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| JavaScript, bundled (`browser`, `react`, `svelte`, `nextjs`, `react-router-framework`, `tanstack-start`, `cloudflare`) | The Sentry bundler plugin detects a name — Cordova, Heroku, AWS CodeBuild, CircleCI, Xcode, and Gradle environments, otherwise the git `HEAD` commit SHA — and **injects** it into the bundle for the SDK to pick up | `release.name` in the bundler plugin options, or `SENTRY_RELEASE` at build time                       |
+| JavaScript, server-side (`node`, `nestjs`)                                                                             | `SENTRY_RELEASE` from the runtime environment                                                                                                                                                                        | `release` in `Sentry.init`, or set `SENTRY_RELEASE` where the process runs                            |
+| Python                                                                                                                 | `SENTRY_RELEASE`, otherwise an inferred git commit SHA                                                                                                                                                               | `release="myapp@1.0.0"` in `sentry_sdk.init`                                                          |
+| Ruby                                                                                                                   | First match of: `SENTRY_RELEASE`, `KAMAL_VERSION`, git HEAD SHA, a `REVISION` file (Capistrano), `HEROKU_SLUG_COMMIT`                                                                                                | `config.release`                                                                                      |
+| Go                                                                                                                     | `SENTRY_RELEASE`                                                                                                                                                                                                     | `Release` in `sentry.ClientOptions`                                                                   |
+| PHP (incl. Laravel, Symfony)                                                                                           | `SENTRY_RELEASE`                                                                                                                                                                                                     | `release` in `\Sentry\init([...])`, or the framework’s Sentry config                                  |
+| .NET                                                                                                                   | First match of: `SENTRY_RELEASE`, `AssemblyInformationalVersionAttribute`, `AssemblyVersionAttribute` — the latter two yielding `<assembly-name>@<version>`                                                          | `options.Release`                                                                                     |
+| Elixir                                                                                                                 | —                                                                                                                                                                                                                    | `config :sentry, release: "myapp@1.0.0"` in `config/prod.exs`                                         |
+| Android                                                                                                                | `packageName@versionName+versionCode`, e.g. `my.project.name@2.3.12+1234`                                                                                                                                            | `io.sentry.release` meta-data in `AndroidManifest.xml`, or `options.release` if initializing manually |
+| Apple / Cocoa                                                                                                          | `CFBundleIdentifier@CFBundleShortVersionString+CFBundleVersion`                                                                                                                                                      | `options.releaseName`                                                                                 |
+| Flutter / Dart                                                                                                         | `name@version` from `pubspec.yaml`; on Android and iOS `packageName@versionName+versionCode`                                                                                                                         | `options.release`; on Flutter Web pass `SENTRY_RELEASE` via `--dart-define`                           |
+| React Native                                                                                                           | The app version and build number from the native project                                                                                                                                                             | `release` **and** `dist` in `Sentry.init` — read the warning below                                    |
+
+Two traps in that table:
+
+- **Don’t set `release` in `Sentry.init` when a Sentry bundler plugin is in the build.**
+  The plugin injects its own value; a hardcoded `init` release silently wins over it and
+  drifts from the release CI created.
+  Change `release.name` in the plugin options instead.
+- **React Native:** setting a custom `release`/`dist` **disables the automatic source
+  map upload script**, which only recognizes the default values.
+  You then have to upload source maps manually — using the React Native source map
+  procedure. Prefer leaving the defaults alone on React Native unless you have a reason.
+
+The platform’s own SDK reference has the surrounding `init` and build-plugin
+configuration if you need to see where these options sit.
+
+## `dist` — the second half of mobile identity
+
+`dist` disambiguates multiple builds of the same release: same `1.0.0`, build `51` vs
+`52`. It matters on iOS, Android, and React Native, where the store version stays put
+across builds, and it must match between the SDK and any artifact upload for that build.
+Server-side platforms can ignore it.
+
+## Environment
+
+`environment` is a separate tag (`environment` option, or `SENTRY_ENVIRONMENT`) and
+releases need it to be useful: it’s what keeps staging crashes out of production
+crash-free rates, and a deploy is always recorded _into_ an environment.
+Set it alongside the release, not later.
+
+## Release health needs sessions
+
+Crash-free rate and adoption come from **session** data, not errors, so they only appear
+if the SDK sends sessions.
+Session tracking is on by default in most modern SDKs.
+Release health is supported on Android, Apple, Flutter/Dart, browser and Node
+JavaScript, React Native, .NET, PHP, and Python; it is not available on every platform,
+so don’t promise the graphs before checking the platform.
+
+## When the tag isn’t enough
+
+Tagging alone gets you release-scoped filtering, regression detection, and (where
+supported) release health.
+It does **not** get you commits on the release, deploy tracking, suspect commits, or
+`Fixes PROJECT-NAME-12A` resolution — those need a release created in CI with its
+commits associated ([`ci-pipeline.md`](ci-pipeline.md)) and, for suspect commits, an SCM
+integration ([`suspect-commits.md`](suspect-commits.md)). Flag that as the natural
+follow-up rather than implying the tag finished the job.
+
+## Related
+
+- [`../search-query-language.md`](../search-query-language.md) — `release`,
+  `firstRelease`, `release.stage`.

package/skills/sentry/references/releases/troubleshooting.md

@@ -0,0 +1,67 @@
+# When releases are set up but nothing works
+
+Release setup fails **quietly**. Every step below can succeed on its own while producing
+no visible feature, so diagnose by symptom rather than re-running the pipeline and
+hoping.
+
+Start by establishing which half is broken: does a recent event carry the release tag
+you expect, and does a release object with that exact name exist with commits attached?
+Almost every entry here is one of those two answers being no.
+
+## Symptom table
+
+| Symptom                                                                   | Cause                                                                                                                                              | Fix                                                                                                                                                                                                                                                                                      |
+| ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Events show no release, or `release: unknown`                             | The SDK isn’t tagging. Either nothing set it and the platform has no default, or the value is computed at build time and never reached the runtime | Set it per [`tagging.md`](tagging.md); for bundled JS confirm the plugin’s `inject` is on and the built bundle really contains the value                                                                                                                                                 |
+| The release exists in Sentry with commits and a deploy, but **0 events**  | Name mismatch — the classic failure. `v1.2.3` vs `1.2.3`, short vs full SHA, a build number on one side only                                       | Derive both sides from one variable; compare the release list against the `release` tag on a real event, character for character                                                                                                                                                         |
+| Events attribute correctly, but the release has **no commits**            | Commit association never ran, or ran outside the repo                                                                                              | Take the path that matches the build ([`ci-pipeline.md`](ci-pipeline.md)): if a Sentry bundler plugin is already there, fix `release.setCommits` on it rather than adding a second pipeline; otherwise add `set-commits` to CI. Either way it must run where the git repo is checked out |
+| `set-commits --auto` fails, or an “Unable to Fetch Commits” email arrives | The previous release’s commit no longer exists in the repo (squash-merge, rebase, amend, force-push), or CI made a shallow clone                   | `fetch-depth: 0` on checkout; add `--ignore-missing` (`ignoreMissing: true` in the bundler plugin) so it falls back instead of failing                                                                                                                                                   |
+| Commits are associated but there are **no suspect commits**               | Usually the blame path, not the release path                                                                                                       | Work the ordered list in [`suspect-commits.md`](suspect-commits.md) — in-app frames, then code mappings, then integration state                                                                                                                                                          |
+| Suspect commit shows, but no suggested assignee                           | The commit author isn’t in the Sentry org, or their email is hidden                                                                                | Match the commit email to an org member; on GitHub uncheck “Keep my email address private”                                                                                                                                                                                               |
+| Frames are minified/unsymbolicated, so nothing resolves                   | Missing artifacts — a different problem wearing this costume                                                                                       | Upload source maps (JavaScript) or debug files (native/mobile); that procedure is separate from releases                                                                                                                                                                                 |
+| “Resolve in next release” never resolves anything                         | The release was never **finalized**, so Sentry has no anchor for “next”                                                                            | Call `sentry-cli releases finalize` at deploy time (or `--finalize` on `new`)                                                                                                                                                                                                            |
+| `Fixes PROJECT-NAME-12A` links the commit but the issue stays unresolved  | Working as designed until a release **containing that commit** is created                                                                          | Ensure the post-merge release runs `set-commits` and includes the merge commit                                                                                                                                                                                                           |
+| Release health / crash-free rate is empty                                 | No sessions: session tracking disabled, no `environment` set, or the platform doesn’t support release health                                       | Confirm platform support and session tracking in [`tagging.md`](tagging.md)                                                                                                                                                                                                              |
+| Production crash-free rate looks terrible                                 | Staging events are landing in the same environment                                                                                                 | Set `environment` per build; record deploys into the right environment                                                                                                                                                                                                                   |
+| No deploys listed on the release                                          | `deploys new` never ran — creating a release does not create a deploy                                                                              | Add the deploy step; verify with `sentry-cli deploys list --release "$VERSION"`                                                                                                                                                                                                          |
+| Two releases appear for one build                                         | A bundler plugin **and** a hand-rolled `sentry-cli` pipeline both ran, with different names                                                        | Keep one. If the plugin is in the build, configure it rather than adding CLI steps                                                                                                                                                                                                       |
+| Nothing uploads and nothing errors                                        | Missing `SENTRY_AUTH_TOKEN` — most tools skip silently                                                                                             | [`../auth-token.md`](../auth-token.md), including how to check for presence without printing the value                                                                                                                                                                                   |
+| `403` on `code-mappings upload`                                           | Token lacks the `org:ci` scope                                                                                                                     | Issue an org token with `org:ci`                                                                                                                                                                                                                                                         |
+| One project’s release swallowed another’s events                          | Release names are **global per organization**                                                                                                      | Prefix with the project (`checkout-api@1.0.0`)                                                                                                                                                                                                                                           |
+
+## Checking from the terminal
+
+```bash
+sentry-cli repos list                              # is an SCM integration connected, and under what name
+sentry-cli deploys list --release "$VERSION"        # did the deploy get recorded
+```
+
+## Checking with the MCP
+
+The two halves need two different tools, and using the wrong one is how a mismatch gets
+missed.
+
+**The tagging half** — the release fields, but they aren’t interchangeable between
+tools:
+
+- `release:<exact-name>` — works on both.
+  Do events exist under the name CI created?
+  Zero hits here, combined with a release object that _does_ have commits, is the
+  mismatch signature.
+- `firstRelease:<name>` — did this issue first appear in that release (regression
+  detection working). **`search_issues` only.** On `search_events` it is silently
+  rewritten to `release:`, which returns plausible hits for a different question — check
+  `## Executed Search` if you’re unsure what ran.
+
+The grammar is in [`../search-query-language.md`](../search-query-language.md).
+
+**The CI half** — `get_release_details` for that exact version reports the commits and
+deploys hanging off the release.
+An event search can never answer this; it only ever sees the tag.
+It’s a catalog tool, so reach it via `search_sentry_tools` / `execute_sentry_tool` if it
+isn’t exposed directly.
+
+## Related
+
+- [`tagging.md`](tagging.md) · [`ci-pipeline.md`](ci-pipeline.md) ·
+  [`suspect-commits.md`](suspect-commits.md)