Contributing

This page covers the conventions for contributing code and documentation to infrastore.

Code Quality

All changes should pass the standard workspace checks before being committed:

cargo fmt --all -- --check                              # Rust formatting
cargo clippy --workspace --all-targets --all-features -- -D warnings   # Rust linting
cargo test --workspace --all-features                   # Rust tests
dprint check                                            # Markdown formatting
cargo deny check --config deny.toml                     # Dependency policy

The workspace targets edition 2024 and declares an MSRV of Rust 1.94 (rust-version in the root Cargo.toml is the authority; there is no rust-toolchain file). Markdown in docs/ is wrapped at 100 characters — dprint fmt does it for you.

Testing Across Bindings

A change to the core may need re-running the binding tests:

# Rust
cargo test --workspace

# Python
cd crates/infrastore-py && maturin develop && pytest ../../python/tests

# Julia (requires the cdylib + INFRASTORE_LIB)
cargo build -p infrastore-ffi --release
export INFRASTORE_LIB=$PWD/target/release/libinfrastore_ffi.dylib  # .so on Linux
julia --project=julia/InfraStore.jl julia/InfraStore.jl/test/runtests.jl

The On-Disk Format Is a Contract

The NetCDF layout, the SQLite schema, and the hashing rules together form the on-disk format, versioned by DATA_FORMAT_VERSION. Any backward-incompatible change to any of them must bump that version. The hash_golden test pins representative hashes; if it fails because you changed the hashing domain, that is a format-breaking change, not a test to "fix."

Generated Surfaces

The C header crates/infrastore-ffi/include/infrastore.h is generated by cbindgen — do not hand-edit it; it is refreshed when you build infrastore-ffi.
The proto-derived Rust types in infrastore-proto are generated by tonic from proto/infrastore/v1/store.proto.

When you change the public surface of a binding, update the matching reference page in this book.

Documentation

Docs follow the Diataxis framework. Put new pages in the right category:

Category	Location	When
Getting Started	`src/getting-started/`	First-run, learning-oriented quick starts
Explanation	`src/explanation/`	Concepts, architecture, design rationale
Developer Guides	`src/guides/`	End-to-end, per-language usage
How-To	`src/how-to/`	A single task in the fewest steps
Reference	`src/reference/`	Exact signatures, schemas, on-disk layouts

After adding a page, add it to src/SUMMARY.md. Preview locally:

cd docs
mdbook serve --open

Significant design decisions belong in the Explanation section, covering the problem, the approach, the trade-offs, and the alternatives considered.