# 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