Skip to content

Contributing to kv0

Thanks for your interest in kv0. Bug reports, 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.
  • Security issues go through SECURITY.md, not public issues.
  • By contributing, you agree that your contributions are licensed under the Apache License 2.0.
  • Use synthetic data in tests, examples and issues.

Development setup

You need Rust 1.94.1 or newer (the minimum supported version, checked in CI), protoc with the well-known .proto includes (Lance needs it at build time: apt install protobuf-compiler libprotobuf-dev or brew install protobuf) and, for the Python bindings, Python 3.11+ with uv and maturin.

git clone https://github.com/sayef/kv0 && cd kv0
cargo test -p kv0                     # or: cargo nextest run -p kv0

uv sync --no-install-project          # pytest, maturin and ruff, at the versions in uv.lock
uv run --no-sync maturin develop --release
uv run --no-sync pytest

Object-store tests run against any S3-compatible server. CI starts RustFS in Docker:

KV0_TEST_S3_BUCKET=kv0-test .github/scripts/s3-server.sh
KV0_TEST_S3_ENDPOINT=http://127.0.0.1:9000 cargo test -p kv0 --test s3
KV0_TEST_S3_ENDPOINT=http://127.0.0.1:9000 uv run pytest -k s3

The documentation site is MkDocs with the Material theme:

uv pip install -r docs/requirements.txt
uv run mkdocs serve               # preview at http://127.0.0.1:8000
uv run mkdocs build --strict      # what CI runs: no warnings allowed

Project layout

  • crates/kv0: the library. src/kv is the key-value layer (view.rs the in-memory ordered view, store.rs the Lance operation log), src/tracking the tracking tables, src/storage.rs locations and object-store options, src/rt.rs the Tokio runtime behind the blocking APIs.
  • crates/kv0-py: the Python bindings (PyO3), the pure-Python package in python/kv0, typed stubs and the Python tests.
  • bench/: the evaluation harness (bench/eval/), the key-value comparison with the SQLite-cache baseline and the tracking benchmark.
  • docs/ and mkdocs.yml: the documentation site. assets/: brand files.
  • DESIGN.md: decisions, guarantees and rejected alternatives. Update it when behaviour changes.

Checks

CI runs the checks below on every pull request, and the pre-commit hooks run most of them before each commit. Install the hooks once with pre-commit (or prek, which reads the same file):

uvx pre-commit install                # or: pipx install pre-commit && pre-commit install
uvx pre-commit run --all-files        # everything at once, as CI does

pre-commit installs its own copies of ruff, typos, actionlint and zizmor, at the versions pinned in .pre-commit-config.yaml; the Rust hooks use your toolchain.

Check What it covers Run it locally
Whitespace, YAML, TOML, merge markers trailing whitespace, final newlines, line endings pre-commit
gitleaks secrets in the tree (CI scans the whole history) pre-commit
cargo fmt, cargo clippy Rust formatting and lints, warnings as errors pre-commit, or cargo fmt --all --check and cargo clippy --workspace --all-targets -- -D warnings
ruff Python lints and formatting pre-commit, or uv run --no-sync ruff check and uv run --no-sync ruff format --check
typos spelling in code and docs; exclusions and allowed words in _typos.toml pre-commit, or uvx typos
actionlint, zizmor GitHub Actions workflows: correctness and security pre-commit, or uvx zizmor --offline .github
cargo machete unused Rust dependencies (CI only) cargo install cargo-machete && cargo machete
cargo deny check licences, advisories and sources (CI only) cargo install cargo-deny && cargo deny check
Tests, MSRV, docs Rust and Python tests, Rust 1.94.1, mkdocs build --strict see the sections above

The benchmark outputs (bench/results/*.json, bench/eval/charts/*.svg, bench/REPORT.md) are generated, but they pass the same whitespace hooks: regenerate them rather than editing them by hand. If ruff and the pre-commit hook disagree, the ruff pin in pyproject.toml and the rev in .pre-commit-config.yaml have drifted apart; I keep them on the same version.

Checklist for a pull request

  • cargo fmt --all and cargo clippy --workspace --all-targets -- -D warnings are clean.
  • cargo deny check passes (licences, advisories and sources).
  • pre-commit run --all-files passes and leaves no changes.
  • New behaviour has Rust and, where it is exposed, Python tests.
  • Performance changes include numbers from bench/ or cargo bench -p kv0 --bench kv.