diff --git a/AGENTS.md b/AGENTS.md index 04ec54c..9b38de7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,109 +17,66 @@ specific language governing permissions and limitations under the License. --> -# Druid Operator — Agent Guide +# Druid Operator Agent Guide -This document provides guidance for AI agents working on the druid-operator codebase. It is a Go-based Kubernetes operator for [Apache Druid](https://druid.apache.org/), built with [Kubebuilder v3](https://book.kubebuilder.io/). +Operational guidance for AI agents working in the druid-operator repository. ## Project Structure | Path | Purpose | |------|---------| -| `apis/druid/v1alpha1/` | CRD type definitions (`Druid`, `DruidIngestion`). Edit here to change the API. | +| `apis/druid/v1alpha1/` | API types for `Druid` and `DruidIngestion`. | | `controllers/druid/` | Reconciler logic for the `Druid` custom resource. | | `controllers/ingestion/` | Reconciler logic for the `DruidIngestion` custom resource. | -| `pkg/druidapi/` | Client for the Druid HTTP API. | -| `pkg/http/` | Shared HTTP utilities. | -| `pkg/util/` | General-purpose utilities. | -| `chart/` | Helm chart for deploying the operator. CRDs live under `chart/crds/` and are **generated** — do not edit them by hand. | -| `config/` | Kustomize manifests for CRDs, RBAC, manager, samples, and related deployment config. Only `config/crd/bases/` and `config/rbac/role.yaml` are generated — do not edit those by hand. | -| `e2e/` | End-to-end tests. Requires a [kind](https://kind.sigs.k8s.io/) cluster. | -| `docs/` | Documentation, including API specifications generated from Go types. | -| `hack/` | Boilerplate and tooling scripts. | - -## Code Standards - -- All source files must include the Apache 2.0 license header. This is audited by `make rat` in CI. New files without a header will fail the check. -- `zz_generated.deepcopy.go` is auto-generated by `controller-gen`. Never edit it manually — run `make generate` instead. -- CRD YAML files under `config/crd/bases/` and `chart/crds/` have their Apache header prepended automatically by `make manifests`. Do not add the header manually to these files. -- Follow standard Go conventions. Run `make fmt` and `make vet` before committing. +| `pkg/` | Shared libraries such as the Druid API client, HTTP helpers, and utilities. | +| `config/` | Kustomize config for CRDs, RBAC, manager, samples, and deployment manifests. | +| `chart/` | Helm chart for the operator, including generated CRDs under `chart/crds/`. | +| `e2e/` | End-to-end test scripts and manifests. | +| `docs/` | Project docs, including generated API reference docs. | +| `hack/` | Boilerplate, templates, and tooling support files. | -## Key Make Targets - -Run `make help` to see all available targets with descriptions. - -### After editing `*_types.go` (API changes) - -These two commands **must** be run together whenever the CRD types change: - -```shell -make manifests # Regenerate CRDs, RBAC role, and webhook config -make generate # Regenerate DeepCopy methods (zz_generated.deepcopy.go) -``` - -### Formatting and linting - -```shell -make fmt # Run go fmt -make vet # Run go vet -``` - -### Testing +## Working Rules -```shell -make test # Unit tests using envtest (no real cluster required) -make e2e # End-to-end tests (requires kind cluster — see below) -``` +- Hand-written source, docs, and config files generally need the Apache 2.0 header. +- Do not infer header requirements from file extension alone. `make rat` excludes some paths, including shell scripts, `zz_generated.*.go`, `PROJECT`, `.asf.yaml`, and some binary or checksum artifacts. +- Never hand-edit generated files. Regenerate them with the owning Make target. +- Follow standard Go conventions. Run `make fmt` and `make vet` when validating code changes. -### License audit +## Generated Artifacts -```shell -make rat # Apache RAT license header check -``` +- After editing `*_types.go`, run both `make manifests` and `make generate`. +- `apis/druid/v1alpha1/zz_generated.deepcopy.go` is generated by `make generate`. +- `config/crd/bases/*.yaml` and `config/rbac/role.yaml` are generated by `make manifests`. +- `chart/crds/*.yaml` is generated output and must not be edited by hand. +- `make manifests` prepends Apache headers to the generated YAML files it owns. Do not add those headers manually. -### Documentation - -```shell -make api-docs # Regenerate docs/api_specifications/druid.md from Go types -``` - -### Building - -```shell -make build # Compile the manager binary to bin/manager -make docker-build # Build the operator Docker image -``` - -## Running Locally with kind - -```shell -make kind # Bootstrap a local kind cluster -make install # Install CRDs into the cluster -make run # Run the operator from your host (no image build needed) -``` - -For E2E tests, the full flow is: +## Key Make Targets -```shell -make kind -make e2e -``` +- `make help`: list available targets. +- `make test`: runs `manifests`, `generate`, `fmt`, `vet`, envtest setup, and `go test ./...`. +- `make build`: lighter local compile path, but still runs `manifests`, `generate`, `fmt`, and `vet` first. +- `make docker-build`: heavyweight verification plus image build because it depends on `make test`. +- `make kind`: bootstrap a local kind cluster. +- `make e2e`: run end-to-end tests; assumes a working kind cluster. +- `make api-docs`: regenerate `docs/api_specifications/druid.md` after CRD API changes. +- `make rat`: run the Apache RAT license audit. -## Before Submitting a PR +## Before Sending a PR -1. Run `make manifests generate` if you touched any `*_types.go` file. +1. If you changed `*_types.go`, run `make manifests` and `make generate`. 2. Run `make fmt vet`. -3. Run `make test` — all unit tests must pass. -4. Run `make rat` — all files must have the Apache license header. -5. If you changed the CRD API, run `make api-docs` to update `docs/api_specifications/druid.md`. -6. Verify the checklist in `.github/pull_request_template.md`: - - Tested on a real Kubernetes cluster. - - Backward compatibility verified (or breaking changes noted). - - Documentation updated for new or modified behavior. +3. Run `make test`. +4. Run `make rat`. +5. If you changed the CRD API, run `make api-docs`. +6. Check `.github/pull_request_template.md` and ensure the change: + - was tested on a real Kubernetes cluster when applicable, + - considered backward compatibility or called out breaking changes, + - adds comments explaining the "why" where intent is not obvious, + - updates docs for new or changed behavior. ## Common Pitfalls -- **Stale generated files**: Editing `*_types.go` without running `make manifests generate` will cause the CRDs and DeepCopy methods to drift from the types. CI will catch this but it is easy to miss locally. -- **Missing license headers**: Any new file (`.go`, `.yaml`, etc.) needs an Apache 2.0 header. Check `hack/boilerplate.go.txt` for the Go header template. -- **E2E without kind**: `make e2e` assumes a kind cluster is running and configured. Running it without one will fail immediately. -- **Hand-editing generated YAMLs**: Changes to `config/crd/bases/*.yaml`, `chart/crds/*.yaml`, or `config/rbac/role.yaml` will be overwritten by the next `make manifests` run. +- Editing `*_types.go` without regenerating manifests and DeepCopy code. +- Hand-editing generated YAML under `config/crd/bases/`, `config/rbac/role.yaml`, or `chart/crds/`. +- Adding license headers mechanically to excluded or generated files. +- Treating `make docker-build` as a cheap local smoke test. \ No newline at end of file