From c5d340eb8225d516d297408b2ee688ca9a40dc95 Mon Sep 17 00:00:00 2001 From: James Crosswell Date: Tue, 3 Mar 2026 16:50:00 +1300 Subject: [PATCH 1/3] Initial commit --- AGENTS.md | 141 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 1 + 2 files changed, 142 insertions(+) create mode 100644 AGENTS.md create mode 120000 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..f351bfa811 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,141 @@ +# Agent Instructions + +## Build System + +Uses the .NET SDK (`dotnet` CLI). Key files: +- `Sentry.slnx` — full solution (all platforms/samples)... rarely used directly +- `global.json` — pins .NET SDK and Workload versions +- `Directory.Build.props` / `Directory.Build.targets` — shared MSBuild properties across all projects + +## Solution Filters + +Use solution filters instead of the full `Sentry.slnx`: + +| Filter | Use when | +|--------|----------| +| `SentryNoMobile.slnf` | General development (no Android/iOS build toolchain needed for quicker builds) | +| `Sentry-CI-Build-macOS.slnf` | All macOS projects | +| `Sentry-CI-Build-Windows.slnf` | All Windows projects | +| `Sentry-CI-Build-Linux.slnf` | All Linux projects | + +> Do **not** edit `*.slnf` files directly. They are generated by `scripts/generate-solution-filters.ps1` from `scripts/generate-solution-filters-config.yml`. + +## Essential Commands + +```sh +# Full build (operating system specific - run one only) +dotnet build Sentry-CI-Build-macOS.slnf + +# Quick build (no mobile targets) +dotnet build SentryNoMobile.slnf + +# Build a specific project +dotnet build src/Sentry/Sentry.csproj + +# Run all tests +dotnet test Sentry-CI-Build-macOS.slnf + +# Run all tests (non-mobile) +dotnet test SentryNoMobile.slnf + +# Run tests for a specific project +dotnet test test/Sentry.Tests/Sentry.Tests.csproj + +# Run a single test by name +dotnet test test/Sentry.Tests/ --filter "FullyQualifiedName~CaptureEvent_" + +# Run android device tests (Android emulator must be running) +pwsh scripts/device-test.ps1 android + +# Run ios device tests (iOS simulator must be running) +pwsh scripts/device-test.ps1 ios + +# Format code +dotnet format Sentry.slnx --no-restore --exclude ./modules --exclude ./**/*OptionsSetup.cs --exclude ./test/Sentry.Tests/AttributeReaderTests.cs +``` + +## Repository Layout + +``` +src/ # Source for all Sentry packages +test/ # Test projects (mirror src/ naming: Sentry.X.Tests) +samples/ # Sample applications +benchmarks/ # Performance benchmarks +integration-test/ # Pester-based integration tests (CLI, AOT, runtime, etc.) +modules/ # Native SDK submodules (sentry-native, Ben.Demystifier, etc.) +scripts/ # Build and maintenance scripts +``` + +## Platform Targets + +### Non-mobile (Linux / macOS / Windows) +- Use `SentryNoMobile.slnf` — no extra toolchain needed. +- Targets: `net9.0`, `net10.0`, `netstandard2.0`, `netstandard2.1`, `net462`. + +### Android +- Requires `JAVA_HOME` set and Java installed. +- Built on all platforms (Linux, macOS, Windows). +- `Sentry.Bindings.Android` wraps the native Android SDK. + +### iOS / Mac Catalyst +- **macOS only**. Requires Xcode. +- `Sentry.Bindings.Cocoa` wraps the native Cocoa SDK. +- Device tests run in CI only. + +### MAUI +- Requires MAUI workloads: `sudo dotnet workload restore` (macOS/Linux) or `dotnet workload restore` (Windows). +- Combine mobile toolchain requirements above. + +### Blazor WASM +- `Sentry.AspNetCore.Blazor.WebAssembly.PlaywrightTests` uses Playwright — see `playwright-blazor-wasm.yml` for CI setup. + +### Alpine / musl +- Separate CI pipeline (`alpine.yml`). Do not attempt Alpine-specific builds outside that environment. + +## Testing Conventions + +- Framework: **xUnit** +- Mocking: **nsubstitute** +- Test project naming: `.Tests` (e.g. `Sentry.AspNetCore.Tests`) +- Test naming convention: `Method_Context_Expectation` (e.g., `CaptureEvent_ActiveScope_AppliesScopeData`) +- Snapshot tests use [Verify](https://github.com/VerifyTests/Verify) — commit updated `*.verified.*` files when API surface changes +- Device tests (`Sentry.Maui.Device.TestApp`, `AndroidTestApp`); requires a connected emulator to run locally +- Integration tests in `integration-test/` use [Pester](https://pester.dev/) (PowerShell) — require a local nuget pack or CI-built packages + +### Accepting Verify snapshot changes + +```sh +dotnet test +pwsh ./scripts/accept-verifier-changes.ps1 +# Repeat if needed — dotnet test stops after N failures +``` + +## API Changes + +Public API diffs are stored as Verify snapshot files. After any public API change: +1. Run tests locally — they will fail with a diff +2. Accept the diff: `pwsh ./scripts/accept-verifier-changes.ps1` +3. Commit the updated `*.verified.*` snapshot files + +## Changelog + +- If the change is not user-facing, add `#skip-changelog` to the PR description +- Otherwise generated automatically from [Commit message conventions](https://develop.sentry.dev/engineering-practices/commit-messages/) + +```sh +# Get PR number for current branch +gh pr view --json number -q '.number' +``` + +## Key Conventions + +- New features must be **opt-in** — extend `SentryOptions` or relevant options class with getters/setters +- Maintain **backwards compatibility** — avoid breaking public API without strong justification +- Platform-specific code lives in `src/Sentry/Platforms/` and is conditionally compiled + +## Commit Attribution + +AI commits MUST include: +``` +Co-Authored-By: +``` diff --git a/CLAUDE.md b/CLAUDE.md new file mode 120000 index 0000000000..47dc3e3d86 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file From 555cb12431f0e6721b15ed2412e0e7b471a71b77 Mon Sep 17 00:00:00 2001 From: James Crosswell Date: Tue, 3 Mar 2026 17:00:30 +1300 Subject: [PATCH 2/3] Update version numbers in CONTRIBUTING.md --- CONTRIBUTING.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5a1631e077..b3b80f778b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -25,10 +25,11 @@ For a big feature it's advised to raise an issue to discuss it first. ## Minimal Dependencies * The latest versions of the following .NET SDKs: + - [.NET 10.0](https://dotnet.microsoft.com/download/dotnet/10.0) - [.NET 9.0](https://dotnet.microsoft.com/download/dotnet/9.0) - [.NET 8.0](https://dotnet.microsoft.com/download/dotnet/8.0) - *Technically, you only need the full SDK installation for the latest version (9.0). If you like, you can install the smaller ASP.NET Core Runtime packages for .NET 8.0. However, installing the full SDKs will also give you the runtimes.* + *Technically, you only need the full SDK installation for the latest version. If you like, you can install the smaller ASP.NET Core Runtime packages for older versions. However, installing the full SDKs will also give you the runtimes.* * [`pwsh`](https://github.com/PowerShell/PowerShell#get-powershell) Core version 6 or later on PATH. From bc742fc1e3d0721a6794a269117c4a65f432d067 Mon Sep 17 00:00:00 2001 From: James Crosswell Date: Tue, 3 Mar 2026 17:09:43 +1300 Subject: [PATCH 3/3] Added copilot symlink as well --- .github/copilot-instructions.md | 1 + 1 file changed, 1 insertion(+) create mode 120000 .github/copilot-instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 120000 index 0000000000..be77ac83a1 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1 @@ +../AGENTS.md \ No newline at end of file