Contributing

Thanks for your interest in contributing to Fatou! Bug reports, fixes, new lint rules, parser and formatter work, and documentation improvements are all welcome. For larger changes, please open an issue first so we can discuss the approach.

Development environment

The repository ships a devenv (Nix) environment (devenv.nix) that provides the pinned Rust toolchain, a Julia interpreter, mdbook, task, and the auxiliary cargo tools. Enter it with devenv shell. Julia packages (JuliaSyntax.jl, the parser oracle, plus the formatter-comparison tools) are managed by Julia’s own package manager via the repo’s pinned Project.toml/Manifest.toml, not by Nix.

Nix is not required, though. Rust 1.89 or newer is enough to build Fatou; the development toolchain tracks stable through rust-toolchain.toml:

cargo build --workspace
cargo test --workspace

Quality gates

CI is the source of truth for quality gates. Before opening a pull request, make sure these pass locally:

cargo test --workspace                                                 # all tests
cargo clippy --workspace --all-targets --all-features -- -D warnings   # warnings are errors
cargo fmt --all -- --check                                             # rustfmt-clean

Or via task: task test, task lint, task format-check. CI additionally runs cargo-audit and cargo-deny, and builds and tests on Linux, macOS, and Windows.

fatou.schema.json is generated from the configuration types. After changing a configuration key, type, enum, or default, regenerate it with UPDATE_EXPECTED=1 cargo test config_schema, review the diff, and rerun cargo test config_schema. Do not edit the schema by hand.

The fatou-parser reparse benchmark sits behind a bench feature, so a plain --all-targets build never pulls in criterion, whose alloca dependency wants a C toolchain. Run it with task bench-reparse. The clippy line above passes --all-features, so the bench is still linted.

Snapshot tests use insta: review changed snapshots with cargo insta review and accept them with cargo insta accept. Logging in tests honors RUST_LOG (e.g., RUST_LOG=debug cargo test).

Test-driven development

Fatou is developed test-first: write a failing test, watch it fail, then make it pass. For a bug, add a failing fixture or snapshot that reproduces it before the fix.

• Parser fixtures live in crates/fatou-parser/tests/fixtures/parser/<case>/ with an input.jl; the harness snapshots the CST and diagnostics and asserts losslessness (reconstruct(text) == text).
• Formatter fixtures live in crates/fatou-formatter/tests/fixtures/formatter/<case>/ with an input.jl and a hand-authored expected.jl. Fatou owns its formatting style; expected.jl is written by hand, never captured from a formatter. The suite also checks idempotence (format(format(x)) == format(x)) and clean reparse of the output.
• Parser parity is measured against JuliaSyntax.jl via a differential oracle (crates/fatou-parser/tests/juliasyntax_oracle.rs) that needs no Julia at test time.

Architecture and roadmap

• AGENTS.md documents the architecture, the design tenets (deterministic full-reflow formatting, first-class incremental parsing, losslessness), and the project conventions in detail.
• TODO.md is the live roadmap and records known issues and follow-ups. When in doubt about scope or priority, check there.

Documentation

The documentation site (fatou.dev) is an mdBook under docs/. Preview it locally with:

task docs-preview        # mdbook serve docs --open

Commits and versioning

• Use Conventional Commits (type(scope): subject) in the imperative mood, with subject lines ideally under 60 characters.
• Fatou follows semantic versioning. Releases and CHANGELOG.md are generated by tooling—never edit the changelog by hand.

License

By contributing, you agree that your contributions are licensed under the MIT License.