Skip to content

Commit c5d340e

Browse files
jamescrosswelljamescrosswell
committed
Initial commit
1 parent caddbd2 commit c5d340e

File tree

2 files changed

+142
-0
lines changed

2 files changed

+142
-0
lines changed

‎AGENTS.md‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
# Agent Instructions
2+
3+
## Build System
4+
5+
Uses the .NET SDK (`dotnet` CLI). Key files:
6+
- `Sentry.slnx` — full solution (all platforms/samples)... rarely used directly
7+
- `global.json` — pins .NET SDK and Workload versions
8+
- `Directory.Build.props` / `Directory.Build.targets` — shared MSBuild properties across all projects
9+
10+
## Solution Filters
11+
12+
Use solution filters instead of the full `Sentry.slnx`:
13+
14+
| Filter | Use when |
15+
|--------|----------|
16+
| `SentryNoMobile.slnf` | General development (no Android/iOS build toolchain needed for quicker builds) |
17+
| `Sentry-CI-Build-macOS.slnf` | All macOS projects |
18+
| `Sentry-CI-Build-Windows.slnf` | All Windows projects |
19+
| `Sentry-CI-Build-Linux.slnf` | All Linux projects |
20+
21+
> Do **not** edit `*.slnf` files directly. They are generated by `scripts/generate-solution-filters.ps1` from `scripts/generate-solution-filters-config.yml`.
22+
23+
## Essential Commands
24+
25+
```sh
26+
# Full build (operating system specific - run one only)
27+
dotnet build Sentry-CI-Build-macOS.slnf
28+
29+
# Quick build (no mobile targets)
30+
dotnet build SentryNoMobile.slnf
31+
32+
# Build a specific project
33+
dotnet build src/Sentry/Sentry.csproj
34+
35+
# Run all tests
36+
dotnet test Sentry-CI-Build-macOS.slnf
37+
38+
# Run all tests (non-mobile)
39+
dotnet test SentryNoMobile.slnf
40+
41+
# Run tests for a specific project
42+
dotnet test test/Sentry.Tests/Sentry.Tests.csproj
43+
44+
# Run a single test by name
45+
dotnet test test/Sentry.Tests/ --filter "FullyQualifiedName~CaptureEvent_"
46+
47+
# Run android device tests (Android emulator must be running)
48+
pwsh scripts/device-test.ps1 android
49+
50+
# Run ios device tests (iOS simulator must be running)
51+
pwsh scripts/device-test.ps1 ios
52+
53+
# Format code
54+
dotnet format Sentry.slnx --no-restore --exclude ./modules --exclude ./**/*OptionsSetup.cs --exclude ./test/Sentry.Tests/AttributeReaderTests.cs
55+
```
56+
57+
## Repository Layout
58+
59+
```
60+
src/ # Source for all Sentry packages
61+
test/ # Test projects (mirror src/ naming: Sentry.X.Tests)
62+
samples/ # Sample applications
63+
benchmarks/ # Performance benchmarks
64+
integration-test/ # Pester-based integration tests (CLI, AOT, runtime, etc.)
65+
modules/ # Native SDK submodules (sentry-native, Ben.Demystifier, etc.)
66+
scripts/ # Build and maintenance scripts
67+
```
68+
69+
## Platform Targets
70+
71+
### Non-mobile (Linux / macOS / Windows)
72+
- Use `SentryNoMobile.slnf` — no extra toolchain needed.
73+
- Targets: `net9.0`, `net10.0`, `netstandard2.0`, `netstandard2.1`, `net462`.
74+
75+
### Android
76+
- Requires `JAVA_HOME` set and Java installed.
77+
- Built on all platforms (Linux, macOS, Windows).
78+
- `Sentry.Bindings.Android` wraps the native Android SDK.
79+
80+
### iOS / Mac Catalyst
81+
- **macOS only**. Requires Xcode.
82+
- `Sentry.Bindings.Cocoa` wraps the native Cocoa SDK.
83+
- Device tests run in CI only.
84+
85+
### MAUI
86+
- Requires MAUI workloads: `sudo dotnet workload restore` (macOS/Linux) or `dotnet workload restore` (Windows).
87+
- Combine mobile toolchain requirements above.
88+
89+
### Blazor WASM
90+
- `Sentry.AspNetCore.Blazor.WebAssembly.PlaywrightTests` uses Playwright — see `playwright-blazor-wasm.yml` for CI setup.
91+
92+
### Alpine / musl
93+
- Separate CI pipeline (`alpine.yml`). Do not attempt Alpine-specific builds outside that environment.
94+
95+
## Testing Conventions
96+
97+
- Framework: **xUnit**
98+
- Mocking: **nsubstitute**
99+
- Test project naming: `<SourceProjectName>.Tests` (e.g. `Sentry.AspNetCore.Tests`)
100+
- Test naming convention: `Method_Context_Expectation` (e.g., `CaptureEvent_ActiveScope_AppliesScopeData`)
101+
- Snapshot tests use [Verify](https://github.com/VerifyTests/Verify) — commit updated `*.verified.*` files when API surface changes
102+
- Device tests (`Sentry.Maui.Device.TestApp`, `AndroidTestApp`); requires a connected emulator to run locally
103+
- Integration tests in `integration-test/` use [Pester](https://pester.dev/) (PowerShell) — require a local nuget pack or CI-built packages
104+
105+
### Accepting Verify snapshot changes
106+
107+
```sh
108+
dotnet test
109+
pwsh ./scripts/accept-verifier-changes.ps1
110+
# Repeat if needed — dotnet test stops after N failures
111+
```
112+
113+
## API Changes
114+
115+
Public API diffs are stored as Verify snapshot files. After any public API change:
116+
1. Run tests locally — they will fail with a diff
117+
2. Accept the diff: `pwsh ./scripts/accept-verifier-changes.ps1`
118+
3. Commit the updated `*.verified.*` snapshot files
119+
120+
## Changelog
121+
122+
- If the change is not user-facing, add `#skip-changelog` to the PR description
123+
- Otherwise generated automatically from [Commit message conventions](https://develop.sentry.dev/engineering-practices/commit-messages/)
124+
125+
```sh
126+
# Get PR number for current branch
127+
gh pr view --json number -q '.number'
128+
```
129+
130+
## Key Conventions
131+
132+
- New features must be **opt-in** — extend `SentryOptions` or relevant options class with getters/setters
133+
- Maintain **backwards compatibility** — avoid breaking public API without strong justification
134+
- Platform-specific code lives in `src/Sentry/Platforms/` and is conditionally compiled
135+
136+
## Commit Attribution
137+
138+
AI commits MUST include:
139+
```
140+
Co-Authored-By: <Agent Name> <agent-email-or-noreply@example.com>
141+
```

‎CLAUDE.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
AGENTS.md

0 commit comments

Comments
 (0)