compose/AGENTS.md
Nicolas De Loof 26a770cc98 docs(agents): add an architecture map of the non-guessable facts
AGENTS.md covered build/test/lint mechanics but nothing about how the
codebase is organized, so a reader's first mental model comes from file
names and local comments — several of which used to be misleading (see
the previous commits in this series).

The new section states, in ~35 lines, the facts a contributor cannot
derive from local reading: the two coexisting lifecycle engines and
which commands enter the plan-based reconciler versus the dependency
graph walk, the Run()/EventProcessor operation convention, the
stdout/stderr split, the two environment-resolution idioms and the
setEnvWithDotEnv timing, the config-hash label as the actual project
membership invariant, and the Docker Desktop integration points that
must fail silently.

Part of #14074 (A: the code misdescribes its own structure).

Signed-off-by: Nicolas De Loof <nicolas.deloof@gmail.com>
2026-11-16 16:10:47 +01:00

6.2 KiB

Project: Docker Compose

All agents must conform to AI_POLICY.md and the Compose-specific rules in CONTRIBUTING.md.

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 ./internal/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 internal/e2e/scenario.go): intent, inline compose model, steps as (command → expected observables). Read internal/e2e/SCENARIO.md before writing or debugging one — it codifies the rules (state-based checks first, OutputContains as last resort, new checks go in internal/e2e/checks.go) and how to exploit failure artifacts and E2E_KEEP_FAILED=1.

Architecture map

Read this before changing lifecycle or CLI code — several of these facts are not guessable from local reading.

  • Packages: cmd/compose is the cobra CLI layer; pkg/api is the public SDK contract (interface Compose + option structs); pkg/compose is the backend implementation (NewComposeService). Everything else under pkg/ is exported for historical reasons, not as a stability promise.
  • Two lifecycle engines coexist. The plan-based reconciler (pkg/compose/reconcile.go) is entered through reconcile(), called from preparePlan in create.go (behind create, up, scale, watch rebuilds and the dependencies of run) and directly from start() in start.go. The run target itself bypasses the plan: doPrepareRun calls createContainer directly. ReconcileScope selects the phases the plan covers: Create (create), Create+Start (up, scale, watch rebuilds) or Start only (compose start) — the plan does start containers (OpStartContainer); interactive up only runs the two phases of its plan separately. stop, restart, down and the classic build still walk InDependencyOrder/InReverseDependencyOrder (internal/depgraph).
  • Operation convention: exported composeService methods wrap the work in Run(ctx, …, "opname"), which drives the EventProcessor (Start/On/Done) used for progress display. Unexported methods (s.create, s.start, …) are building blocks without their own event cycle — calling an exported method from another operation nests event cycles.
  • Output conventions: progress/status rendering goes to stderr (dockerCli.Err()); stdout is reserved for command payload (ps, config, container logs' stdout stream). TTY detection for the renderer probes stderr, color detection for logs probes stdout.
  • Environment resolution has two idioms: os.Getenv sees only the process environment; project.Environment[...] also sees the project's .env. cmd/compose/compose.go:setEnvWithDotEnv additionally copies COMPOSE_* keys from the project's env-files into the process environment during PersistentPreRunE — variables read before that point (e.g. as cobra flag defaults) do not see the .env.
  • Container/project identity is label-based: container listings (pkg/compose/containers.go:getDefaultFilters) filter on the presence of com.docker.compose.config-hash, not just the project label. One-off (compose run) containers carry oneoff=True and no container-number. Lifecycle-hook helper containers are created with NoConfigHash (pre_start.go), so they have no config-hash label and those listings never see them: they are invisible to ps and to the normal teardown path, and down removes retained pre_start ones through a dedicated sweep (down.go:removePreStartHookContainers); that sweep and getHookContainers list them by project label plus hook label, bypassing getDefaultFilters.
  • Docker Desktop integrations (internal/desktop, used from up, publish, the keyboard menu) talk to Desktop over a private socket and are expected to fail silently on non-Desktop engines.

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 cognitive complexity: 30 (gocognit; gocyclo is deliberately disabled)
  • 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."