Development guide

Required checks

Run formatting, linting, and tests from the repository root:

cargo fmt --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace

Check the declared minimum supported Rust version separately. The locked workspace must compile with Rust 1.88:

rustup toolchain install 1.88.0
cargo +1.88.0 check --workspace --locked

Exercise the optional PyO3 API through an installed extension:

python -m venv .venv
.venv/bin/python -m pip install "maturin[patchelf]>=1.7,<2" numpy scipy pytest
env -u CONDA_PREFIX VIRTUAL_ENV="$PWD/.venv" \
  PATH="$PWD/.venv/bin:$PATH" \
  .venv/bin/maturin develop --release \
  --manifest-path crates/fcmaes-py/Cargo.toml
.venv/bin/python -m pytest

SciPy is needed only by the retry binding tests, where the extension constructs the public scipy.optimize.Bounds object passed to an optimizer callback.

Before a registry release, also run the package and clean-install checks in RELEASING.md. The Python version is derived from the workspace package version rather than duplicated in pyproject.toml.

Run git diff --check before handing off changes.

Source map

Generate rustdoc

RUSTDOCFLAGS="-D warnings" cargo doc -p fcmaes-core --no-deps
cargo doc --workspace --no-deps

fcmaes-core denies missing public documentation and broken intra-doc links. Add rustdoc comments to every public module, type, field, constant, function, and method when extending the API. Public solver modules should include a runnable example and cite the primary algorithm literature. Use intra-doc links such as [`De::optimize`] where the target is in the same crate. Keep this directory focused on workflows and architecture rather than duplicating every generated signature.

Rust nightly’s coverage display (or the equivalent bootstrap command used for local auditing) reports the exact documented-item ratio:

RUSTC_BOOTSTRAP=1 cargo rustdoc -p fcmaes-core --lib -- \
  -Z unstable-options --show-coverage

The 0.1.4 release reports 452/452 public items documented. The compile-time lint and CI documentation build prevent that count from silently regressing.

Build the documentation site

Install the pinned mdBook release once:

cargo install mdbook --no-default-features --features search \
  --version "^0.5.4" --locked

Then assemble and build the site from the canonical repository content:

python scripts/check_doc_consistency.py
python scripts/build_book.py
python scripts/check_book_links.py

Build and verify the complete PDF edition separately:

python scripts/build_book.py --print
python scripts/build_book_pdf.py

The PDF builder needs Chrome or Chromium plus mutool. It creates a navigable bookmark tree, keeps chapter links inside the book, converts links to repository artifacts into portable GitHub URLs, and writes docs/fcmaes-rust-book.pdf.

The three commands cover different failure modes:

• The consistency check derives tutorial and package counts from the tree. It verifies repeated inventories, the registry-pin and MODE counts, the release tag command, and workspace lockfile versions.
• The build stages source under target/mdbook-src and writes rendered HTML to target/book. Navigation comes from book/SUMMARY.md. Edit the canonical README, guide, tutorial, or benchmark—not the staged files.
• The rendered-link check validates pages, assets, and anchors after mdBook has applied its output-path rules.

The documentation workflow runs these checks on pull requests and deploys main through GitHub Pages. A repository administrator must select GitHub Actions once under Settings → Pages → Build and deployment → Source.

Testing strategy

Optimizer parity is statistical, not bit-exact across languages. Fixed-seed Rust tests should be deterministic, while cross-language acceptance should compare distributions, success rates, and budget use.

The test layers are:

• Core unit tests beside each Rust module.
• GTOP reference and helper tests in fcmaes-examples.
• PyO3 compilation as part of the workspace build and Python-level integration tests under crates/fcmaes-py/python_tests/.
• Reproducible native performance workloads in benchmarks/.
• Standalone tutorial tests plus byte-for-byte figure and local-link checks under tutorials/.

When adding a public parameter, test its default, a non-default path, invalid input, result accounting, and stop behavior. Ask/tell interfaces also need call-order and batch-length tests.

Coverage

If cargo-llvm-cov is installed:

cargo llvm-cov --workspace --all-targets --summary-only

Coverage is a diagnostic, not a substitute for convergence and parity tests. Optimization code needs tests that exercise update behavior and result quality, not only line execution.

Adding an optimizer

1. Implement numerics in fcmaes-core without Python dependencies.
2. Define explicit parameter and result structs and re-export them from fcmaes-core/src/lib.rs.
3. Add one-shot convergence tests and stateful contract tests when applicable.
4. Add an optional PyO3 wrapper only after the core API is stable.
5. Register that binding in crates/fcmaes-py/src/lib.rs.
6. Add deterministic convergence and API-contract evidence.
7. Update rustdoc and these guides.

Adding a GTOP problem or CLI option

Add objective numerics to gtop.rs, then add a named Problem with validated bounds in problems.rs. Add name aliases to by_name, reference-value tests, and catalog coverage. Shared CLI options belong in runner::Cli; both binaries should continue to use the same parser.

Progress output belongs on stderr so stdout remains usable by benchmark and automation code.

Performance checks

• Always build with --release before timing.
• Exclude compilation from timed samples.
• Report workers, retries, configured budgets, and actual evaluations.
• Distinguish retry threads from optimizer population threads.
• Match optimizer configuration, evaluation budgets, retries, workers, stop conditions, and input data before comparing two runs.
• Store raw samples next to the benchmark report.