agones

# AGENTS.md

Rules for AI coding agents contributing to Agones. `CONTRIBUTING.md` and `build/README.md` are the source of truth for humans, and agents must follow them too. If anything here conflicts with `CONTRIBUTING.md`, follow `CONTRIBUTING.md` and note the discrepancy in the PR.

## Before you write code

- Work only from an existing, open issue that asks for the change. No drive-by, speculative, or "while I was here" PRs.
- Before starting, check the issue is not already being worked on: no assignee, no linked PR, and no recent comment from someone else taking it. Do not open a competing or duplicate PR. If it was claimed long ago with no progress, ask on the issue before taking over.
- If the issue still has open questions or unresolved discussion, do not implement it. Go back to the issue, raise the questions, and wait for the maintainers before writing code.
- Stay inside the issue's scope. One issue, one PR. Surface unrelated problems in the PR description or a new issue rather than fixing them here.

## Working with your human

- You are assisting the human contributor who is driving you, not acting on your own. When unsure, stop and ask them rather than guessing. Do not invent API names, fabricate behavior, or silence a failing check to make something pass. A clear question or a `TODO` beats a confident wrong guess.
- Keep changes minimal and match the surrounding code. Do not add comments that restate what the code does, introduce new abstractions or dependencies without justification, or reformat and rename code outside the change.

## Build, test, and lint: use the build Makefile, not host Go tools

There is no root Makefile. Builds, tests, and lint run through `build/Makefile` inside a Docker build image (the only host dependencies are Make and Docker), so invoke targets as `make -C build <target>` from the repo root.

- Validate Go changes with `make -C build lint test-go` before opening a PR, and do not claim they pass without running them. The first run builds the image and is slow.
- CI runs these targets in the build image with a pinned Go toolchain, so a passing raw `go test`, `go build`, or `golangci-lint` does not mean CI passes, and is not a substitute.
- Do not run the e2e targets (`make -C build test-e2e...`) unless asked. They need a live Kubernetes cluster and take a long time.
- Do not disable or weaken checks (deleting tests, broad `//nolint`, skipping hooks) to get a PR green. Fix the underlying issue.

## Do not hand-edit generated files

Edit the source and regenerate with the matching target. CI checks that several of these stay in sync with their source.

- `pkg/apis/**/zz_generated.deepcopy.go` and `pkg/client/**`: edit the API types in `pkg/apis/`, then `make -C build gen-crd-code`.
- gRPC and SDK code generated from the `.proto` files in `proto/` (the `*.pb*.go` files, plus the per-language SDK outputs under `sdks/` and `test/sdk/`): edit the `.proto` files, then `make -C build gen-all-sdk-grpc`, or `gen-allocation-grpc` for the allocator.
- `install/yaml/install.yaml`: edit the Helm templates under `install/helm/`, then `make -C build gen-install`.
- `site/content/en/docs/Reference/agones_crd_api_reference.html`: regenerate with `make -C build gen-api-docs`.
- `CHANGELOG.md` is updated from generated release notes at release time. Ordinary PRs should not edit it.

## Dependencies

Dependencies are vendored in `vendor/`, so do not edit it by hand. Change `go.mod`, then run `go mod tidy` and `go mod vendor` (see `build/docs/dependencies.md`).

## New source files

Start new Go files with the Apache license header, copied from an existing non-generated `.go` file. Do not copy `build/boilerplate.go.txt`, which appends an autogenerated marker and is only for generators.

## Error handling

Use `agones.dev/agones/pkg/util/errors` to create your own errors, not `github.com/pkg/errors` (blocked by a `depguard` rule in `.golangci.yml`). Scope the `Errors` value with `errors.FromStruct` for a struct's own methods, and reuse that same struct-scoped value from any free function that already has an instance to hand, rather than introducing a package-level one. Reserve `errors.FromPackage` for errors with no associated struct instance in scope. Still use the standard library `errors` package (`errors.Is`, `errors.As`, etc.) to inspect errors.

## Commits and the PR

- Sign off every commit with `git commit -s`. DCO is bot-enforced, and an unsigned commit blocks the PR.
- Squash the branch to a single commit before it merges.
- Fill in `.github/pull_request_template.md`: set one `/kind` label, describe what and why, and put `Closes #<issue>` for the issue it fixes, or `Work on #<issue>` to reference an issue without closing it.

## New features

A new feature usually sits behind a feature gate in `pkg/util/runtime/features.go` and moves through stages: alpha, then beta, then stable. Agree the design on a `kind/design` issue before writing code, and ship documentation under `site/`.

Also found in one other repository

The same file, byte for byte, in the weekly crawl of public GitHub.

• agones-dev/agones7.1k