Skip to content

Commit 2079493

Browse files
jamescrosswelljamescrosswell
authored
feat: Add AGENTS.md (#4974)
* Initial commit * Update version numbers in CONTRIBUTING.md * Added copilot symlink as well
1 parent e7c25cc commit 2079493

File tree

4 files changed

+145
-1
lines changed

4 files changed

+145
-1
lines changed

‎.github/copilot-instructions.md‎

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

‎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

‎CONTRIBUTING.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,10 +25,11 @@ For a big feature it's advised to raise an issue to discuss it first.
2525
## Minimal Dependencies
2626

2727
* The latest versions of the following .NET SDKs:
28+
- [.NET 10.0](https://dotnet.microsoft.com/download/dotnet/10.0)
2829
- [.NET 9.0](https://dotnet.microsoft.com/download/dotnet/9.0)
2930
- [.NET 8.0](https://dotnet.microsoft.com/download/dotnet/8.0)
3031

31-
*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.*
32+
*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.*
3233

3334
* [`pwsh`](https://github.com/PowerShell/PowerShell#get-powershell) Core version 6 or later on PATH.
3435

0 commit comments

Comments
 (0)