iroh-gossip-rendezvous/CONTRIBUTING.md

Contributing to iroh-gossip-rendezvous

Bug reports, feature requests, and pull requests welcome.

Developer setup

# Clone the repo.
git clone https://git.swaits.com/swaits/iroh-gossip-rendezvous
cd iroh-gossip-rendezvous

# Install the dev toolchain. Most tools are lightweight; Kani is the
# heaviest and only needed if you're running formal proofs.
cargo install --locked \
    cargo-nextest \
    cargo-llvm-cov \
    cargo-deny \
    cargo-audit \
    cargo-semver-checks \
    cargo-mutants \
    cargo-fuzz

# Optional: Kani bounded model checker (needed only for `just kani`).
cargo install --locked kani-verifier
cargo kani setup  # one-time; downloads the solver toolchain.

# Optional: just (task runner). Most distros package it; via cargo:
cargo install just

# Sanity check.
just check

MSRV is 1.93.0. Newer Rust features are not allowed in the main crate; they are allowed in dev-dependencies and examples only.

Local testing

Every CI lane is replayable locally via just:

Task	What it runs
just check	fmt check + clippy + nextest + doctests (the fast CI lane)
just test	nextest + doctests only
just fmt	apply rustfmt
just clippy	lint only
just deny	cargo-deny (licenses, advisories, bans)
just audit	cargo-audit (RUSTSEC)
just semver	cargo-semver-checks vs last published
just coverage	cargo-llvm-cov HTML report
just mutants	cargo-mutants (30–90 min)
just fuzz TARGET=x	60s fuzz run (nightly toolchain required)
just miri	cargo-miri on sync modules (nightly)
just kani	Kani proofs (kani feature)
just model-bfs	Stateright BFS N=4, K=3
just model-random	Stateright random N=20, K=3, 10⁷ steps
just bench	criterion (not a release gate)
just docs	open rustdoc locally
just all	everything, in order

Before you open a PR

• just check must pass locally.
• Add tests for new behavior. Aim for ≥90% coverage on the module you touched; crate-wide minimum is 85%.
• If you change the wire format, the protocol spec, or public API, update PROTOCOL.md / CHANGELOG.md / doctests as appropriate.
• If you touch the algorithmic core (keys, wire, crypto, merge, protocol), re-run just mutants and just kani locally.
• Breaking API changes require cargo-semver-checks to flag them and a major/minor version bump depending on the semver rules.

Where things live

See ARCHITECTURE.md for the module map.

• Algorithm spec: PROTOCOL.md.
• Security posture: SECURITY.md.
• API docs: run just docs or visit https://docs.rs/iroh-gossip-rendezvous.

Style

• rustfmt with default config; clippy pedantic + nursery with the module-level allows documented in Cargo.toml's [lints.clippy] block.
• unwrap_used, expect_used, panic denied in non-test code. If you need one, justify it with a SAFETY comment and #[allow(...)].
• Keep async code in protocol.rs / rendezvous.rs / gossip_glue.rs. Algorithmic core (keys, wire, crypto, merge) must stay pure — Miri and Kani both want sync code.

License

By contributing, you agree that your contributions will be licensed under the MIT license.