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/kvis the key-value layer (view.rsthe in-memory ordered view,store.rsthe Lance operation log),src/trackingthe tracking tables,src/storage.rslocations and object-store options,src/rt.rsthe Tokio runtime behind the blocking APIs.crates/kv0-py: the Python bindings (PyO3), the pure-Python package inpython/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/andmkdocs.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.
Releasing¶
Releases are off until the repository variable RELEASE_ENABLED is true; nothing has been published
yet. With it on, every push to main updates a release pull request (version and CHANGELOG.md).
Merging that pull request publishes kv0 to crates.io, tags v<version> and creates the GitHub
release (release-plz), and release.yml builds the wheels and publishes them to PyPI.
The only version is version in [workspace.package] of Cargo.toml; maturin turns it into the
PEP 440 form for the wheels (0.1.0-beta.1 is 0.1.0b1 on PyPI). The first versions are betas
toward 0.1.0:
- The first beta. Nothing is published, so the first release pull request releases the current
version,
0.1.0-beta.1, as it is. - The next beta. From a pre-release, release-plz bumps the last number (
0.1.0-beta.1to0.1.0-beta.2); merging the release pull request cuts it. A version with a pre-release part becomes a GitHub pre-release (git_release_type = "auto"inrelease-plz.toml), and pip installs it only when asked for (pip install --pre kv0, orkv0==0.1.0b2). - 0.1.0. release-plz never leaves a pre-release on its own, so I set the version explicitly: a
pull request that sets
version = "0.1.0"(or runsrelease-plz set-version kv0@0.1.0) and runscargo update -w. Once it is merged, release-plz sees a version higher than the published one, keeps it, and opens the release pull request for 0.1.0. The same works for0.1.0-rc.1or any other version.
The notes under ## [Unreleased] become the release's entry: release-plz only adds the version
heading.
Checklist for a pull request¶
cargo fmt --allandcargo clippy --workspace --all-targets -- -D warningsare clean.cargo deny checkpasses (licences, advisories and sources).pre-commit run --all-filespasses and leaves no changes.- New behaviour has Rust and, where it is exposed, Python tests.
- Performance changes include numbers from
bench/orcargo bench -p kv0 --bench kv.