6fdaa1584b
- m0p3: CONTRIBUTING.md with run-samples checklist, all 4 examples (quickstart, cli_embedding, axum_embedding, actix_embedding), doc-test coverage for every public API surface - m1p5: TidalDb public API — write_item, signal, read_decay_score, read_windowed_count, read_velocity; StorageBox enum routing memory vs fjall; WalSender/WalHandleWriter bridge; WAL replay on open - Periodic checkpoint: 30s background thread for persistent+schema mode; FjallBackend::Clone (O(1), fjall::Keyspace is ref-counted); graceful shutdown via Arc<AtomicBool> + join before final checkpoint - ROADMAP.md: M0 and M1 fully marked COMPLETE (341 tests passing) - Milestone 2 planning scaffolding added under docs/planning/milestone-2/ Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
89 lines
2.7 KiB
Markdown
89 lines
2.7 KiB
Markdown
# Contributing to tidalDB
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# Clone the repo
|
|
git clone https://github.com/orchard9/tidaldb && cd tidaldb
|
|
|
|
# Confirm the engine compiles and all tests pass
|
|
cargo test --manifest-path tidal/Cargo.toml
|
|
|
|
# Confirm doc tests and examples compile and run
|
|
cargo test --doc --manifest-path tidal/Cargo.toml
|
|
cargo test --examples --manifest-path tidal/Cargo.toml
|
|
```
|
|
|
|
## Run Samples Checklist
|
|
|
|
Before opening a PR that touches public API or examples, verify all samples still work:
|
|
|
|
```bash
|
|
# Doc tests (default features)
|
|
cargo test --doc --manifest-path tidal/Cargo.toml
|
|
|
|
# Doc tests with optional features
|
|
cargo test --doc --manifest-path tidal/Cargo.toml --features test-utils,metrics
|
|
|
|
# All four examples compile and run
|
|
cargo run --example quickstart --manifest-path tidal/Cargo.toml
|
|
cargo run --example cli_embedding --manifest-path tidal/Cargo.toml
|
|
cargo run --example axum_embedding --manifest-path tidal/Cargo.toml # Ctrl+C to stop
|
|
cargo run --example actix_embedding --manifest-path tidal/Cargo.toml # Ctrl+C to stop
|
|
```
|
|
|
|
Expected output for `quickstart`:
|
|
|
|
```
|
|
build: dev
|
|
uptime: 0.000s
|
|
health: ok
|
|
tidalDB opened, verified, and closed. M0 complete.
|
|
```
|
|
|
|
## Full Quality Gate
|
|
|
|
The pre-commit hook enforces these automatically on staged Rust files:
|
|
|
|
```bash
|
|
cargo fmt --manifest-path tidal/Cargo.toml -- --check
|
|
cargo clippy --manifest-path tidal/Cargo.toml -- -D warnings
|
|
cargo test --manifest-path tidal/Cargo.toml --lib
|
|
```
|
|
|
|
Run the complete gate manually:
|
|
|
|
```bash
|
|
cargo fmt --manifest-path tidal/Cargo.toml
|
|
cargo clippy --manifest-path tidal/Cargo.toml -- -D warnings
|
|
cargo test --manifest-path tidal/Cargo.toml
|
|
cargo bench --manifest-path tidal/Cargo.toml --no-run # ensure benches compile
|
|
```
|
|
|
|
## Project Layout
|
|
|
|
```
|
|
tidal/ Rust database engine
|
|
src/
|
|
db/ TidalDb handle, builder, config, metrics
|
|
schema/ Types, validation, error types
|
|
signals/ Signal ledger, decay, windowed counters, checkpoint
|
|
storage/ StorageEngine trait, fjall backend, key encoding
|
|
wal/ Write-ahead log, group commit, crash recovery
|
|
benches/ Criterion benchmarks
|
|
examples/ Embedding guides (quickstart, axum, actix, cli)
|
|
tests/ Integration and property tests
|
|
site/ Marketing site (Next.js)
|
|
docs/ Research and planning documents
|
|
```
|
|
|
|
## Coding Standards
|
|
|
|
See [CODING_GUIDELINES.md](CODING_GUIDELINES.md) for the full engineering standards.
|
|
|
|
Key rules:
|
|
- `Result<T, LumenError>` everywhere — no panics on recoverable failures
|
|
- `#![forbid(unsafe_code)]` — relaxed only at explicit FFI boundaries with `// SAFETY:` comment
|
|
- Property tests for invariants, criterion benchmarks for performance claims
|
|
- `cargo clippy -D warnings` must pass with zero warnings
|