# Repository workflow
- **New pull requests:** branch from `dotnet/orleans`'s `main`, push to the authenticated user's fork, and open the PR against `dotnet/orleans`.
- **Existing contributor pull requests:** when maintainer edits are enabled and authentication permits, push updates to the PR author's head fork and branch.
- **Every push:** run `git remote -v` and verify the destination by URL. Use the authenticated user's fork for new work or the PR author's fork for an existing PR; never rely on remote names or hard-code `origin`.
- Never push a feature branch to a remote whose URL points to `github.com/dotnet/orleans`, over HTTPS or SSH. Delete it immediately if this happens accidentally.
- After rebasing a PR branch, use `--force-with-lease`, never `--force`.
- Use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) for commits and PR titles. Update nonconforming PR titles during review.
- When reviewing changes, check whether corresponding documentation or sample updates are needed in the `/docs` and `/samples` directories.
- Keep PR descriptions focused on the problem, solution, and rationale; omit test-command sections.
## Build, test, and style commands
* The repo builds with the .NET SDK from `global.json` (`10.0.203`, roll-forward `major`). Do not edit `global.json` unless explicitly asked.
* Build the solution with `dotnet build Orleans.slnx -bl`. CI uses this form and uploads the binlog.
* On Windows, `.\Build.cmd` runs `build.ps1`, which restores, builds, and packs `Orleans.slnx`, writes restore/build/pack binlogs, and outputs packages under `Artifacts\<Configuration>`. Set `BuildConfiguration=Release` to build release artifacts.
* Run tests with `dotnet test Orleans.slnx --framework net10.0 -- -parallel none -noshadow`. CI also runs `net8.0`; source projects default to `net8.0;net10.0`.
* Run a category with `dotnet test Orleans.slnx --framework net10.0 --filter "Category=BVT" -- -parallel none -noshadow`. Common categories are `BVT`, `SlowBVT`, `Functional`, and provider-specific categories such as `Redis`, `Cassandra`, `SqlServer`, `Azure`, `AWS`, and `Streaming`.
* Run one test with `dotnet test test\Orleans.Core.Tests\Orleans.Core.Tests.csproj --framework net10.0 --filter "FullyQualifiedName~MyTestClass.MyTestMethod" -- -parallel none -noshadow`.
* `.\Test.cmd` runs the scripted Windows test subset using the default `Category=BVT|Category=SlowBVT` filter. `.\TestAll.cmd` sets `Category=BVT|Category=SlowBVT|Category=Functional`.
* Provider tests often need external services, connection-string environment variables, or secrets. Match `.github\workflows\ci.yml` and `test\TestInfrastructure\TestExtensions\TestDefaultConfiguration.cs` for the required setup.
* Style is enforced by `dotnet build` because `Directory.Build.props` sets `EnforceCodeStyleInBuild=true` and `TreatWarningsAsErrors=true`.
## High-level architecture
* Orleans is a virtual actor framework. User code defines grain interfaces (`IGrainWithStringKey`, `IGrainWithGuidKey`, etc.) and grain classes; the runtime activates, places, deactivates, persists, and routes calls to grains across silos.
* `src\Orleans.Core.Abstractions` contains the public programming model: grain interfaces, grain references, attributes, and shared abstractions used by both clients and silos.
* `src\Orleans.Serialization.Abstractions` and `src\Orleans.Serialization` provide the version-tolerant serializer, serialization attributes, runtime serialization services, and source-generator integration. Additional serializer packages live under `src\Orleans.Serialization.*` and `src\Serializers`.
* `src\Orleans.Core` contains shared client/server runtime infrastructure such as messaging, hosting integration, configuration, and serialization integration.
* `src\Orleans.Runtime` is the silo implementation: activation lifecycle, placement, cluster membership, reminders, runtime services, and grain execution.
* `src\Orleans.Sdk`, `src\Orleans.Client`, and `src\Orleans.Server` are packaging/metapackage projects. The SDK brings in core packages plus analyzers/code generation; the client/server packages compose the SDK with client or silo dependencies.
* Provider packages are intentionally split by backend and capability under `src\Azure`, `src\AWS`, `src\AdoNet`, `src\Cassandra`, `src\Redis`, and related top-level provider directories. They usually expose builder extensions in `Orleans.Hosting` and options in `Orleans.Configuration`.
* Tests mirror runtime areas under `test\`. Shared test infrastructure is in `test\TestInfrastructure\TestExtensions`, test grains and grain interfaces are under `test\Grains`, and `Orleans.TestingHost`/`TestClusterBuilder` are the primary integration-test harnesses.
* `src\api` contains generated public API surface files for packable projects. API surface updates are generated by `.github\workflows\generate-api-diffs.yml` using `GenAPIGenerateReferenceAssemblySource`.
## Key conventions
* Central package management is enabled in `Directory.Packages.props`; add or update package versions there instead of putting versions in individual projects.
* Use project references for repo-internal dependencies. `CONTRIBUTING.md` explicitly discourages DLL references and unnecessary `Private=True` metadata.
* `src\Directory.Build.props` makes source projects packable by default; `test\Directory.Build.props` makes test projects non-packable, disables nullable for tests, and copies `test\xunit.runner.json`.
* Build-time code generation is controlled by `OrleansBuildTimeCodeGen=true`, which imports the Orleans code generator and analyzers as build analyzers for framework projects.
* Serializable Orleans types that cross grain calls, storage, or streams generally need `[GenerateSerializer]` plus stable `[Id(n)]` members. Do not renumber existing serialization IDs.
* Public API changes in packable `src\` projects usually require corresponding generated API-surface changes under `src\api`.
* Tests use xUnit with the custom `[TestCategory("...")]` attribute from `test\TestInfrastructure\TestExtensions\TestCategory.cs`; this maps categories to xUnit traits and keeps `dotnet test --filter "Category=..."` working.
* Cluster tests usually derive from or compose fixtures in `test\TestInfrastructure\TestExtensions` and configure silos through `TestClusterBuilder`, `ISiloConfigurator`, or `ISiloBuilder`. The default cluster fixture uses in-memory reminders, durable jobs, and grain storage.
* Follow `.editorconfig`: C# uses file-scoped namespaces, system directives first, `var` preferences, braces on new lines, `_camelCase` private fields, and preview language features. Nullable is enabled for source projects and disabled for test projects.
* Add XML docs for new or changed public APIs even though CS1591 is currently suppressed; package projects generate documentation files.
* PR workflow from `AGENTS.md`: open PRs against `dotnet/orleans`, push feature branches to the `origin` fork, and create PRs with `gh pr create --repo dotnet/orleans --base main --head ReubenBond:<branch>`.
