# 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
```sh
# 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](SECURITY.md). Don't open public issues for security
bugs.
## Code of conduct
This project follows the [Builder's Code of Conduct](CODE_OF_CONDUCT.md).
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.