We are always thrilled to receive pull requests. We do our best to process them quickly. See the contributor's guide for development setup and the review process for how maintainers review contributions. Read the AI usage policy and community guidelines before participating.
Report vulnerabilities privately to security@docker.com, not in public issues. See SECURITY.md for the reporting process and supported versions.
Search existing issues before opening a report. Include reproduction steps and the output of docker version and docker info. Remove secrets and private data from logs before sharing them. For existing reports, subscribe for updates and add useful evidence rather than “+1” comments.
Discuss significant improvements, new features, refactoring, and cleanup proposals in a GitHub issue before starting implementation. Explain the problem, proposed approach, alternatives, and user or maintenance benefit so maintainers can agree on the scope. Use a design document for larger changes when needed.
Keep changes with the component that owns them and follow the existing package layout.
api/ and client/ - Independently versioned public Go modules for API types and the API clientcmd/ and daemon/ - Engine entry points and implementationintegration/ - API integration testsdocs/ and man/ - Technical documentation and man page generationhack/ - Build, test, and validation toolingThe root module builds the engine and is not intended to be imported as a library; see Go modules. Prefer internal directories for new packages that are not intended for other modules. Keep new Go source files out of the repository root and new packages out of the legacy pkg/ directory. Regenerate vendored files with the repository's vendoring tooling rather than editing vendor/ directly.
Keep the pull request focused and explain the problem and solution in its description. Fill in the applicable sections of the pull request template. Put related issue and PR links there, using a closing keyword such as Fixes when appropriate.
Include tests for your changes; see TESTING.md for guidance and test filters. Add new integration tests under integration/ using the API client, not the deprecated integration-cli/ suite. Keep each commit passing the tests and validation relevant to its changes. Use make test-unit, make test-integration, and make validate as appropriate.
Include relevant API and reference documentation updates with the code change. User guides live in docker/docs; follow its style guide and contribution instructions. Check documentation for clarity, correctness, and broken links, and run the relevant validation. The AUTHORS file is generated from Git history; leave it unchanged.
For changes worth a user-facing changelog entry, include a brief release note, ideally one sentence. Use present tense and imperative tone; see Docker Engine release notes for examples.
Use a short imperative summary, prefixed with the affected component for scoped changes, such as daemon: or client:. Separate an optional body with a blank line and explain the problem, fix, and important constraints. See How to Write a Git Commit Message for more guidance.
Keep each commit focused on one atomic, independently reviewable change. A pull request can contain multiple commits for separate logical units of work. Prefer separate commits for unrelated changes rather than squashing them just to make the pull request a single commit. When squashing, rewrite the message to describe the resulting change, not the intermediate steps.
CI rejects GitHub issue and PR shorthand and URLs in commit messages; put those references in the PR description or comments. Use commit hashes when referring to other code changes in commit messages.
Discuss feedback, push the agreed changes, and reply briefly with what changed and which checks you ran. Temporary fixup commits are fine during review, but fold review fixes into the commits they correct before merging.
Rebase on the latest target branch (usually master) rather than merging it into your feature branch. Use git rebase -i to organize commits into logical units of work. When updating your own remote branch after rewriting commits, use git push --force-with-lease to avoid overwriting others' updates. Coordinate with collaborators before rewriting a shared branch.
Maintainers approve changes through LGTM comments or GitHub reviews; see REVIEWING for the process.
Every commit must include a Signed-off-by trailer certifying that you meet the Developer Certificate of Origin. Use a known identity (sorry, no anonymous contributions.) Configure Git's user.name and user.email, then use git commit -s to add the trailer:
Signed-off-by: Joe Smith <joe.smith@email.com>
Read and follow the shared Moby and Docker AI usage policy. Disclose which tools you used and roughly how much work they did in the issue or PR description, not in commit messages. For AI-assisted pull requests, add a Created with: <AGENT NAME> note at the end of the description. Review and edit AI-assisted content before posting; you remain responsible for the submission. Reserve Co-Authored-By trailers for human contributors, not LLMs or AI agents.
Connect through the forums, Docker Community Slack (#moby-project), or Moby Twitter feed. See project/GOVERNANCE.md for project governance.
These rules apply equally to everyone. Violations are forgiven after six months of good behavior, and minor infractions receive guidance. Obvious spammers are banned on the first occurrence. Extreme threatening, abusive, destructive, or illegal behavior is addressed immediately without strikes or forgiveness. Report abuse or appeal violations to abuse@docker.com; mistakes and misunderstandings can be reviewed.
Follow the conventions of the package you are changing, Effective Go, and Go Code Review Comments. Avoid unrelated cleanup in a focused change.
gofmt -s -w.make validate-golangci-lint to use the development container’s linter.utils or helpers packages.testing package and gotest.tools/v3/assert for new tests. Integration tests require the repository’s daemon and test harness; see TESTING.md.