Contributing Conventions
The rules for code in the Anarchy I/O Toolkit repository. Unlike the conventions for adopters, these are required: they are enforced by the build and in review, and a pull request that breaks one is not merged.
Process lives in CONTRIBUTING.md. Branches, commit messages, history shaping and version bumps are described there, and it wins on any disagreement with this page. Coding agents get both through
AGENTS.mdand theanarchy-contributeskill.
Every convention is a rule here
Each adopter convention applies in full, without its Opting out section:
| Convention | Enforced by |
|---|---|
| Layering | make check_layering (CI), the dependency map |
| Naming | Review |
| UseCases and Aggregates | Review |
| Code Organization | Review; applied to new and touched code |
| Dependency Injection | Review |
| Observability | Review |
| Async | Review |
| Exceptions | Review |
| Enums | Review |
| Endpoints | Review |
| Testing | Review; unit tests on every pull request |
Rules that only apply to the toolkit
Packages
- Follow the values. In particular: packages are domain-free (no business enums, entities or destinations), vendor-neutral (company specifics go behind extension points) and standalone (every dependency restores from nuget.org).
- Test-only libraries stay in
Testing.*kits. No production project references AwesomeAssertions, Moq or xUnit. - One README per package.
src/<Project>/README.mddescribes the package and links toRELEASE-NOTES.md, which has a note per published version. The copies underdocs/portal/packages/are generated. - New packages are listed in the Package Catalog, named after their layer (
<Layer>.<Name>). - Package names follow the dependency hierarchy. Within a layer, a package may only reference its name ancestors (
Web.MockServer.UitoWeb.MockServerorWeb), so a feature family such asInfrastructure.Persistence.Db.*shows its shared parent in its name. A project may always reference a lower layer; any other same-layer reference is an entry, with its reason, inbuild/PackageHierarchy.cs.make check_package_hierarchyand its unit test enforce it. This is a rule of the toolkit’s own monorepo, which uses prefix layering; it is not part of the adopter conventions and is never imposed on solutions that use folder-mode layering. - Versions are bumped with
make release_bump, never by hand, and validated withmake validate_release.
Build and code quality
- The build that counts is Release with warnings as errors:
dotnet build Anarchy.Toolkit.sln -c Release -p:TreatWarningsAsErrors=true. Analyzer findings only show up there. make lintpasses;make lint_fixapplies the formatting.- Package versions are centrally managed in
Directory.Packages.props; respect the compatibility notes in it.
Tests
- Unit tests run on xUnit v3 and Microsoft.Testing.Platform in
tests/Unit/, with folders mirroring thesrc/projects; tests that drive real tools (Git, the .NET SDK) go totests/Integration/, and those that run a user-facing entry point (the CLI, the packaged Makefile and scripts) totests/EndToEnd/. - Pass
TestContext.Current.CancellationTokento calls that accept a token (xUnit1051).
Generated files and skills
- Regenerate and commit
docs/portal/dependency-map.html(make dependency_map) with any new project, project reference or package dependency. - Commit
.fallout/build.schema.jsonwhen the build regenerates it. - Make targets name their agent skill with
#@; update the skill and runmake skills_sync.make skills_validateruns in CI.
Documentation
- Guides teach, conventions recommend, decisions explain. Put new pages in the matching section: Guides, Conventions or Decisions, and add them to
docs/portal/_data/navigation.yml. - A convention page keeps the same shape: banner, why (linking to a value or ADR), the rules, Opting out or adapting.
- A choice that shapes the packages gets an ADR in
docs/portal/decisions/. - Conventions, decisions and the onboarding guides also ship inside the agent skills (
make skills_docs_sync, checked in CI). Agents read them without the site: keep links relative, keep the elements they look for (ordered steps, Why, Opting out or adapting, “Done when” checks, symptom/cause/fix tables), and update the skill’s guidance when a page’s shape changes.
Checks before a pull request
make lint
make test_unit
make check_layering
make check_package_hierarchy # when you changed a project reference between packages
make skills_validate # when you changed make targets