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

### Toolchain

`rust-toolchain.toml` pins the development toolchain to **1.91.1**; rustup honors
it automatically. That pin is not the library's MSRV — `tidaldb` and its siblings
publish `rust-version = "1.91"` and build on 1.91.0. The extra patch release is
required by `tidalctl`'s AWS SDK chain (`aws-types` declares 1.91.1), and without
it every workspace-wide command fails during dependency resolution instead of
compiling, which silently disables the gates below.

## 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 (`hooks/pre-commit`, activated by `scripts/install-hooks.sh`)
enforces these on staged Rust files:

```bash
cargo fmt
cargo clippy -p tidaldb -p tidal-net -p tidal-server -p tidal-stress -p tidalctl --all-targets
cargo test -p tidaldb --lib
```

Clippy runs **without** `-D warnings` on purpose. Each crate's `[lints]` table is
the single source of truth: `clippy::all` and `unwrap_used` are `deny` (so they
fail the build), while `pedantic` and `nursery` are `warn` (advisory). Passing
`-D warnings` on the command line overrides that and turns ~58 deliberate
pedantic warnings in the integration tests into hard errors.

Run the complete gate manually, across the whole workspace:

```bash
cargo fmt --check
cargo clippy --workspace --all-targets
cargo test --workspace
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
- Deny-level clippy (`clippy::all`, `unwrap_used`) must pass; pedantic/nursery are advisory