Skip to content

Contributing

Welcome! This guide covers repo layout, local development, CI gates, and release workflow.

Repository layout

modelvault/
├── Cargo.toml          # workspace manifest + shared version
├── crates/             # Rust crates (crates.io)
│   ├── modelvault/          # application facade
│   ├── modelvault-core/     # engine
│   ├── modelvault-derive/   # proc macros
│   └── modelvault-cli/      # CLI binary
├── python/modelvault/       # PyPI package (maturin + PyO3)
└── docs/               # MkDocs site (this book)

Quick start (local dev)

python3 -m venv .venv
.venv/bin/python -m pip install -U pip
make check-full

make check-full runs Rust checks/tests, builds the Python extension, runs pytest, make docs-check, and make verify-doc-examples.

For the 1.0 readiness gate:

make check-2p0-ready   # check-full + async facade tests

Rust

cargo check
cargo test
cargo clippy -- -D warnings   # if configured in CI

Python

.venv/bin/python -m pip install -U "maturin>=1.5,<2" pytest
cd python/modelvault && maturin develop --release && pytest -q

Documentation

Docs are built with MkDocs Material.

make docs-check    # strict link check
make docs-serve    # local preview (if target exists)

Verified examples

make verify-doc-examples ensures stdout from snippets in READMEs and guides matches documented output. When you change example behavior, update:

  1. The code block in the doc/README
  2. The matching ```text output block
  3. scripts/verify-doc-examples.sh expected heredocs

Covered sources: root README, docs/guides/quickstart.md, docs/guides/python.md, python/modelvault/README.md, docs/ops/operations_and_failure_modes.md.

Runnable examples

Under examples/ (todo app, CLI notes, FastAPI). Smoke test:

make examples-smoke   # todo, cli_notes, desktop (isolated data dir)

When adding examples, include a README with problem → solution → run commands → result, and keep *.modelvault files gitignored (see examples/.gitignore). Desktop smoke uses MODELVAULT_EXAMPLE_DATA_DIR — do not write into the user's real app-data folder in CI.

Blog drafts live under blog/ — see modelvault-for-application-models.md.

Positioning docs: Why ModelVault, Comparisons. Page levels and checklist: Documentation map. Full editorial plan: docs/MODELVAULT_DOCUMENTATION_POSITIONING_MASTER_PLAN.md on GitHub.

Fuzzing

rustup toolchain install nightly
cargo +nightly fuzz run decode_segment_header -- -max_total_time=30

Targets under fuzz/fuzz_targets/. Decode errors are success; panics/UB are failures.

Benchmarks

make bench
python scripts/bench_compare.py --base target/criterion-old --new target/criterion

CI runs benches weekly (non-blocking). See bench workflow on GitHub.

Coverage

  • Rust: cargo llvm-cov — practical 100% line coverage goal for modelvault-core with documented exclusions
  • Python: pytest-cov via .coveragerc

Gap report: python scripts/coverage_modelvault_core_gap_rank.py

Versioning

Workspace crates and PyPI share [workspace.package] version in root Cargo.toml. Bump on release, tag vX.Y.Z to match.

Publishing

Automated from a version tag:

./scripts/publish-all.sh   # requires CARGO_REGISTRY_TOKEN + MATURIN_PYPI_TOKEN

GitHub Actions publish workflow runs on v*.*.* tags.

Before tagging:

  1. make check-2p0-ready
  2. Release checklist
  3. Update CHANGELOG.md

Publish order for crates.io: modelvault-core → modelvault-derive → modelvault → modelvault-python.

CI

.github/workflows/ci.yml — Rust + Python + docs + coverage.

Where to look next

Topic Doc
File format Specifications
API contracts Compatibility
1.x file-format rules Format evolution · make test-format-compat
Roadmap ROADMAP on GitHub
Full contributing notes (repo root) contributing.md on GitHub