AGENTS.md

1# Coding Agent Instructions
2 
3This file provides guidance to agents when working with code in this repository.
4 
5## Build Commands
6 
7```bash
8# Full build (clean, restore, build, test, package)
9./build.ps1
10 
11# Build only (no tests)
12dotnet build
13 
14# Run all tests
15dotnet test
16 
17# Run a specific test project
18dotnet test ./test/Polly.Core.Tests/Polly.Core.Tests.csproj
19 
20# Run a single test by filter
21dotnet test ./test/Polly.Core.Tests --filter "FullyQualifiedName~CircuitBreakerTests"
22 
23# Run tests for a specific framework
24dotnet test ./test/Polly.Core.Tests --framework net10.0
25 
26# Mutation testing
27./build.ps1 -Target MutationTestsCore
28./build.ps1 -Target MutationTestsExtensions
29./build.ps1 -Target MutationTestsLegacy
30./build.ps1 -Target MutationTestsRateLimiting
31./build.ps1 -Target MutationTestsTesting
32```
33 
34Lint runs in CI via GitHub Actions workflows (actionlint, zizmor, PSScriptAnalyzer).
35 
36Linting for C# is enabled through analyzers configured to run during the build process.
37 
38## Architecture
39 
40Polly is a .NET resilience library. Version 8+ (`Polly.Core`) is a complete redesign; `Polly` (the root package) is the legacy pre-v8 API kept for backwards compatibility.
41 
42### Core abstractions (`src/Polly.Core`)
43 
44- **`ResiliencePipeline`** / **`ResiliencePipeline<T>`** — the main user-facing type. Wraps one or more strategies and executes them in sequence.
45- **`ResiliencePipelineBuilder`** / **`ResiliencePipelineBuilder<T>`** — fluent builder used to compose strategies.
46- **`ResilienceStrategy`** / **`ResilienceStrategy<T>`** — base class for all built-in and custom strategies.
47- **`ResilienceContext`** — per-execution context flowing through the pipeline (cancellation token, properties, result type, etc.).
48 
49### Built-in strategies
50 
51Strategies split into two categories:
52 
53**Reactive** (respond to failures):
54 
55- `RetryResilienceStrategy` — configurable backoff, jitter, attempt limits
56- `CircuitBreakerResilienceStrategy` — state machine: Closed → Open → HalfOpen
57- `FallbackResilienceStrategy` — returns an alternative value/action on failure
58- `HedgingResilienceStrategy` — fires parallel attempts and returns the fastest success
59 
60**Proactive** (prevent overload):
61 
62- `TimeoutResilienceStrategy` — bounds execution duration
63- `RateLimiterResilienceStrategy` (in `Polly.RateLimiting`) — wraps `System.Threading.RateLimiting`
64 
65Each strategy has a corresponding `*Options` class (e.g., `RetryStrategyOptions`) that holds configuration.
66Predicates for which outcomes to handle are declared via the `PredicateBuilder` fluent API.
67 
68### Supporting packages
69 
70- **`Polly.Extensions`** — `IServiceCollection` extensions and telemetry/OpenTelemetry support.
71- **`Polly.Testing`** — `ResiliencePipelineDescriptor` and test helpers; accesses internals via `InternalsVisibleTo`.
72 
73### Multi-targeting
74 
75- `Polly.Core`: targets .NET Framework, .NET and .NET Standard.
76- Test projects: Target all supported versions of .NET plus the latest version of .NET Framework on Windows.
77- Targets for .NET 8 and later support native AoT.
78 
79### Build system
80 
81- **Cake** (bootstrapped by `build.ps1`) orchestrates the full pipeline via `cake.cs`.
82- **Centralized package management**: all NuGet versions in `Directory.Packages.props`.
83- **`Directory.Build.props` / `eng/Common.props`**: shared MSBuild properties (nullable enabled, warnings-as-errors, strong naming via `Polly.snk`, XML doc generation).
84- **`LegacySupport`**: a shared source project injected into `Polly` at compile time via a custom MSBuild target.
85- **MinVer** provides automatic SemVer versioning from git tags.
86 
87### Testing patterns
88 
89- **xUnit** for unit tests; **FsCheck** for property-based/fuzz tests.
90- Test projects access internals via `InternalsVisibleTo` declared in `eng/Library.targets` (brought in via the shared MSBuild imports).
91- `Polly.TestUtils` is a shared utilities project referenced by several test projects.
92- `Polly.AotTest` validates AOT compatibility by publishing a trimmed app.
93- Coverage is collected in CI and uploaded to Codecov.
94 
95## General guidelines
96 
97- Always ensure code compiles with no warnings or errors and tests pass locally before pushing changes.
98- Do not change the public API unless specifically requested.
99- Do not use APIs marked with `[Obsolete]`.
100- Bug fixes should **always** include a test that would fail without the corresponding fix.
101- Do not introduce new dependencies unless specifically requested.
102- Do not update existing dependencies unless specifically requested.
103