mirror of
https://github.com/GreptimeTeam/greptimedb.git
synced 2026-07-03 20:40:37 +00:00
de873a9f06
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>
92 lines
4.1 KiB
Markdown
92 lines
4.1 KiB
Markdown
# 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:
|
|
|
|
- [`src/mito2/AGENTS.md`](src/mito2/AGENTS.md)
|
|
- [`src/metric-engine/AGENTS.md`](src/metric-engine/AGENTS.md)
|
|
- [`src/flow/AGENTS.md`](src/flow/AGENTS.md)
|
|
- [`src/frontend/AGENTS.md`](src/frontend/AGENTS.md)
|
|
- [`src/meta-srv/AGENTS.md`](src/meta-srv/AGENTS.md)
|
|
|
|
## Read before changing code
|
|
|
|
- [`.agents/architecture-invariants.md`](.agents/architecture-invariants.md) —
|
|
repo-wide rules that are easy to violate and expensive to get wrong (persisted/
|
|
wire format compatibility, crate layering, async runtimes, error handling,
|
|
feature gating, the DataFusion fork).
|
|
- [`.agents/generated-files.md`](.agents/generated-files.md) — tool-generated
|
|
artifacts that must not be hand-edited (sqlness `.result`, `config/config.md`,
|
|
Grafana dashboards, proto).
|
|
- [`docs/style-guide.md`](docs/style-guide.md) — code style.
|
|
- [`CONTRIBUTING.md`](CONTRIBUTING.md) — contribution flow and CLA.
|
|
|
|
## 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
|
|
|
|
- Agent skills and resources: [`.agents/`](.agents/) (see [`.agents/README.md`](.agents/README.md))
|
|
- Architecture decisions: [`docs/rfcs/`](docs/rfcs/)
|
|
- How-to guides: [`docs/how-to/`](docs/how-to/)
|