Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
42 lines (31 loc) · 1.59 KB

CONTRIBUTING.md

File metadata and controls

42 lines (31 loc) · 1.59 KB

Contributing to WolfDB

Thanks for your interest! WolfDB aims to be a small, correct, well-tested memory substrate.

Setup

git clone https://github.com/wolfdb/wolfdb
cd wolfdb
python -m pip install -e ".[dev]"

Quality gates (all must pass)

ruff check .          # lint + import order
mypy                  # static types (the package ships py.typed)
pytest -q             # unit + property + concurrency + S3 (moto) tests

CI runs these on Python 3.10–3.12 for every push and PR.

Principles

  • Correctness first. The bi-temporal semantics are the product. New behavior needs a test; temporal/concurrency changes should add a hypothesis property test where practical.
  • Keep the core dependency-free. Real models, S3, and ANN live behind optional extras and lazy imports. import wolfdb must work with nothing but the standard library + (optionally) numpy.
  • The log is the source of truth. Never mutate committed events; evolve state by appending.
  • Small surface area. Prefer extending the tiny StorageBackend / Embedder / Extractor interfaces over adding engine special-cases.

Tests

  • tests/test_temporal.py / test_properties.py — bi-temporal correctness & invariants
  • tests/test_storage.py / test_concurrency.py — CAS, durability, multi-writer races
  • tests/test_s3.py — the S3 backend against an in-memory S3 (moto)
  • tests/test_index.py, test_embedders.py, test_compaction.py, test_hardening.py

Please run python examples/quickstart.py and python benchmarks/bench.py before sending a PR that touches the engine.