# Repository Guidelines

## Project Structure & Module Organization
This repository is split into module-local Go services; there is no root `go.mod`, so work from the relevant subdirectory.

- `global/`: control plane API, workflow workers, CLI, and shared deployment assets.
- `regional/`: region-scoped execution service used by the global control plane.
- `pipeline/`: metrics collector runtime and Prometheus-facing binaries.
- `helm-charts/`: deployable charts for `pipeline` and Prometheus assets.
- `docs/`: design notes, release guides, and validation procedures.
- `pipeline/tools/local-e2e/`: shell-based local validation scripts and test configs.

## Build, Test, and Development Commands
Run commands from the target module directory.

- `cd global && make run-server`: start the global API server with local config.
- `cd global && make run-workflow`: start background workflow workers.
- `cd regional && make run`: run the regional service locally.
- `cd pipeline && make run`: run the collector with example configs.
- `cd pipeline && make prometheus-run`: run the Prometheus binary.
- `cd global && make build`, `cd regional && make build`, `cd pipeline && make build-pipeline`: build release binaries.
- `cd global && make proto`, `cd regional && make proto`, `cd pipeline/api/integration/prometheus && make proto`: regenerate protobuf, gateway, and swagger artifacts.

## Coding Style & Naming Conventions
Use standard Go formatting: run `gofmt` on edited files before review. Keep package names lowercase, exported identifiers in `CamelCase`, and tests in `*_test.go`. Favor small package-local helpers over cross-module coupling. Do not hand-edit generated files such as `*.pb.go`, `*.pb.gw.go`, or swagger JSON; regenerate them from `api/` sources.

## Testing Guidelines
Use `go test ./...` in the module you changed; run all three modules for shared behavior changes. The codebase uses the standard `testing` package plus `testify` in several packages. For proto or pipeline config changes, add a targeted local E2E pass with scripts under `pipeline/tools/local-e2e/`.

## Commit & Pull Request Guidelines
Recent history mixes short imperative subjects and optional Conventional Commit prefixes, for example `fix: align tidb-x support` and `support alibaba cloud integration`. Keep commit titles concise, imperative, and scoped to one change. PRs should state the affected module (`global`, `regional`, `pipeline`), summarize operational impact, list validation commands run, and attach config diffs or screenshots only when deployment or docs behavior changes.

## Security & Configuration Tips
Use checked-in files under `deployment/config/local/` and `pipeline/example/` as templates only. Never commit real credentials, API keys, or environment-specific endpoints.