3bcfb3c576
- Add BUILD.bazel across tidal, tidal-net, tidal-server, tidalctl for bzlmod build - Add tidal/ crate docs (README, CHANGELOG, CONTRIBUTING, AGENTS, CLAUDE, API, ARCHITECTURE) and ai-lookup reference - Add docker standalone/cluster/deploy images, compose, and prometheus config - Harden WAL (batch format, writer, dedup, diagnostics), text syncer/collectors, and vector registry - Expand tidalctl CLI and tests; restructure WAL/visibility integration test suites - Refine tidal-net transport/client/server and tidal-server cluster/scatter-gather
105 lines
3.3 KiB
Markdown
105 lines
3.3 KiB
Markdown
# Contributing to tidalDB
|
|
|
|
## Quick Start
|
|
|
|
tidalDB is the `tidaldb` crate at `tidal/` in this Cargo workspace. Run cargo
|
|
commands from the workspace root, targeting this crate with `-p tidaldb`.
|
|
|
|
```bash
|
|
# From the workspace root:
|
|
|
|
# Confirm the engine compiles and all tests pass
|
|
cargo test -p tidaldb
|
|
|
|
# Confirm doc tests and examples compile and run
|
|
cargo test -p tidaldb --doc
|
|
cargo test -p tidaldb --examples
|
|
```
|
|
|
|
## 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 -p tidaldb --doc
|
|
|
|
# Doc tests with optional features
|
|
cargo test -p tidaldb --doc --features test-utils,metrics
|
|
|
|
# All four examples compile and run
|
|
cargo run -p tidaldb --example quickstart
|
|
cargo run -p tidaldb --example cli_embedding
|
|
cargo run -p tidaldb --example axum_embedding # Ctrl+C to stop
|
|
cargo run -p tidaldb --example actix_embedding # 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 -p tidaldb -- --check
|
|
cargo clippy -p tidaldb -- -D warnings
|
|
cargo test -p tidaldb --lib
|
|
```
|
|
|
|
Run the complete gate manually:
|
|
|
|
```bash
|
|
cargo fmt -p tidaldb
|
|
cargo clippy -p tidaldb -- -D warnings
|
|
cargo test -p tidaldb
|
|
cargo bench -p tidaldb --no-run # ensure benches compile
|
|
```
|
|
|
|
## Project Layout
|
|
|
|
tidalDB is the `tidaldb` crate at `tidal/` in this Cargo workspace. Companion
|
|
crates `tidal-net`, `tidal-server`, and `tidalctl` are workspace siblings at
|
|
the repository root.
|
|
|
|
```
|
|
tidal/
|
|
src/ Flat module layout (engine source)
|
|
cohort/ Cohort-scoped signal aggregation
|
|
db/ TidalDb handle, builder, config, metrics
|
|
entities/ Item / User / Creator entity model
|
|
load/ Bulk load / ingest paths
|
|
query/ RETRIEVE / SEARCH / SUGGEST parser, planner, executor
|
|
ranking/ Profile engine, signal scoring, diversity enforcement
|
|
replication/ WAL-stream replication (cluster mode)
|
|
schema/ Schema builder, validation, signal/profile defs, error types
|
|
session/ Session + agent context, policies
|
|
signals/ Signal ledger, decay, velocity, windowed counters, checkpoint
|
|
storage/ StorageEngine trait, fjall backend, key encoding
|
|
testing/ Shared test harness + fixtures
|
|
text/ Tantivy full-text indexing
|
|
wal/ Write-ahead log, group commit, crash recovery
|
|
benches/ Criterion benchmarks
|
|
examples/ Embedding guides (quickstart, axum, actix, cli)
|
|
tests/ Integration and crash-property tests
|
|
docker/ cluster / standalone / deploy Dockerfiles
|
|
site/ Marketing site (Next.js)
|
|
docs/ Specs, API, guides, research, runbooks, ops, planning
|
|
```
|
|
|
|
## Coding Standards
|
|
|
|
See [docs/CODING_GUIDELINES.md](docs/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
|