Development workflow

End-to-end loop for changing Moby code: branch, build, test, PR, merge.

Branch model

The project tracks the active development tip on master. Long-lived release branches (19.03, 25.0, 27.0, etc.) follow the policy in project/BRANCHES-AND-TAGS.md. Engine releases are tagged with docker-vX.Y.Z and the API and client sub-modules tag independently as api/v1.x.x and client/v1.x.x.

Local cycle

git checkout -b my-feature
# edit code
make validate-gofmt
make test-unit                  # fast feedback
TESTDIRS=./daemon/... make test-unit  # scoped unit tests
make test-integration           # slow, full suite
git commit -s -m "subsystem: short summary"

The -s flag is required (DCO). make validate runs the same checks CI does: gofmt, vendor consistency, swagger, golangci-lint, package isolation, license headers.

Editing the API

The Engine API is wire-compatible across many versions. When you add or change an endpoint:

1. Update api/swagger.yaml.
2. Add or update the corresponding type under api/types/<area>/.
3. Add or update the router under daemon/server/router/<area>/ and the backend method on Daemon.
4. Add an integration test under integration/<area>/.
5. Update docs/api/version-history.md and the per-version stability notes. The CHANGELOG lives at api/docs/CHANGELOG.md (see api/README.md).
6. Run make swagger-gen if you regenerate types. Validate with make validate-swagger.

Vendoring

Dependencies are vendored under vendor/. Update via:

make vendor                     # implicitly: hack/vendor.sh

make validate-vendor checks that vendor/ is consistent with go.mod/go.sum.

Commit and PR style

• One logical change per commit. Squash review fixups before merge.
• Subject line: subsystem: short summary (e.g. daemon: fix container kill race). Lowercase summary.
• Wrap the body at ~72 chars.
• Reference issues with Fixes #1234 when appropriate.
• Add a Signed-off-by trailer.

CI

PR CI runs in GitHub Actions. Key workflows in .github/workflows/:

Workflow	Role
ci.yml	Linux unit + integration tests across distros and graphdrivers.
arm64.yml	ARM64 build & test.
windows-2022.yml, windows-2025.yml	Windows build & integration.
bin-image.yml	Builds the engine container images for releases.
buildkit.yml	Cross-checks BuildKit integration.
validate-pr.yml	DCO, milestone, lint and other PR-only checks.
codeql.yml, zizmor.yml	Security analysis.

CI failures should be fixed before re-requesting review. The validation logic lives under hack/validate/ and is the same code used by make validate.

Merge

Merging requires LGTM from at least two maintainers. Maintainers (commit bit holders) and reviewers are listed in MAINTAINERS.