# Repository Guidelines

## Project Structure

- `cmd/`: binary entry points (e.g. server/worker/ctl).
- `components/`: main Rust workspace crates (engine, server, cloud, native_br, test utilities).
- `src/`: top-level `tikv` crate sources.
- `tests/`: integration test harness crate and suites:
  - `tests/cloud_engine/`: cloud-engine integration tests.
  - `tests/cloud_engine_failpoints/`: cloud-engine failpoint integration tests.
  - `tests/random/`: random tests.
- `~/.cargo/registry/src`: depedencies source code path.

## Commands

- Build dev: `make build`
- Build release: `make release`
- Run integration tests: `cargo test --package tests --test cloud_engine --features testexport <test_name>`
  Note: `testexport` feature is important to make some tests work.
- Lint: `make clippy`
- Format: `make format`

## Workflow Principles

- When working on a component (for example, `components/kvengine`), first locate and fully read its `MAINTAINER_GUIDE.md` if one exists. Use it to understand the component's architecture, design decisions, and invariants before planning or making changes.
- Keep `MAINTAINER_GUIDE.md` concise and limited to durable, non-obvious architecture, design rationale, invariants, and critical flows. Exclude change history, temporary or debugging details, exhaustive inventories, and information clear from the code.
- Update it only when existing guidance becomes inaccurate or a lasting architectural concept is introduced. Consolidate or replace content instead of appending history, prefer source links over duplication, and keep its size flat unless architectural complexity genuinely grows.
- When creating issues or pull requests, prefer the templates under `.github/` (for example, `.github/ISSUE_TEMPLATE/` and `.github/pull_request_template.md`).
- When creating git commits, always use `--signoff` (or `-s`).
- Don't run all tests in the workspace as it is extremely slow. Run targeted tests.
- Add failpoint-based tests to `tests/cloud_engine_failpoints/` instead of ordinary unit or integration suites, because failpoints are global and standard Rust tests run concurrently.
- Do not run multiple `cargo` commands concurrently; they contend on package cache locks and will block with `Blocking waiting for file lock on package cache`.
- Always ensure format is ok (`make format`) before you finish your work.
- Run `make clippy` before you finish your work when the change touches Rust-related files such as `*.rs`, `Cargo.toml`, or other Cargo/workspace project files. If there are no Rust-related file changes, skip `make clippy`.
- Treat `make clippy` warnings as failures when `make clippy` is required for the submitted changes; fix warnings, do not leave them as "pass with warnings".
- When changing Grafana dashboard sources (`metrics/grafana/*.dashboard.py`), regenerate all dashboards with `./scripts/gen-tikv-details-dashboard` and commit only the resulting tracked `.json` and `.json.sha256` files. Serverless JSON and checksums are ignored local artifacts; `scripts/check-dashboards` validates their checksums when they are present locally. Do not hand-edit generated dashboard JSON unless explicitly instructed.
- **NEVER** use git to discard or revert any changes not made by you - they are proposely changed by user and you should live with that.

## Engineering Rules

This project requires extremely high code quality and maintainability. Best engineering practices must be followed at all times.

The rules below are some typical principles. They are not exhaustive, and you must always use your best judgment to **write the cleanest code possible**.

### Core Principles: Simplicity & Readability

- Boring Code - Obvious, self-explanatory > clever, minimize cognitive load
- Single Responsibility - One function, one job
- Explicit over Implicit - Clear is better than concise
- Meaningful Abstractions - Only when they reduce cognitive load
- Keep DRY - Only if it does not conflict with the above principles

### Better Maintainability

- Keep the public API surface minimal; prefer reusing existing methods
  - Prefer `pub` over `pub(crate)` unless there is a strong reason; avoid hacky visibility levels
- Don't treat "looks similar" as "equivalent"
- Abstractions must be meaningful
- Keep certainty, single source of truth - e.g. don't introduce "optional" unless absolutely necessary
- Always add clear, concise and explicit doc comments for public APIs, complex logic, and non-obvious code

For non-refactor tasks:

- Prefer minimal, necessary, localized changes (avoid drive-by refactors in `components/`)
- Follow existing code patterns, even if they are not ideal or party against our principles
  - Do your best to trade off between "ideal code", "consistent codebase", "only change what is necessary"
  - Point out any refactor chance you discovered after finishing your work, avoid changing them in the same work. Let human decides later.

### Naming Symbols

- Choosing the name that needs the least explanation, consider: verb clarity, noun specificity, context

### Testing and Test Cases

- Name tests by behavior and expectation (e.g. `test_restore_keyspace_with_failed_store`).
- For long integration tests, add brief comments before each major step to explain what the step does.
- Do not use ordered step numbers in those comments, so they stay easy to maintain when the test flow changes.

### Performance Requirements

- This project (Cloud Storage Engine) is a high performance KV system. Typical workload expectations (1 node):
  - OLTP point get (Kv Get) QPS: > 10K QPS, < 30ms P99 latency
  - Vector search QPS: > 1K QPS, < 100ms P99 latency
  - FTS QPS: > 5K QPS, < 100ms P99 latency
  - Write: > 30MB/s throughput
  - Typical data size: 1TB+
- Reduce unnecessary allocations, copies, and data structure conversions.

## Tips

- Many integration tests spin up in-process clusters and an object-store mock; keep files/ports under temp dirs.
- For panic debugging, set `CI=1 LOG_FILE=/tmp/test.log` to capture logs (panic hook may exit via `_exit(1)`).