Contributing¶

How to contribute to HyperbyteDB: the PR process, code review checklist, and engineering policies.

PR Process¶

1. Branch from main.
2. Implement your change following the Coding Standards.
3. Test locally:

   cargo fmt --all --check
   cargo clippy --all-targets -- -D warnings
   cargo test --lib
   cargo test --test '*'
   

4. Document new config keys in docs/user-guide/configuration.md and config.toml.example.
5. Open a PR against main.
6. CI must pass — format, clippy, tests, and release build.

Code Review Rubric¶

Every PR is reviewed against the following layers. Each gate requires cited evidence (command output, test name, or code trace).

Tool Gates (CI alignment)¶

Layer A — Correctness¶

A.1 Rust fundamentals - No new unwrap/expect on fallible paths in non-test code. - Errors propagate with ? or explicit mapping. - No Mutex/RwLock held across .await. - Public API changes are intentional.

A.2 Data path integrity - WAL ordering and sequence semantics preserved. - Flush does not drop acknowledged writes. - Replication apply path is idempotent. - Storage layout and file naming match StorageLayout.

A.3 Distributed semantics - Network failures have timeouts, retries, and backoff. - Raft log/store/network/state machine changes preserve safety.

A.4 HTTP/InfluxDB v1 compatibility - Status codes and bodies match docs/user-guide/reference.md. - Auth paths remain consistent.

A.5 Query translation safety - Identifiers and literals are quoted/escaped against injection.

A.6 Security - Secrets not logged. - Password hashing uses Argon2.

A.7 Observability - No high-cardinality labels on Prometheus metrics.

Layer B — Maintainability¶

• Port traits remain the primary abstraction between application and adapters.
• Config keys documented when added or renamed.
• Domain types free of I/O dependencies.

Layer D — Tests¶

Suite ownership (avoid duplication):

Before deleting a test, show that another suite covers the same behavior.

Layer E — De-bloating¶

Allowed removals (each needs proof):

1. Unused dependencies — cargo machete clean + cargo check --all-targets.
2. Unreachable code — Not part of stable pub API; grep consumers; tests pass.
3. Duplicate documentation — Consolidate with one canonical page.
4. Obsolete scripts — No references in CI, README, or deploy/.
5. Local-only artifacts — Never delete user data trees.

Breaking removals (HTTP shape, config keys, features) require explicit label and changelog note.

Engineering Policies¶

Rust coding standards¶

The project follows the rust-skills rule set (MIT), summarized in the root .cursorrules file. Key areas: ownership, error handling, memory safety, API design, async patterns, performance, and anti-patterns.

Commit conventions¶

• Use clear, descriptive commit messages.
• Reference issues when applicable.
• Keep commits focused — one logical change per commit.

Dependencies¶

• Prefer Arc<dyn Trait> for dependency injection.
• Keep domain types free of I/O dependencies.
• Pin major versions of GitHub Actions.
• Commit Cargo.lock.

Getting Help¶

• Check Architecture for system design questions.
• Check Core Modules for "where is this code?" questions.
• Check Extension Points for "how do I add...?" questions.

Engineering review artifacts and editor policy¶

• Review rubric (layers, suite gates, de-bloating rules): engineering/code-review-rubric.md.
• Section review notes (architecture areas, findings log): engineering/section-review-notes.md.

Rust coding standards (editors and AI): the in-repo summary lives in the root .cursorrules file (condensed from rust-skills). If you change or extend project-wide Rust guidance, update .cursorrules and the engineering rubric if review gates change. A full per-rule copy may exist under .cursor/skills/ locally; that path is sometimes gitignored and does not change policy.

Further Reading¶