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 62c9f03 Create AGENTS.md (#12)
62c9f03 is described below
commit 62c9f033a13bce321e827dc05394e780d94e0acc
Author: Razin Bouzar <[email protected]>
AuthorDate: Mon Apr 6 11:39:00 2026 -0700
Create AGENTS.md (#12)
Creating an AGENTS.MD file
---
AGENTS.md | 125 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 125 insertions(+)
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..04ec54c
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,125 @@
+<!--
+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
+
+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/).
+
+## Project Structure
+
+| Path | Purpose |
+|------|---------|
+| `apis/druid/v1alpha1/` | CRD type definitions (`Druid`, `DruidIngestion`).
Edit here to change the API. |
+| `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.
+
+## 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
+
+```shell
+make test # Unit tests using envtest (no real cluster required)
+make e2e # End-to-end tests (requires kind cluster — see below)
+```
+
+### License audit
+
+```shell
+make rat # Apache RAT license header check
+```
+
+### 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:
+
+```shell
+make kind
+make e2e
+```
+
+## Before Submitting a PR
+
+1. Run `make manifests generate` if you touched any `*_types.go` file.
+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.
+
+## 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.
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
