Skip to content

Latest commit

 

History

History
141 lines (102 loc) · 4.94 KB

AGENTS.md

File metadata and controls

141 lines (102 loc) · 4.94 KB

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

# 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: <SourceProjectName>.Tests (e.g. Sentry.AspNetCore.Tests)
  • Test naming convention: Method_Context_Expectation (e.g., CaptureEvent_ActiveScope_AppliesScopeData)
  • Snapshot tests use 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 (PowerShell) — require a local nuget pack or CI-built packages

Accepting Verify snapshot changes

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
# 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: <Agent Name> <agent-email-or-noreply@example.com>