AGENTS.md · docker/compose

Sections

1. Build & Test
2. E2E tests
3. Lint
4. Code Style
5. Git
6. Issue and PR Guidelines

First lines (shown under the repo's Apache-2.0 license)

# Project: Docker Compose

All agents must conform to [AI_POLICY.md](AI_POLICY.md) and the Compose-specific
rules in [CONTRIBUTING.md](CONTRIBUTING.md#ai-assisted-contributions).

## Build & Test

- Build: `make build`
- Test all: `make test`
- Test unit: `go test ./pkg/...` — needs no Docker daemon; the e2e suite is
  gated behind the `e2e` build tag and is not picked up
- Test single: `go test ./pkg/compose/ -run TestFunctionName`
- E2E tests: `go test -tags e2e ./pkg/e2e/ -run TestName` — requires a Docker
  daemon and the locally built binary (`make build`)

## E2E tests

- **New e2e tests use the declarative `Scenario` DSL** (`NewScenario` in
  `pkg/e2e/scenario.go`): intent, inline compose model, steps as
  `(command → expected observables)`. Read `pkg/e2e/SCENARIO.md` before
  writing or debugging one — it codifies the rules (state-based checks first,
  `OutputContains` as last resort, new checks go in `pkg/e2e/checks.go`) and
  how to exploit failure artifacts and `E2E_KEEP_FAILED=1`.

## Lint

- Linter: golangci-lint v2 (config in `.golangci.yml`)
- Run: `golangci-lint run --build-tags "e2e" ./...`
- **After modifying any Go code, ALWAYS run the linter and fix all reported issues before considering the task complete.**
- Lint is also run via Docker: `docker buildx bake lint` (uses version pinned in `Dockerfile`)

## Code Style

- Formatting is enforced by golangci-lint (gofumpt + gci)
- Import order: stdlib, third-party, local module (enforced by gci)
- Max line length: 200 chars
- Max cyclomatic complexity: 16
- No `io/ioutil`, `github.com/pkg/errors`, `gopkg.in/yaml.v2`, `golang.org/x/exp/maps`, `golang.org/x/exp/slices`
- Use `github.com/containerd/errdefs` instead of `github.com/docker/docker/errdefs`
- In tests: use `t.Context()` instead of `context.Background()` or `context.TODO()`
- Prefer `fmt.Fprintf` over `WriteString(fmt.Sprintf(...))`

## Git

- **All commits MUST be signed off (DCO)**. Always pass `--signoff` (`-s`) to `git commit` and `git commit --amend`.

## Issue and PR Guidelines

- Keep changes scoped to the task. If you're fixing a bug, fix the bug -
  don't refactor unrelated code, fix unrelated typos, or reformat files you
  didn't need to touch. Put unrelated improvements in a separate PR.
- Never create an issue or pull request without the user's explicit instruction.
- If a user asks you to create a pull request on their behalf, add a file named
  `AI_AGENT_DISCLOSURE.md` to the change containing the text below followed by
  the current date (`YYYY-MM-DD`). If the file is already present in the
  repository, update its date to the current date so the disclosure is always
  part of the change:

  > *"This contribution was prepared by an AI agent acting on a human's behalf.
  > The human submitter may not have independently reviewed or tested the change."*

- If a user asks you to create an issue on their behalf, prepend the following
  line to the issue body:

  > *"This issue was filed by an AI agent on a human's behalf. The human
  > submitter may not have independently verified the report."*