# Repository Guidelines

## Project Structure

- `crates/api/pd-proto-grpc`: gRPC/protobuf API crate; `build.rs` depends on `protoc`.
- `crates/api/pd-proto-tso`: shared TSO-facing API types.
- `crates/services/pd-service-tso`: core TSO service implementation, including allocator, oracle, election, gRPC, persistence, and metrics code.
- `crates/bins/pd-tso`: `pd-tso` binary entry point.
- `crates/test-util`: shared helpers for workspace tests.
- `testing/pd-integration-tests`: integration suites covering PD + TSO behavior.
- `testing/pd-compat-tests`: compatibility suites; legacy version coverage is configured by `testing/pd-compat-tests/legacy-client-version-manifest.yaml`.
- `testing/pd-chaos-tests`: chaos and fault-oriented tests.
- `scripts/`: helper scripts for kvproto fetch and integration-test orchestration.
- `third_party/kvproto.lock`: pinned kvproto revision; `.kvproto/` is the local fetched checkout and is gitignored.
- `.github/workflows/`: CI definitions for format, clippy, unit-test, and integration-test jobs.

## Commands

- Fetch the pinned kvproto checkout: `make kvproto`
- Build the release binary: `make build`
- Build the debug binary: `make build-debug`
- Verify formatting: `make fmt`
- Run clippy with warnings denied: `make clippy`
- Run the standard local checks: `make check`
- Run workspace unit tests with nextest: `make unit-test`
- Run integration test packages: `make integration-test`
- Build and push the container image: `make image`
- `protoc` is required for builds, clippy, and tests that compile protobuf crates.
- `cargo-nextest` is required for `make unit-test` and `make integration-test`; `make unit-test` installs it automatically, while integration-test setup normally comes from the integration-tests skill.
- Docker is required for `make image` and for the scripted integration-test environment.

## Integration tests

- See `.agents/skills/integration-tests/SKILL.md`.
- Prefer that skill when asked to run integration tests. It resolves/builds `PD` from `PD_DIR` when available, falls back to `PD_IMAGE` only when no checkout can be resolved, and handles port selection, temp dir cleanup, log capture, and repeat/stability runs before invoking `make integration-test`.
- Local integration orchestration lives in `scripts/ci-run-integration-tests.sh` and `scripts/pd-rs-integration-helper.sh`.
- `PD_DIR` is authoritative when set; `PD_IMAGE` is only a fallback source for image-backed integration runs. Other relevant environment variables include `PD_REAL_ETCD_ENDPOINTS`, `PD_GO_TSO_ENDPOINT`, and `PD_TSO_STORE`.

## PD Alignment

- This project is a Rust implementation of the TSO service from the Go `PD` implementation.
- When reviewing code, proposals, or designs, including work done with the `deep-review` skill, refer to the corresponding `PD` code and docs and try to keep behavior, terminology, and design choices consistent with `PD` unless the task explicitly requires a divergence.
- If the path to `PD` is not provided in the prompt, try `PD_DIR` first, then `../pd`, then `PD_DIR` from `.env` in the workspace root directory.

## Workflow Principles

- Prefer `make` targets over raw `cargo` commands when the task depends on `KVPROTO_ROOT`, build metadata (`PD_TSO_GIT_HASH`, `PD_TSO_GIT_REF`, `PD_TSO_BUILD_TIME`), or CI parity.
- Do not hand-edit `.kvproto/`; it is a local fetched checkout and should be recreated via `make kvproto`. If the pinned kvproto version changes, update `third_party/kvproto.lock`.
- Do not run multiple `cargo` or `make` targets that invoke cargo concurrently; they will contend on cargo package cache locks.
- Prefer targeted tests during iteration. Use the smallest relevant crate or test package first, then run `make unit-test` and/or `make integration-test` when the change affects shared behavior or cross-component flows.
- Always ensure `make fmt` passes before you finish your work.
- Run `make clippy` before finishing when you touch Rust sources, `Cargo.toml`, `build.rs`, or Rust-related test/build orchestration. Treat warnings as failures.
- When changing protocol/API crates or wire behavior, check the impacted compatibility and integration suites under `testing/`.
- When touching hot-path service code under `crates/services/pd-service-tso/`, keep allocations, copies, blocking calls, and lock contention under control.
- When committing changes to git, always use a signed-off commit, for example via `git commit --signoff`.
- **NEVER** use git to discard or revert changes you did not make.

## Engineering Rules

- Prefer simple, explicit code and small, localized changes.
- Preserve existing API and protocol behavior unless the task explicitly requires a breaking change.
- Add concise doc comments for public APIs and for non-obvious invariants in TSO, election, persistence, and forwarding code.
- Avoid introducing abstractions unless they clearly reduce cognitive load for the next maintainer.
- Follow existing code patterns in the touched module even when they are not globally ideal; keep refactors separate from the main change unless they are required.
- Name tests by behavior and expectation.

## GitHub issue and PR templates

- When creating a GitHub issue for this repo, use the matching template from `.github/ISSUE_TEMPLATE/` instead of writing the issue body from scratch.
- Choose the closest issue template for the task: `bug-report.md`, `development-task.md`, `enhancement-task.md`, `feature-request.md`, or `flaky-test.md`.
- When creating a GitHub pull request, use `.github/pull_request_template.md` and keep its structure, including the issue link, test checklist, and release note section.
- If creating an issue or PR through the GitHub UI, CLI, or API, copy the body from the corresponding template file in this repo and fill in the sections.

## Tips

- `crates/services/pd-service-tso/benches/tso_hot_path.rs` is a useful reference when modifying allocator, oracle, or gRPC hot paths.
- Integration logs and helper-generated state are written under `.artifacts/` or temporary directories chosen by the helper scripts.
- `testing/pd-compat-tests/legacy-client-version-manifest.yaml` defines the legacy client versions used by compatibility tests.