mirror of https://github.com/GreptimeTeam/greptimedb.git synced 2026-07-04 13:00:38 +00:00

Files

dennis zhuang 3b8f55e490 docs(agents): add per-crate guides, architecture invariants, and generated-files list (#8346 )

* docs(agents): add per-crate guides, architecture invariants, and generated-files list

Add agent/contributor navigation docs modeled on the AGENTS.md convention:

- Per-crate AGENTS.md for hot crates (mito2, metric-engine, flow, frontend,
  meta-srv): module map, read/write paths, change-coupling points, test
  commands, and gotchas.
- .agents/architecture-invariants.md: repo-wide rules that clippy and the
  style guide do not cover (format compatibility, crate layering, async
  runtimes, error handling, experimental gating, the DataFusion fork).
- .agents/generated-files.md: tool-generated artifacts that must not be
  hand-edited (sqlness .result, config.md, dashboards, build.rs output, proto).
- Anchor the .gitignore CLAUDE.md/AGENTS.md rules to the repo root so per-crate
  AGENTS.md files are tracked while root-level personal config stays ignored.

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

* chore: update crate AGENTS.md and fix config.md path

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

* docs(agents): fix DataFusion patch layout and SQL query lifecycle order

Address review feedback on #8346:

- architecture-invariants: the DataFusion sub-crates pin an exact crates.io
  version in [workspace.dependencies] and are redirected to the fork rev in
  [patch.crates-io]; the two sections hold different forms, not the same rev.
- frontend: the SQL query lifecycle runs the pre_parsing/post_parsing
  interceptors around parsing, before the per-statement permission check.

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

---------

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

2026-06-24 09:14:09 +00:00

1.9 KiB

Raw Permalink Blame History

Generated Files — Do Not Hand-Edit

These artifacts are produced by tooling. Editing them by hand is almost always wrong: your change is either overwritten on regeneration or causes CI to fail. When the underlying source changes, regenerate them with the listed command.

sqlness `.result` files — `tests/cases/**/*.result`

Generated by the sqlness runner from the sibling .sql files. Never edit a .result by hand. To update expectations, change the .sql (or the engine behavior) and re-run the test; the runner rewrites the .result.

cargo sqlness bare            # run all local cases
cargo sqlness bare -t <name>  # run one case

Review the regenerated output with git diff tests.

Note: tests/cases/distributed/common is a symlink to tests/cases/standalone/common. They are the same files — editing one changes both, and there is no need to diff standalone vs distributed.

Configuration docs — `config/config.md`

Generated from the config/*.example.toml files and config/config-docs-template.md.

make config-docs

Edit the example TOMLs and/or the template, then regenerate. Do not edit config/config.md directly.

Grafana dashboards

Generated artifacts; regenerate rather than editing by hand.

make dashboards

`build.rs`-generated code

Some crates generate code at build time into the Cargo OUT_DIR (e.g. common-version for build/git info, plus common-catalog, common-function's system tables, log-store, servers). There is no checked-in file to edit — change the corresponding build.rs or its inputs instead.

Protobuf / gRPC types

Generated from the external greptime-proto crate, not from sources in this repo. To change the wire format, change greptime-proto upstream and bump the dependency.

License headers

Managed by the license-header tooling and the pre-commit hooks; let the tooling add/fix them rather than editing headers by hand.

1.9 KiB Raw Permalink Blame History