rust/greptimedb
1
0
Fork 0
mirror of https://github.com/GreptimeTeam/greptimedb.git synced 2026-09-20 20:25:36 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
9fcfeff9ce876522fe2c47d2c47d7ea5fffa3c89
greptimedb/AGENTS.md
T
dennis zhuang 5d4699db1c docs: refine coding agent maps (#8790) 
* docs: refine coding agent maps

Signed-off-by: Dennis Zhuang <killme2008@gmail.com>

* docs: trim license header guidance

Signed-off-by: Dennis Zhuang <killme2008@gmail.com>

* docs: update README links and project status

Signed-off-by: Dennis Zhuang <killme2008@gmail.com>

---------

Signed-off-by: Dennis Zhuang <killme2008@gmail.com>
2026-08-10 02:45:37 +00:00

6.9 KiB
Raw Blame History

AGENTS.md

Guidance for coding agents (Claude Code, Codex, ...) and contributors working in this repository. CLAUDE.md is a symlink to this file. If .local/AGENTS.md or .local/CLAUDE.md is present, you MUST read it as well — it holds personal or machine-local overrides (gitignored, not shared). To record a personal or machine-local override, write it to .local/AGENTS.md (create .local/ and the file if absent), not to this shared file.

GreptimeDB is an open-source, cloud-native observability database for unified collection and analysis of metrics, logs, and traces. It is written in Rust and provides sub-second querying at PB scale with high cost efficiency.

Core commands

Task Command
Build (debug) make build
Build (release) make build RELEASE=true
Run standalone cargo run -- standalone start
Targeted Rust tests cargo nextest run -p <package> (preferred over cargo test)
Full local Rust suite make test
SQL tests cargo sqlness bare (single case: cargo sqlness bare -t <name>)
Format make fmt (and make fmt-toml for TOML)
Lint make clippy (= cargo clippy --workspace --all-targets --all-features -- -D warnings)
Type check make check

Toolchain: Rust nightly, Protobuf compiler (>= 3.15), C/C++ build essentials. Install the test runner with cargo install cargo-nextest --locked.

Repo map

GreptimeDB is a Cargo workspace rooted at the repository; most crates live under src/ (plus tests-fuzz, tests-integration, tests/runner). Key areas:

  • Frontend / protocol: src/frontend/ (request orchestration), src/servers/ (wire protocols), src/sql/ (SQL parsing)
  • Storage engines: src/mito2/ (main time-series engine), src/metric-engine/ (metrics), src/file-engine/
  • Coordination: src/meta-srv/ (metadata & cluster control), src/meta-client/
  • Execution / statements: src/operator/ (DDL/DML, request conversion, procedures)
  • Stream / transform: src/flow/ (continuous aggregation), src/pipeline/
  • Query / index: src/query/, src/promql/, src/index/
  • Shared: src/common/, src/datatypes/, src/store-api/ (engine contract), src/catalog/, src/table/

Before editing a path, read every AGENTS.md from the repository root down to that path. The root guide always applies; a nested guide adds or overrides rules for its subtree. Changes spanning multiple subtrees must follow every applicable guide.

AGENTS.md files are maps, not manuals. Keep them short and stable: record where code lives, important boundaries or change-coupling, high-cost gotchas, and the validation entry point. Implementation details belong in code. Do not copy exhaustive test lists or workflow logic; link to the source of truth.

High-change areas and specialized test suites carry their own AGENTS.md with a module map, read/write paths, change-coupling points, and gotchas:

Read before changing code

High-signal entry points

  • Main binary: src/cmd/src/bin/greptime.rs
  • Configuration: src/common/config/, example TOMLs in config/
  • Error handling: src/common/error/ (ErrorExt, StatusCode)
  • Protocol implementations: src/servers/src/

Worktree safety

  • Check git status --short before editing. Preserve unrelated tracked changes and untracked files; re-read files changed by another process.
  • Do not rewrite history, force-push, or remove files in bulk unless the user explicitly requests it.
  • Update generated artifacts only through the generators documented in .agents/generated-files.md.

Validation by change type

Use the narrowest command that covers the change, then expand only when its blast radius requires it.

Change Minimum validation
One Rust crate cargo nextest run -p <package>
Cross-workspace Rust behavior make test; inspect .github/workflows/rust.yml when CI parity matters
SQL parsing, planning, execution, or output cargo sqlness bare -t <case>; inspect regenerated .result files
Persisted metadata or wire format Add/run a case under tests/compatibility/; follow its README.md and AGENTS.md
Public configuration Update example TOMLs, loading/serialization snapshots, and docs; run make config-docs
Query regression harness or DSL Follow tests/perf/AGENTS.md
Enterprise-gated code Build/test with --features enterprise where applicable and run make check-enterprise-license

Before opening a PR

  1. make fmt
  2. make clippy
  3. make test
  4. make check-udeps (run make fix-udeps if it reports unused dependencies).
  5. If you added or changed a public configuration option, update the applicable example TOMLs, configuration-loading and serialized-config snapshot tests, and related user-facing documentation. Run make config-docs (needs Docker) and commit the regenerated config/config.md.
  6. If you changed a persisted or wire format, add a compatibility test case (see .agents/architecture-invariants.md).
  7. If you added or gated an enterprise-only file, give it the enterprise license header, list it in licenserc-enterprise.toml (includes) and licenserc.toml (excludes), and run make check-enterprise-license.
  8. Use a conventional-commit title, sign off commits (git commit -s), and sign the CLA.
  9. When creating or updating a pull request, follow .github/pull_request_template.md: include the CLA statement, fill the change-intention section with enough detail, and update checklist items accurately.

More

Reference in New Issue View Git Blame Copy Permalink