Contributing

Thank you for looking. This is a personal project built in evenings, under the MIT licence, and it is deliberately governed by documents rather than by memory.

Read these first

Before you open a pull request

cargo lint          # doc links, rustfmt, clippy, eslint, prettier, ruff, mypy, dotnet format
cargo test --workspace --all-features
cargo llvm-cov --workspace --fail-under-lines 70 && scripts/coverage-per-crate.sh 70

Install the hooks once, and the first two run for you before each push:

git config core.hooksPath .githooks

The pull request template is the definition of done as a checklist. Name the plan and sub-wave your change belongs to, the requirement IDs it satisfies and the ADRs it applies.

What makes a change easy to accept

• It belongs to a plan. If the design calls for something and no plan names it, add it to the plan in a separate change first.
• It is proven by the specification, not by argument. An extractor change runs dependency-cruiser's own fixtures; an element predicate runs its ported ArchUnitNET case. The conformance ratchets may only shrink.
• It carries links. Every source file, plan and ADR links the architecture section, the ADRs, the plan and the requirement it serves. A broken link fails the build.
• It does not lower a gate. Widening a pattern, raising a ratchet, adding an allowEmpty or disabling a lint to get green is the one thing that will be sent back. Record a genuine exception with an owner and an expiry instead.

Decisions

An accepted ADR is never edited except to change its status; a reversal is a new ADR that supersedes it. If your change makes a decision, write the ADR in the same pull request.

Adding a ported gate 2 case

Gate 2's cases are the upstream tests, ported as data (ADR-0009, conformance/README.md). A snapshot test in ArchUnitNET is ported by the tool: python3 conformance/archunitnet/tools/port.py rewrites conformance/archunitnet/ported/ and the counts in ported.json and unported.json. A test whose assertions are C# is ported by hand:

1. Add a file conformance/archunitnet/ported/<TestClass>.yaml whose first line starts # Ported from ArchUnitNET 0.13.4 <path> by hand: and says why. Give each case an id (<Test>#<n>), a query in words, the upstream csharp assertion, the rule, and the expect: pass and fail sets of full names, passes for HasNoViolations, vacuous, or an error. A family other than element (slice, diagram, plantuml, association, baseline) is read as crates/rb-rules/tests/gate2.rs describes.
2. Rerun port.py: a hand-ported test replaces its one unported entry with its cases, and the tool must reproduce the counts you expect.
3. Run cargo test -p rb-rules --test gate2 -- --nocapture, scripts/gate2-check.sh and scripts/gate2-ratchet.sh. A case that fails is a bug in the engine or the extractor, never in the expectation: fix the code, not the case.

NetArchTest cases are written by conformance/netarchtest/tools/Port, which runs NetArchTest itself over the committed fixtures (conformance/netarchtest/README.md).

A second maintainer

The project has one maintainer, and a second is the goal by the end of wave 2 (design § Open questions). The criterion is fixed in advance (plan 0002 § 1.7, "Second maintainer"):

Two parts of the tree are the safest first pull request, because a committed specification tells you when you are right and a reviewer does not have to:

Nobody is invited through another project's issue tracker (ADR-0065): this section is the invitation. Whether the criterion is met is recorded in the plans' status tables; not meeting it blocks no plan.

Reporting

Bugs and questions belong in issues. Security reports go through the security policy, not an issue.