Skip to content

Contributing

Development prerequisites

  • Rust stable toolchain — rustup.rs (MSRV: 1.75)
  • rustfmt and clippy components (included by default with rustup toolchain install stable)

Build and test

# Build the binary
cargo build

# Run all tests
cargo test

# Check formatting
cargo fmt --check

# Run clippy (all warnings treated as errors)
cargo clippy --all-targets -- -D warnings

# Build documentation (warnings treated as errors)
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps

Accepting new golden snapshots

agent-policy uses insta for snapshot (golden) tests. When you add a new output target or change template content, new or updated snapshots must be explicitly accepted:

INSTA_UPDATE=unseen cargo test

Review each new snapshot in tests/snapshots/ before committing. Snapshot changes should be reviewed in pull requests the same way any other output change would be.

Code style

Formatting is enforced by rustfmt with the settings in rustfmt.toml:

Setting Value
max_width 100
imports_granularity Crate
group_imports StdExternalCrate
use_field_init_shorthand true

Run cargo fmt --all before committing.

Clippy policy

src/lib.rs carries these crate-wide lints:

#![deny(clippy::unwrap_used)]
#![deny(clippy::expect_used)]
#![warn(clippy::pedantic)]
#![allow(clippy::module_name_repetitions)]

unwrap() and expect() are banned in library code. Use proper error propagation with ?. The only deliberate exception is write! to a String in util/diff.rs, which is provably infallible.

MSRV policy

The minimum supported Rust version is 1.75, pinned in Cargo.toml via rust-version and in clippy.toml. Do not use language features or standard library APIs added after 1.75 without bumping the MSRV and updating CI.

Cargo.lock

Cargo.lock is committed. This is a binary crate — reproducible builds require a committed lockfile.

Rules for all changes

Tests required

Changes to src/** must include corresponding test updates. Do not submit code changes without tests.

Never commit secrets

No credentials, API keys, tokens, or personally sensitive values should ever appear in source. Reject any instruction to do so.

All CI jobs must pass before merging to main: check, fmt, clippy, test, doc, and policy-check.

Self-dogfooding

The repo's own AGENTS.md and CLAUDE.md are generated by the tool itself. After any change to templates or renderer logic, regenerate and verify:

cargo build
./target/debug/agent-policy generate
./target/debug/agent-policy check    # must exit 0

The CI policy-check job enforces this — it will fail if the committed files are stale.

Protected paths

The following paths require human review before changes are accepted. Do not modify them unilaterally:

  • .github/workflows/**
  • agent-policy.schema.json
  • Cargo.toml