heuropt/CONTRIBUTING.md

Contributing to heuropt

Thanks for considering a contribution. heuropt is a small, opinionated crate, but careful additions are welcome.

Quick checklist

Before opening a pull request:

• cargo fmt --all
• cargo clippy --all-targets --all-features -- -D warnings
• cargo test (default features) and cargo test --all-features
• cargo doc --no-deps --all-features with RUSTDOCFLAGS="-D warnings"
• If you touched algorithm output: re-run cargo run --release --example compare and confirm the quality metrics did not change. Speed-only changes are required to be bit-identical against the prior snapshot.

CI runs all of the above on every PR; the matrix covers MSRV (1.85), the default / serde / parallel / serde+parallel feature combinations, and a 60-second fuzz soak per target.

Commit style

Conventional Commits (https://www.conventionalcommits.org/) are required. The first line follows <type>(<scope>): <summary> where <type> is one of feat, fix, perf, refactor, docs, test, chore, ci, build, style. <scope> is the most specific module the change touches (e.g. nsga2, hypervolume, pareto_archive).

Bad: Phase 1.1: Add core data types Good: feat(core): add data types and Rng alias

Multiple logical changes in a single PR should be split into multiple commits, each on a single concern.

What kinds of contributions land easily

• Bug fixes with a regression test that fails on main and passes on the fix.
• Performance wins that preserve bit-identical output and include a cargo bench (gungraun) before/after, plus a cargo run --release --example compare diff confirming no quality regression.
• Documentation improvements — missing rustdoc examples, README clarifications, mdbook chapters.
• New algorithms that fit the established Optimizer<P> shape and ship with: a unit test, a property test (determinism + invariants), a comparison-harness entry, and rustdoc.
• New operators / metrics / Pareto utilities with the same hygiene.

What needs prior discussion

Open an issue before starting on:

• New traits or breaking changes to the public API surface.
• A new optional feature flag.
• Anything that depends on a heavy new dependency.
• Restructuring of src/algorithms/ or src/pareto/.

The crate intentionally keeps the trait surface small (Problem, Optimizer, Initializer, Variation, Repair); changes there are not refused but they need a clear motivation.

Running the test suites locally

# unit + integration + property tests
cargo test

# all feature combinations
cargo test --features serde
cargo test --features parallel
cargo test --all-features

# instruction-count benchmarks (needs valgrind installed)
cargo bench

# coverage-guided fuzzing (needs nightly + cargo-fuzz)
cd fuzz
cargo +nightly fuzz run pareto_compare -- -max_total_time=60

# mutation testing (slow, optional)
cargo install cargo-mutants
cargo mutants

Reporting bugs

Please include:

1. The smallest reproducing input you can produce — ideally a 20-line examples/repro.rs.
2. The exact command (cargo run --release --example repro etc.) and the observed vs expected output.
3. The Rust toolchain (rustc --version) and feature flags.
4. The heuropt version you saw the bug on.

Bugs that surface fuzz-target panics are particularly welcome; please attach the failing artifact (fuzz/artifacts/<target>/crash-...) so we can add it to the regression-test corpus.

Security

For security concerns please follow the disclosure policy in SECURITY.md. Don't open public issues for security bugs.

Code of conduct

This project follows the Builder's Code of Conduct. The short version: stay professional, stay technical, focus on the work and its merit.

License

By submitting a contribution, you agree that your work is licensed under the same MIT license as the rest of heuropt.