This is an automated email from the ASF dual-hosted git repository.
adheipsingh pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/druid-operator.git
The following commit(s) were added to refs/heads/master by this push:
new 1075589 Update AGENTS.md (#14)
1075589 is described below
commit 107558984d6d6d281f1443e16f170207d529e85e
Author: Razin Bouzar <[email protected]>
AuthorDate: Sun Apr 12 21:01:58 2026 -0700
Update AGENTS.md (#14)
---
AGENTS.md | 129 +++++++++++++++++++++-----------------------------------------
1 file changed, 43 insertions(+), 86 deletions(-)
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
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
