rust/greptimedb
1
0
Fork 0
mirror of https://github.com/GreptimeTeam/greptimedb.git synced 2026-07-03 04:20:38 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
main
greptimedb/AGENTS.md
dennis zhuang de873a9f06 docs: add project-level AGENTS.md as the shared agent guide (#8358) 
docs: add project-level AGENTS.md as the shared agent/contributor guide

Promote the agent guidance that was previously a personal, gitignored root file
into a committed, contributor-facing AGENTS.md, and tie together the existing
.agents/ resources (architecture invariants, generated-files list, skills) and
the per-crate AGENTS.md guides under one auto-discoverable root entry point.

- Add root AGENTS.md: core commands, repo map, must-read rules, high-signal
  entry points, and pre-PR checks. Worded for any coding agent, not just one.
- CLAUDE.md becomes a symlink to AGENTS.md for Claude Code compatibility.
- .gitignore: stop ignoring root AGENTS.md/CLAUDE.md; ignore /.local/ instead,
  which is where personal/local agent config now lives.

Signed-off-by: Dennis Zhuang <killme2008@gmail.com>
2026-06-26 04:11:23 +00:00

4.1 KiB
Raw Permalink 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
Test cargo nextest run (preferred over cargo 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/

Hot crates 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/

Before opening a PR

  1. make fmt
  2. make clippy
  3. make test (or cargo nextest run)
  4. make check-udeps (run make fix-udeps if it reports unused dependencies).
  5. If you changed sample config under config/, 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. Use a conventional-commit title, sign off commits (git commit -s), and sign the CLA.

More