Contributing¶
Thanks for your interest in moraine. Bug reports, failing seeds, benchmarks, documentation fixes and code are all welcome.
Before you start¶
- For anything beyond a small fix, open an issue first so we can agree on the approach. moraine
follows a written design; a change that departs from it needs an entry in
DECISIONS.mdwith the reason. - Security issues go through SECURITY.md, not public issues.
- Use synthetic data in tests, examples and issues.
- Unless you explicitly state otherwise, any contribution you intentionally submit for inclusion in moraine, as defined in the Apache-2.0 licence, is dual licensed under Apache-2.0 and MIT, without any additional terms or conditions.
Development setup¶
You need Rust 1.95 or newer (the minimum supported version, set by delta-rs) and a C++ compiler
for the usearch index (the vector feature and the test kit). Docker is optional; it runs the
S3-compatible server for the backend tests.
git clone https://github.com/sayef/moraine && cd moraine
scripts/check.sh --quick # format, clippy, tests and 1,000 simulation seeds
scripts/check.sh # the same with 10,000 seeds, plus the aws-sdk feature and bench/
The workspace members are crates/moraine (the library, package morainedb),
crates/moraine-testkit (test tooling and the integration tests), crates/moraine-cli (empty
for now) and spike/ (the spike's checks). bench/ is a workspace of its own and builds
Lance through kv0; scripts/check.sh lints it, which takes a while the first time.
Tests and the simulation¶
Most tests live in crates/moraine-testkit/tests. The simulation tests run many seeds of a
scenario against a fault-injecting store with a simulated clock and a seeded scheduler, and
check every outcome against a reference model. A failing seed is printed and replays exactly:
MORAINE_SIM_SEEDS=100000 cargo test --release -p moraine-testkit --test mutations_sim -- --nocapture
MORAINE_SIM_SEED=1234 cargo test -p moraine-testkit --test mutations_sim # replay one seed
MORAINE_FUZZ_ITERS=20000 cargo test -p moraine-testkit --test fuzz -- --nocapture
Write the failing scenario first, then the fix. Never weaken an invariant check to make a seed pass; add the seed to the scenario's regression list instead.
The backend tests run against any S3-compatible server. spike/s3-server.sh starts RustFS in
Docker:
spike/s3-server.sh start && source <(spike/s3-server.sh env)
cargo test -p moraine-testkit --test backends
spike/s3-server.sh stop
Tests that need a real AWS bucket are ignored by default; they write only under a random prefix and delete it afterwards.
Checks before a pull request¶
The pre-commit hooks run the same checks as CI, except the test suite:
pre-commit install # or: prek install
pre-commit run --all-files
They run cargo fmt and clippy (warnings denied), typos, gitleaks, actionlint and zizmor, and
basic file hygiene. CI also runs the tests, a short simulation and cargo deny.
- Keep delta-rs types out of the public API and out of every module except
crates/moraine/src/log/delta.rs. - A change on the write or read path keeps its request budget: the request-budget tests count the exact requests of each operation.
- Performance changes come with numbers from
bench/(seedocs/BENCH.md).
Documentation¶
The site is built with mkdocs-material:
uv run --with-requirements docs/requirements.txt mkdocs serve # http://127.0.0.1:8000
uv run --with-requirements docs/requirements.txt mkdocs build --strict
Brand assets (the mark, wordmark, banners, social preview, web fonts and the docs colour tokens) are generated; edit
assets/src/build.py and run it again rather than editing the SVG files by hand:
uv run --no-project --with fonttools --with brotli --with uharfbuzz --with resvg-py python assets/src/build.py
The identity is described in brand/DESIGN.md.
The benchmark charts are generated from the raw results too. Add a new run to bench/results/
as a YYYY-MM-DD-<name>.jsonl file and run bench/charts/build.py: it picks the newest run of
each kind by file name, redraws the SVG files in docs/assets/charts/ and rewrites the marked
chart and data regions of docs/benchmarks.md, docs/index.md and this repository's README.
The sentences around the charts are written by hand, so read them against the new numbers.
uv run --no-project --with fonttools --with brotli python bench/charts/build.py
Commits and pull requests¶
- Small, focused commits with an imperative subject line ("Add the key index to
get"). - Describe what changed and why in the pull request, and link the issue.
- Update
CHANGELOG.mdunderUnreleasedfor anything a user of the crate would notice.