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>
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 thee2ebuild 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
ScenarioDSL (NewScenarioininternal/e2e/scenario.go): intent, inline compose model, steps as(command → expected observables). Readinternal/e2e/SCENARIO.mdbefore writing or debugging one — it codifies the rules (state-based checks first,OutputContainsas last resort, new checks go ininternal/e2e/checks.go) and how to exploit failure artifacts andE2E_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/composeis the cobra CLI layer;pkg/apiis the public SDK contract (interfaceCompose+ option structs);pkg/composeis the backend implementation (NewComposeService). Everything else underpkg/is exported for historical reasons, not as a stability promise. - Two lifecycle engines coexist. The plan-based reconciler
(
pkg/compose/reconcile.go) is entered throughreconcile(), called frompreparePlanincreate.go(behindcreate,up,scale,watchrebuilds and the dependencies ofrun) and directly fromstart()instart.go. Theruntarget itself bypasses the plan:doPrepareRuncallscreateContainerdirectly.ReconcileScopeselects the phases the plan covers: Create (create), Create+Start (up,scale,watchrebuilds) or Start only (compose start) — the plan does start containers (OpStartContainer); interactiveuponly runs the two phases of its plan separately.stop,restart,downand the classic build still walkInDependencyOrder/InReverseDependencyOrder(internal/depgraph). - Operation convention: exported
composeServicemethods wrap the work inRun(ctx, …, "opname"), which drives theEventProcessor(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.Getenvsees only the process environment;project.Environment[...]also sees the project's.env.cmd/compose/compose.go:setEnvWithDotEnvadditionally copiesCOMPOSE_*keys from the project's env-files into the process environment duringPersistentPreRunE— 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 ofcom.docker.compose.config-hash, not just the project label. One-off (compose run) containers carryoneoff=Trueand no container-number. Lifecycle-hook helper containers are created withNoConfigHash(pre_start.go), so they have no config-hash label and those listings never see them: they are invisible topsand to the normal teardown path, anddownremoves retainedpre_startones through a dedicated sweep (down.go:removePreStartHookContainers); that sweep andgetHookContainerslist them by project label plus hook label, bypassinggetDefaultFilters. - Docker Desktop integrations (
internal/desktop, used fromup,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 inDockerfile)
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/errdefsinstead ofgithub.com/docker/docker/errdefs - In tests: use
t.Context()instead ofcontext.Background()orcontext.TODO() - Prefer
fmt.FprintfoverWriteString(fmt.Sprintf(...))
Git
- All commits MUST be signed off (DCO). Always pass
--signoff(-s) togit commitandgit 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.mdto 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."