jx12n ad4134e280 chore: doc consolidation, seven-dimension review fixes, and commit hooks

- 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)

2026-06-08 22:46:28 -06:00

2.5 KiB

Raw Blame History

Contributing to tidalDB

Quick Start

# 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:

# 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:

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:

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 for the full, canonical layout (including the tidal/src/ module map and the docs/ doc homes).

Coding Standards

See 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

2.5 KiB Raw Blame History