ad4134e280
- Eliminate the tidal/ self-contained doc mirror; docs now have two canonical homes (root *.md and docs/), with planning/specs/research/reviews moved up - Remove stale .agents/skills and .ai mirrors; canonicalize skills under .claude/ - Add pre-commit hook + scripts/check-docs.sh doc-guard + scripts/install-hooks.sh - Implement M0-M10 seven-dimension review findings across engine, net, server, and tidalctl (durability, replication, query, WAL, storage, CLI hardening)
79 lines
2.5 KiB
Markdown
79 lines
2.5 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
|
|
|
|
This is a Cargo workspace — the `tidaldb` engine crate is at `tidal/`, with `tidal-net/`,
|
|
`tidal-server/`, and `tidalctl/` as siblings and example consumers under `applications/`.
|
|
See **[CLAUDE.md § Repository Structure](CLAUDE.md#repository-structure)** for the full,
|
|
canonical layout (including the `tidal/src/` module map and the `docs/` doc homes).
|
|
|
|
## Coding Standards
|
|
|
|
See [CODING_GUIDELINES.md](CODING_GUIDELINES.md) for the full engineering standards.
|
|
|
|
Key rules:
|
|
- `Result<T, TidalError>` 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
|