AGENTS.md

<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at

  http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License.
-->

# Druid Operator Agent Guide

Operational guidance for AI agents working in the druid-operator repository.

## Project Structure

| Path | Purpose |
|------|---------|
| `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/` | 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. |

## Working Rules

- 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.

## Generated Artifacts

- 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.

## Key Make Targets

- `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 Sending a PR

1. If you changed `*_types.go`, run `make manifests` and `make generate`.
2. Run `make fmt vet`.
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

- 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.