# Repository Guidelines
## Project Structure & Module Organization
The crate lives in `src/` with `lib.rs` exporting the public API and delegating to focused modules: `ser.rs` for serde-driven encoding, `de.rs` for decoding, `fast.rs` for typed-array fast paths, `header.rs` and `size.rs` for framing helpers, and `ext.rs` for serde extensions. Errors reside in `error.rs`. Integration tests sit in `tests/`, split across `basic.rs`, `fast.rs`, and interop suites under `tests/interop.rs` and `tests/cpp/` that validate cross-language compatibility. Example binaries demonstrating emission lives in `examples/` (see `emit_bool.rs` and `emit_color.rs`). Specification notes and external references live under `reference/` for design context.
## Build, Test, and Development Commands
Use `cargo build` for a debug build and `cargo build --release` when benchmarking encoding throughput. Run `cargo test` to execute unit, doc, and integration suites; add `-- --nocapture` when you need stdout. `cargo fmt` formats the codebase and doubles as a CI guard with `cargo fmt -- --check`. Lint with `cargo clippy --all-targets --all-features` before submitting changes. Example binaries can be exercised with `cargo run --example emit_bool`.
## Upgrading `hdf5-pure`
The `mat` feature writes MATLAB v7.3 files through `hdf5-pure`, which is a private implementation detail: no type in beve's public API comes from it (see `src/mat/options.rs`). Keep it that way. When moving to a new release:
1. Read its changelog for **write-side** changes. beve only ever writes, so read-path changes rarely reach it.
2. Mirror any added variant of a policy enum (`Compression`, `NullPolicy`, `LibVer`, ...) into `src/mat/options.rs` and its `to_pure` arm. Nothing flags an unmirrored variant; the mapping only runs one way, so it is simply unreachable. A renamed or removed variant does fail the build.
3. Prove the written bytes did not change rather than that the tests still pass: convert a spread of payload shapes and option settings under both versions and compare byte for byte, error strings included. Past entries in `CHANGELOG.md` record what that spread covered.
4. An hdf5-pure bump is not on its own a beve semver event any more. Version beve by what changed in *beve*.
## Coding Style & Naming Conventions
Follow idiomatic Rust style with rustfmt defaults (4-space indentation, trailing commas, snake_case modules). Public types and traits use UpperCamelCase, while functions, modules, and files stay snake_case. Keep error variants descriptive and suffix serde helper types with `Visitor` or `Adapter` when appropriate. Prefer `&[T]` and iterators over owning collections to keep encoding zero-copy. Let clippy warnings guide refactors; do not ignore new lints without justification.
## Testing Guidelines
Add integration coverage in `tests/` for external behavior and unit tests inline with modules via `#[cfg(test)]` blocks. Mirror the naming of the code under test (`fast_typed_arrays`, `object_roundtrip`, etc.) and assert byte-level expectations when feasible. Validate interop by extending fixtures in `tests/cpp/` when touching the format. Aim to keep new features accompanied by round-trip tests and property checks where practical.
## Commit & Pull Request Guidelines
Write concise, present-tense commit subjects similar to `git log` (<72 chars, imperative verbs such as “Add fast header encode”). Squash noisy commits before review. Each pull request should describe the change, link related issues or spec sections, list validation commands run, and include benchmarks when performance-sensitive behavior shifts. Confirm `cargo fmt`, `cargo clippy`, and `cargo test` succeed before requesting review.