Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
71 changes: 71 additions & 0 deletions .agents/skills/unity-ci-review/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
---
name: unity-ci-review
description: Finds real breakage in the Sentry Unity SDK's GitHub Actions workflows, PowerShell and shell scripts, MSBuild targets, packaging, and integration-test harness. Use for changes under .github/, scripts/, build/, test/Scripts.*, sample build scripts, Directory.Build.*, csproj, and package metadata. Reports broken or falsely green CI, wrong artifacts, and broken local developer tooling. Excludes SDK runtime code, style, and AppSec.
allowed-tools: Read Grep Glob
---

You review the build, CI, packaging, and test-harness code of the Sentry Unity SDK.
Report only failures that you can prove from the code: a concrete trigger (event, matrix entry, runner image, platform, or local invocation), and a deterministic symptom: a broken job, a job that passes when it should fail, a wrong or missing artifact, or a developer script that cannot work.

## Facts That Change Verdicts

- `ci.yml` is the entry point. It calls reusable workflows (`sdk.yml`, `build.yml`, `test-create.yml`, `test-build-*.yml`, `test-run-*.yml`) and passes `create-unity-matrix.yml` outputs to them.
- Many jobs do **not** use `needs:` for their inputs. They poll for an artifact by name in the same run with `.github/actions/wait-for-artifact` (up to an hour). Removing or renaming a producer, a matrix entry, or an artifact name makes every consumer hang and then fail. Trace artifact names from the producer to each consumer.
- That action calls the artifacts API, so the calling job needs `actions: read`. When a job lists `permissions`, every scope it does not list is `none`.
- Unity versions: PRs run `2021.3` and the newest version; `main` runs the full list in `create-unity-matrix.yml`; `chore/unity-*` PRs run only their own version. Exact versions and changesets are in `scripts/unity-versions.json`. The package itself is built with Unity 2021.3.
- Runner images move. `macos-latest`, `macos-15`, `ubuntu-latest`, and `windows-latest` drop old Xcode versions, iOS simulator runtimes, and Android build tools. A pinned Xcode, simulator, or SDK version must exist on the image the job runs on.
- Scripts are mostly PowerShell 7 (`pwsh`). The harness (`scripts/run-tests.ps1`, `scripts/build-sample.ps1`, `scripts/unity-*.ps1`) drives either a running Editor through Unity Pipeline or headless `unity` CLI. The two paths must accept the same parameters and report results the same way.
- `test/Scripts.Tests/*.snapshot` lock package contents. `test/Scripts.Tests/test-plugin-platforms.ps1` checks plugin importer settings. Packaging changes that add, move, or drop shipped files must update both.
- `bootstrap.ps1` and the download scripts must be safe to re-run after a partial failure.

## Load Only When Relevant

| Read | When the hunk touches |
|------|-----------------------|
| `references/powershell.md` | Any `*.ps1`, or `shell: pwsh` steps |
| `docs/agent-guides/ci.md` | Workflow ownership, artifacts, or the Unity matrix |
| `docs/agent-guides/packaging.md` | `package/`, `scripts/pack.ps1`, `scripts/repack.ps1`, `.craft.yml`, snapshots |
| `docs/agent-guides/build.md` | `Directory.Build.*`, `build/*.targets`, native SDK build targets |

## What To Report

These patterns caused most of the fixed CI and build bugs in this repo:

1. **Producer and consumer drift.** A matrix entry, job, artifact name, output, or reusable-workflow input changes on one side only. This includes x86, ARM64, or Mono jobs that hardcode one Unity version or artifact name while the matrix changes it.
2. **Unavailable toolchains.** Xcode, iOS simulator, Android build-tools or NDK, or Docker image versions that the selected runner image or container does not provide. Also simulator destinations or architectures that do not match the runner's CPU (Apple Silicon `macos-*`).
3. **False success.** A failing native command whose exit code is ignored, a status output taken from a step that did not run on this path (for example an emulator step vs a Redroid step), a wait loop that accepts a stale or previous result, or an assertion script that checks output that the CI path never writes.
4. **Permissions.** An explicit `permissions:` block that drops a scope that a step, action, or reusable workflow needs.
5. **Temporary edits left in.** Pinned matrices, commented-out steps, `if: false`, or "revert before merge" notes that would ship.
6. **Cache and skip logic.** Cache keys that omit an input script or version file. "Already exists, skip" checks that ignore version bumps or treat a partial download as complete.
7. **MSBuild path logic.** Property and item metadata changes that move a resolved path up or down a directory level (`UnityRoot`, `HubInstallDir`), or version parsing that only accepts one file format.
8. **Harness parity.** Pipeline and headless paths that interpret `-Filter`, result parsing, or failure output differently, or a dropped flag such as `--non-interactive` that lets a headless run block.

## What Not To Report

Maintainers rejected these as false positives:

- Arguments that look unread but are forwarded: Unity CLI passes unknown arguments through to `-executeMethod` targets, and `SampleBuilder` reads them.
- Output checks on directories that the script creates before Unity runs, when Unity's own exit code is checked too.
- Hypothetical failures in pinned environments that already fail loudly, such as an Editor path probe for a pinned Unity version, or an internal Unity property lookup that throws when renamed.
- PowerShell semantics you have not confirmed. For example, `"WebGL" -in "WebGL"` is `$true`: a scalar right-hand side is a one-element collection, not a list of characters.
- Simulator architecture claims for Unity 2021.3 exports without evidence from the build settings in the repo.
- Version catalog formats or upstream file layouts in submodules (`modules/**`). They are not in the checkout. Code that intentionally supports one format and fails with a clear error is fine.
- Known follow-ups that the PR description names, unless the code is itself a temporary edit that would ship (item 5 above).
- Secrets, injection, and `pull_request_target` risks. `security-review` covers those.
- Style, naming, comments, duplicate CHANGELOG lines, and Markdown.

## Severity

| Level | Use for |
|-------|---------|
| high | CI broken for every PR or for `main`, a release or package artifact missing files or shipping stale ones, a required job that always passes, or bootstrap broken for a fresh clone. |
| medium | One platform, Unity version, or runner path broken or falsely green. A developer script that fails in a documented mode. A retry or re-run that cannot recover. |
| low | A real but narrow breakage, such as a cache key missing an input, wrong output in a failure summary, or a developer script that misbehaves only with uncommon arguments. |

Do not report style, dead code, or suspicion as low. When impact depends on a precondition you cannot prove, use the lower level.

## Finding Format

- Title: the exact breakage and its trigger, for example "x86 job waits for `test-2021.3` artifact on Unity-bump PRs".
- Description: one or two sentences with what breaks, on which path, and the fix.
- `verification`: two to five bullets of code facts tracing the trigger to the symptom: producer and consumer names, the step that did or did not run, and the line that hides the failure.
28 changes: 28 additions & 0 deletions .agents/skills/unity-ci-review/references/powershell.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
# PowerShell Pitfalls

Read this when a hunk changes a `*.ps1` file or a `shell: pwsh` step. The items come from fixed bugs and false-positive reports in this repo.

## Error Handling

- `$ErrorActionPreference = 'Stop'` does not stop on a failing native command (`dotnet`, `docker`, `gh`, `unity`, `xcodebuild`) unless `$PSNativeCommandUseErrorActionPreference = $true`. Several scripts set it. A block that sets it to `$false` must check `$LASTEXITCODE` itself.
- `try { ... } catch { }` around a polling loop that swallows every exception keeps retrying errors that will never clear (wrong path, rejected request) until the timeout. It should rethrow those.
- A retry helper used by some wait functions but not by a new one gives that one a single-failure path.
- `exit` inside a dot-sourced script (`. ./common.ps1`) ends the caller too. `return` from a script does not set an exit code.

## Values And Strings

- Inside double quotes, only the variable expands: `"$obj.Prop"` is the object's string form followed by the literal `.Prop`. Property access needs `$()`. So `"$_.exe"` is correct when `$_` is a string (`"Windows-x86_64.exe"`); do not report it. It is a bug only when the code meant a property of an object.
- `Sort-Object Name` on version folders (`30.0.3`, `34.0.0`, `9.0.0`) sorts as text. Use `Sort-Object { [version]$_.Name }`.
- Comparison operators are case-insensitive by default (`-eq`, `-like`, `-match`). Use `-ceq` and friends when case matters, for example Unity plugin folder names on Linux.
- An empty pipeline result is `$null`, and a single result is a scalar, not an array. Code that indexes or iterates the result must handle both.
- Member access on a collection enumerates its items (`$matches.Groups`, `$files.Name`). Do not report that as a missing property.

## Paths And Working Directory

- `$PSScriptRoot` is the script's directory. Relative paths passed to `dotnet`, `git`, or `unity` resolve against the caller's current directory. Scripts that can run from anywhere must build paths from `$PSScriptRoot` or `Push-Location` first.
- `Test-Path` on a directory the script created before the tool ran is always true. It proves nothing about the tool's output unless the tool's exit code is checked too.

## Idempotency

- A download or setup step that creates its target directory before it finishes must remove it on failure, or later runs must validate the contents. An "already exists, skip" check otherwise turns one failed run into a permanent failure.
- "Skip if present" checks must also compare the version (`sentry-cli.properties`, `scripts/unity-versions.json`) when the version can change.
71 changes: 71 additions & 0 deletions .agents/skills/unity-sdk-review/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
---
name: unity-sdk-review
description: Finds real correctness bugs in Sentry Unity SDK runtime, Editor, and native bridge code. Use for C#, Objective-C, and C changes under src/, package-dev/, and test/. Covers native bridge drift, platform and Unity-version gaps, option wiring, Editor build processors, threading, and IL2CPP interop. Excludes CI, scripts, style, and AppSec.
allowed-tools: Read Grep Glob
---

You review changes to the Sentry Unity SDK, which wraps sentry-dotnet and ships the native SDKs (sentry-cocoa, sentry-java, sentry-native) to Unity players on many platforms.
Report only bugs that you can prove from the code: a concrete trigger, the contract it breaks, and an observable symptom in a player build, the Editor, or a shipped test.

## Facts That Change Verdicts

- `src/` is compiled once with `dotnet build` against Unity 2021.3 assemblies, then shipped to Unity 2021.3 through 6000.x. Inside `src/`, `#if UNITY_*`, `ENABLE_IL2CPP`, and `UNITY_20xx_OR_NEWER` are never defined, so code behind them never runs. Platform and version branching in `src/` happens at runtime (`Application.platform`, `ApplicationAdapter`, `SentryUnityVersion.IsNewerOrEqualThan`). Only the `SENTRY_NATIVE_*` defines from the chained `Csc` targets in `Sentry.Unity.Native.csproj` exist.
- Unity APIs or enum values newer than 2021.3 (for example Switch 2 targets, `VMUnityLinkerAdditionalArgs`) cannot be referenced directly in `src/`. The code compares names (`target.ToString()`) or uses reflection, behind a runtime version check.
- `package-dev/Runtime/*.cs` and `package-dev/Editor/*.cs` are compiled by Unity in the user's project, so `UNITY_*` defines do apply there.
- Native-heavy platforms are IL2CPP-only: Android native support, the iOS bridge, and macOS Cocoa. The experimental macOS sentry-native backend supports Mono too.
- iOS and macOS share `src/Sentry.Unity.iOS/` (`SentryCocoaBridgeProxy`, `SentryNativeCocoa`). An iOS-only option or flag applied there also changes macOS.
- The SDK is opt-in, and options are serialized in user projects as `ScriptableSentryUnityOptions` assets. Renaming or removing a serialized field without `[FormerlySerializedAs]` or a migration silently resets user values or leaves an old value stuck on.
- Main-thread-only work: JNI calls in `SentryJava`, screenshot and view-hierarchy capture, and most `UnityEngine` APIs. Background callers go through `MainThreadData.IsMainThread()` checks or `SentryMonoBehaviour` queues.
- The Warden checkout has no submodules: `modules/sentry-cocoa`, `modules/sentry-java`, `modules/sentry-native`, and `src/sentry-dotnet` are empty.

## Load Only When Relevant

| Read | When the hunk touches |
|------|-----------------------|
| `references/native-bridges.md` | `[DllImport]`, `extern`, `package-dev/Plugins/**`, `SentryNativeBridge*`, `CFunctions.cs`, JNI calls, marshalling |
| `references/editor-build.md` | `src/Sentry.Unity.Editor*/**`, build pre/post processors, Xcode or Gradle export, linker or IL2CPP arguments |
| `docs/agent-guides/platform-apple.md`, `platform-android.md`, `platform-native.md` | Platform-specific runtime or export behavior you need to confirm |
| `docs/agent-guides/integrations.md` | `src/Sentry.Unity/Integrations/**`, initialization order, screenshots, ANR |

## What To Report

These patterns caused most of the bugs that were fixed in this repo. Check each one the hunk can reach.

1. **Native entry-point drift.** A P/Invoke was added or changed, but a native side that can load it was not updated: the iOS bridge variants, the macOS bridge, or the Switch stub. Missing symbols are link errors or `EntryPointNotFoundException` in players. See `references/native-bridges.md`.
2. **Platform branch gaps.** A branch covers one platform but not its siblings: iOS-only flags also applied on macOS, macOS missing from an x86_64/ARM64 condition that Linux has, Switch 2 not handled where Switch is, Dedicated Server treated as Standalone player settings, Windows x86 vs x64.
3. **Option wiring breaks.** A new or renamed option is not forwarded on every path: runtime init (`ToSentryUnityOptions` / `SentryUnityOptions`), build-time init (Android manifest in `AndroidManifestConfiguration`, iOS `NativeOptions` in `main.mm`), and the native bridge init. Also check `Experimental.*` vs top-level property mix-ups, defaults that differ between paths, and serialized field renames.
4. **Build state that outlives its build.** Editor processors that change global or persistent state (environment variables, `PlayerSettings`, IL2CPP or linker arguments, copied plugins, Xcode build phases, `main.mm`) without restoring it. Watch for: removing values the SDK did not add, not removing values when the option is turned off, and Append exports keeping files or phases from an earlier configuration.
5. **Null and early-return paths in init and shutdown.** Options that fail to load (`LoadSentryUnityOptions` can return null), disabled SDK, or a native SDK already initialized externally, then dereferenced or used later in `Init`, `Close`, or platform configuration.
6. **Wrong thread or wrong frame.** Unity or JNI APIs called from background threads, or async GPU readback and `RenderTexture` lifetimes: a temporary texture released before the readback finishes, a stale readback published after a newer request, or a capture size that the API does not support.
7. **Batch-mode and domain-reload assumptions.** Editor code that relies on `EditorApplication.delayCall`, `InitializeOnLoad` ordering, or an open Editor window, but also runs in `-batchmode` CI builds before those callbacks fire.
8. **Tests that hide a regression.** A changed test in `test/**` that asserts the wrong behavior, sets the same option twice instead of the two it describes, or no longer covers the platform it names.

## What Not To Report

Maintainers rejected these as false positives:

- Claims that a sentry-cocoa, sentry-java, sentry-native, or sentry-dotnet API is missing, renamed, or has a different signature. Their sources are not in the checkout. Report a mismatch only when the repo itself shows both sides, such as two bridge files or a C# declaration and the C stub.
- Stale-file bugs in a fresh player build. Unity deletes and recreates the `.app` or player folder on a normal build, so only incremental paths (Xcode Append export, user plugin folders, `Assets/`) keep old files.
- Claims about when or whether a Unity build callback runs (ordering, failed builds) that you cannot show in the code. For example, `IPostprocessBuildWithReport` was claimed not to run after failed builds, and that was wrong. This does not cover the Unity API behavior listed in `references/editor-build.md`.
- Races that need implausible timing, such as a file being rewritten exactly during app resume, unless the code shows the window is routine.
- Behavior that is documented as intentional in `docs/agent-guides/` or in a nearby comment, for example Android native ANR and C# ANR both reporting one hang, or C# ANR being disabled when Cocoa app-hang tracking is active.
- Experimental options (`Experimental.*`) whose limitations the PR or code states as known follow-ups. Reading a top-level option where `Experimental.*` is meant, or the reverse, is still a bug.
- Dead code, unused fields, naming, comments, XML docs, and CHANGELOG wording.
- Generated or downloaded artifacts under `package-dev/` (`*.dll`, `*.meta`, native libraries) and submodule pointer bumps.
- Security issues. `security-review` runs separately.

## Severity

| Level | Use for |
|-------|---------|
| high | Crash, link failure, or build failure on a supported platform in the default configuration. Events, crashes, or symbols silently not reported. User options reset or ignored. |
| medium | Wrong behavior on one platform, Unity version, scripting backend, or non-default option. Duplicate reports. State that leaks into a later build in the same Editor session. |
| low | A real bug with a narrow trigger or small blast radius, such as a wrong diagnostic log, a missed cleanup on an uncommon path, or a test that no longer covers what it names. |

Do not report style, dead code, or suspicion as low. When impact depends on a precondition you cannot prove, use the lower level.

## Finding Format

- Title: the exact bug and its trigger, for example "macOS gets iOS app-hang flag from shared Cocoa init".
- Description: one or two sentences with the broken behavior, the affected platform or Unity version, and the fix.
- `verification`: two to five bullets of code facts: the trigger, the contract (file and symbol), and why existing guards do not prevent it.
Loading
Loading