Skip to content

AGENTS.md

Latest commit

 

History

History
56 lines (35 loc) · 4.88 KB

AGENTS.md

File metadata and controls

56 lines (35 loc) · 4.88 KB
Raw

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