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 everything: the pinned Rust toolchain, a Julia toolchain (including JuliaSyntax.jl, the parser oracle), mdbook, task, and the auxiliary cargo tools. If you use direnv, the environment loads automatically; otherwise run devenv shell.

Nix is not required, though. A stable Rust toolchain (see rust-toolchain.toml) is enough to build and run the full test suite:

cargo build
cargo test

Quality gates

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

cargo test                                                 # all tests
cargo clippy --all-targets --all-features -- -D warnings   # warnings are errors
cargo fmt -- --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.

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 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 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 (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.