mirror of
https://github.com/docker/compose.git
synced 2026-11-18 06:07:53 +00:00
The 'why, history and context' guidance was how the section-A findings of epic #14074 were born: comments justifying code by referencing since- deleted code. Rule 4 now asks for behavioral statements, and a Legibility section spells out the map-must-stay-truthful rules for comments, file names and error messages. Signed-off-by: Nicolas De Loof <nicolas.deloof@gmail.com>
359 lines
16 KiB
Markdown
359 lines
16 KiB
Markdown
# Contributing to Docker
|
|
|
|
Want to hack on Docker? Awesome! We have a contributor's guide that explains
|
|
[setting up a Docker development environment and the contribution
|
|
process](https://docs.docker.com/contribute/).
|
|
|
|
This page contains information about reporting issues as well as some tips and
|
|
guidelines useful to experienced open source contributors. Finally, make sure
|
|
you read our [community guidelines](#docker-community-guidelines) before you
|
|
start participating.
|
|
|
|
## Topics
|
|
|
|
- [Contributing to Docker](#contributing-to-docker)
|
|
- [Topics](#topics)
|
|
- [Reporting security issues](#reporting-security-issues)
|
|
- [Reporting other issues](#reporting-other-issues)
|
|
- [Quick contribution tips and guidelines](#quick-contribution-tips-and-guidelines)
|
|
- [Pull requests are always welcome](#pull-requests-are-always-welcome)
|
|
- [Talking to other Docker users and contributors](#talking-to-other-docker-users-and-contributors)
|
|
- [Conventions](#conventions)
|
|
- [Merge approval](#merge-approval)
|
|
- [Sign your work](#sign-your-work)
|
|
- [How can I become a maintainer?](#how-can-i-become-a-maintainer)
|
|
- [Docker community guidelines](#docker-community-guidelines)
|
|
- [Coding Style](#coding-style)
|
|
|
|
## Reporting security issues
|
|
|
|
The Docker maintainers take security seriously. If you discover a security
|
|
issue, please bring it to their attention right away!
|
|
|
|
Please **DO NOT** file a public issue, instead, send your report privately to
|
|
[security@docker.com](mailto:security@docker.com).
|
|
|
|
Security reports are greatly appreciated and we will publicly thank you for them.
|
|
We also like to send gifts—if you're into Docker swag, make sure to let
|
|
us know. We currently do not offer a paid security bounty program but are not
|
|
ruling it out in the future.
|
|
|
|
|
|
## Reporting other issues
|
|
|
|
A great way to contribute to the project is to send a detailed report when you
|
|
encounter an issue. We always appreciate a well-written, thorough bug report,
|
|
and will thank you for it!
|
|
|
|
Check that [our issue database](https://github.com/docker/compose/issues)
|
|
doesn't already include that problem or suggestion before submitting an issue.
|
|
If you find a match, you can use the "subscribe" button to get notified of
|
|
updates. Do *not* leave random "+1" or "I have this too" comments, as they
|
|
only clutter the discussion, and don't help to resolve it. However, if you
|
|
have ways to reproduce the issue or have additional information that may help
|
|
resolve the issue, please leave a comment.
|
|
|
|
When reporting issues, always include:
|
|
|
|
* The output of `docker version`.
|
|
* The output of `docker context show`.
|
|
* The output of `docker info`.
|
|
|
|
Also, include the steps required to reproduce the problem if possible and
|
|
applicable. This information will help us review and fix your issue faster.
|
|
When sending lengthy log files, consider posting them as a gist
|
|
(https://gist.github.com).
|
|
Don't forget to remove sensitive data from your log files before posting (you
|
|
can replace those parts with "REDACTED").
|
|
|
|
_Note:_
|
|
Maintainers might request additional information to diagnose an issue,
|
|
if initial reporter doesn't answer within a reasonable delay (a few weeks),
|
|
issue will be closed.
|
|
|
|
## Quick contribution tips and guidelines
|
|
|
|
This section gives the experienced contributor some tips and guidelines.
|
|
|
|
### Pull requests are always welcome
|
|
|
|
Not sure if that typo is worth a pull request? Found a bug and know how to fix
|
|
it? Do it! We will appreciate it. Any significant change, like a new feature or
|
|
a significant behavior change, should be documented as
|
|
[a GitHub issue](https://github.com/docker/compose/issues)
|
|
before anybody starts working on it.
|
|
|
|
We are always thrilled to receive pull requests. We do our best to process them
|
|
quickly. If your pull request is not accepted on the first try,
|
|
don't get discouraged!
|
|
|
|
### Talking to other Docker users and contributors
|
|
|
|
<table class="tg">
|
|
<col width="45%">
|
|
<col width="65%">
|
|
<tr>
|
|
<td>Community Slack</td>
|
|
<td>
|
|
The Docker Community has a dedicated Slack chat to discuss features and issues. You can sign-up <a href="https://www.docker.com/community/" target="_blank">with this link</a>.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Forums</td>
|
|
<td>
|
|
A public forum for users to discuss questions and explore current design patterns and
|
|
best practices about Docker and related projects in the Docker Ecosystem. To participate,
|
|
just log in with your Docker Hub account on <a href="https://forums.docker.com" target="_blank">https://forums.docker.com</a>.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>X (Twitter)</td>
|
|
<td>
|
|
You can follow <a href="https://x.com/docker" target="_blank">Docker on X</a>
|
|
to get updates on our products. You can also post us questions or just
|
|
share blogs or stories.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Stack Overflow</td>
|
|
<td>
|
|
Stack Overflow has over 17000 Docker questions listed. We regularly
|
|
monitor <a href="https://stackoverflow.com/questions/tagged/docker" target="_blank">Docker questions</a>
|
|
and so do many other knowledgeable Docker users.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
|
|
### Conventions
|
|
|
|
Fork the repository and make changes on your fork in a feature branch:
|
|
|
|
- If it's a bug fix branch, name it XXXX-something where XXXX is the number of
|
|
the issue.
|
|
- If it's a feature branch, create an enhancement issue to announce
|
|
your intentions, and name it XXXX-something where XXXX is the number of the
|
|
issue.
|
|
|
|
Submit unit tests for your changes. Go has a great test framework built in; use
|
|
it! Take a look at existing tests for inspiration. Also, end-to-end tests are
|
|
available. Run the full test suite, both unit tests and e2e tests on your
|
|
branch before submitting a pull request. See [BUILDING.md](BUILDING.md) for
|
|
instructions to build and run tests.
|
|
|
|
Before opening a pull request, run `make validate` to catch common issues that
|
|
would fail CI: out-of-sync `go.mod`/`go.sum`, missing documentation updates,
|
|
and license headers.
|
|
|
|
Write clean code. Universally formatted code promotes ease of writing, reading,
|
|
and maintenance. Formatting is enforced by `golangci-lint` (using `gofumpt`);
|
|
run `golangci-lint run ./...` or `make lint` before committing. Most editors
|
|
have plug-ins that apply formatting automatically.
|
|
|
|
Pull request descriptions should be as clear as possible and include a reference
|
|
to all the issues that they address.
|
|
|
|
We recommend following the [conventional commits](https://www.conventionalcommits.org/)
|
|
format (`type(scope): summary`, e.g. `fix(watch): handle symlinked directories`)
|
|
as it is increasingly adopted across the project. An optional body can follow
|
|
after a blank line to explain the *why* behind the change.
|
|
|
|
Code review comments may be added to your pull request. Discuss, then make the
|
|
suggested modifications and push additional commits to your feature branch. Post
|
|
a comment after pushing. New commits show up in the pull request automatically,
|
|
but the reviewers are notified only when you comment.
|
|
|
|
Pull requests must be cleanly rebased on top of the base branch without multiple branches
|
|
mixed into the PR.
|
|
|
|
**Git tip**: If your PR no longer merges cleanly, use `rebase main` in your
|
|
feature branch to update your pull request rather than `merge main`.
|
|
|
|
Before you make a pull request, squash your commits into logical units of work
|
|
using `git rebase -i` and `git push -f`. A logical unit of work is a consistent
|
|
set of patches that should be reviewed together: for example, upgrading the
|
|
version of a vendored dependency and taking advantage of its now available new
|
|
feature constitute two separate units of work. Implementing a new function and
|
|
calling it in another file constitute a single logical unit of work. The very
|
|
high majority of submissions should have a single commit, so if in doubt: squash
|
|
down to one.
|
|
|
|
After every commit, make sure the test suite passes. Include documentation
|
|
changes in the same pull request so that a revert would remove all traces of
|
|
the feature or fix.
|
|
|
|
Include an issue reference like `Closes #XXXX` or `Fixes #XXXX` in the pull
|
|
request description that closes an issue. Including references automatically
|
|
closes the issue on a merge.
|
|
|
|
Please see the [Coding Style](#coding-style) for further guidelines.
|
|
|
|
### Merge approval
|
|
|
|
Docker maintainers use the GitHub review system (Approve / Request changes) to
|
|
indicate acceptance.
|
|
|
|
A change requires at least 1 approval from a maintainer before it can be
|
|
merged.
|
|
|
|
|
|
### Sign your work
|
|
|
|
The sign-off is a simple line at the end of the explanation for the patch. Your
|
|
signature certifies that you wrote the patch or otherwise have the right to pass
|
|
it on as an open-source patch. The rules are pretty simple: if you can certify
|
|
the below (from [developercertificate.org](https://developercertificate.org/)):
|
|
|
|
```
|
|
Developer Certificate of Origin
|
|
Version 1.1
|
|
|
|
Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
|
|
660 York Street, Suite 102,
|
|
San Francisco, CA 94110 USA
|
|
|
|
Everyone is permitted to copy and distribute verbatim copies of this
|
|
license document, but changing it is not allowed.
|
|
|
|
Developer's Certificate of Origin 1.1
|
|
|
|
By making a contribution to this project, I certify that:
|
|
|
|
(a) The contribution was created in whole or in part by me and I
|
|
have the right to submit it under the open source license
|
|
indicated in the file; or
|
|
|
|
(b) The contribution is based upon previous work that, to the best
|
|
of my knowledge, is covered under an appropriate open source
|
|
license and I have the right under that license to submit that
|
|
work with modifications, whether created in whole or in part
|
|
by me, under the same open source license (unless I am
|
|
permitted to submit under a different license), as indicated
|
|
in the file; or
|
|
|
|
(c) The contribution was provided directly to me by some other
|
|
person who certified (a), (b) or (c) and I have not modified
|
|
it.
|
|
|
|
(d) I understand and agree that this project and the contribution
|
|
are public and that a record of the contribution (including all
|
|
personal information I submit with it, including my sign-off) is
|
|
maintained indefinitely and may be redistributed consistent with
|
|
this project or the open source license(s) involved.
|
|
```
|
|
|
|
Then you just add a line to every git commit message:
|
|
|
|
Signed-off-by: Joe Smith <joe.smith@email.com>
|
|
|
|
Use your real name (sorry, no pseudonyms or anonymous contributions.)
|
|
|
|
If you set your `user.name` and `user.email` git configs, you can sign your
|
|
commit automatically with `git commit -s`.
|
|
|
|
### How can I become a maintainer?
|
|
|
|
The procedures for adding new maintainers are explained in the global
|
|
[MAINTAINERS](https://github.com/docker/opensource/blob/main/MAINTAINERS)
|
|
file in the
|
|
[https://github.com/docker/opensource/](https://github.com/docker/opensource/)
|
|
repository.
|
|
|
|
Don't forget: being a maintainer is a time investment. Make sure you
|
|
will have time to make yourself available. You don't have to be a
|
|
maintainer to make a difference on the project!
|
|
|
|
## Docker community guidelines
|
|
|
|
We want to keep the Docker community awesome, growing and collaborative. We need
|
|
your help to keep it that way. To help with this we've come up with some general
|
|
guidelines for the community as a whole:
|
|
|
|
* Be nice: Be courteous, respectful and polite to fellow community members:
|
|
no regional, racial, gender or other abuse will be tolerated. We like
|
|
nice people way better than mean ones!
|
|
|
|
* Encourage diversity and participation: Make everyone in our community feel
|
|
welcome, regardless of their background and the extent of their
|
|
contributions, and do everything possible to encourage participation in
|
|
our community.
|
|
|
|
* Keep it legal: Basically, don't get us in trouble. Share only content that
|
|
you own, do not share private or sensitive information, and don't break
|
|
the law.
|
|
|
|
* Stay on topic: Make sure that you are posting to the correct channel and
|
|
avoid off-topic discussions. Remember when you update an issue or respond
|
|
to an email you are potentially sending it to a large number of people. Please
|
|
consider this before you update. Also, remember that nobody likes spam.
|
|
|
|
* Don't send emails to the maintainers: There's no need to send emails to the
|
|
maintainers to ask them to investigate an issue or to take a look at a
|
|
pull request. Instead of sending an email, GitHub mentions should be
|
|
used to ping maintainers to review a pull request, a proposal or an
|
|
issue.
|
|
|
|
## Coding Style
|
|
|
|
Unless explicitly stated, we follow all coding guidelines from the Go
|
|
community. While some of these standards may seem arbitrary, they somehow seem
|
|
to result in a solid, consistent codebase.
|
|
|
|
It is possible that the code base does not currently comply with these
|
|
guidelines. We are not looking for a massive PR that fixes this, since that
|
|
goes against the spirit of the guidelines. All new contributors should make their
|
|
best effort to clean up and make the code base better than they left it.
|
|
Obviously, apply your best judgement. Remember, the goal here is to make the
|
|
code base easier for humans to navigate and understand. Always keep that in
|
|
mind when nudging others to comply.
|
|
|
|
The rules:
|
|
|
|
1. All code should be formatted with `gofumpt` (enforced via `golangci-lint`).
|
|
2. All code should pass [`golangci-lint`](https://golangci-lint.run/) using the
|
|
project's `.golangci.yml` configuration. Run `make lint` to check locally.
|
|
3. All code should follow the guidelines covered in [Effective
|
|
Go](https://go.dev/doc/effective_go) and [Go Code Review
|
|
Comments](https://go.dev/wiki/CodeReviewComments).
|
|
4. Include code comments. Tell us the why and the context — as statements
|
|
about current behavior, not history (see [Legibility](#legibility)).
|
|
5. Document _all_ declarations and methods, even private ones. Declare
|
|
expectations, caveats and anything else that may be important. If a type
|
|
gets exported, having the comments already there will ensure it's ready.
|
|
6. Variable name length should be proportional to its context and no longer.
|
|
`noCommaALongVariableNameLikeThisIsNotMoreClearWhenASimpleCommentWouldDo`.
|
|
In practice, short methods will have short variable names and globals will
|
|
have longer names.
|
|
7. No underscores in package names. If you need a compound name, step back,
|
|
and re-examine why you need a compound name. If you still think you need a
|
|
compound name, lose the underscore.
|
|
8. No utils or helpers packages. If a function is not general enough to
|
|
warrant its own package, it has not been written generally enough to be a
|
|
part of a util package. Just leave it unexported and well-documented.
|
|
9. All tests should run with `go test` and outside tooling should not be
|
|
required. No, we don't need another unit testing framework. Assertion
|
|
packages are acceptable if they provide _real_ incremental value.
|
|
10. Even though we call these "rules" above, they are actually just
|
|
guidelines. Since you've read all the rules, you now know that.
|
|
|
|
### Legibility
|
|
|
|
Coding agents and new contributors navigate this codebase by reading it
|
|
locally: file names, doc comments, option structs and error messages are
|
|
their map. A signpost that lies produces plausible-looking regressions, so
|
|
keep the map truthful:
|
|
|
|
1. Comments state behavior, not history. "Matching the previous
|
|
`ensureNetwork` behavior" becomes meaningless — then misleading — the day
|
|
the referenced code is deleted. Say what the code guarantees instead;
|
|
history belongs in the commit message.
|
|
2. Never justify code by pointing at deleted code, commit hashes, or line
|
|
numbers in other files: they go stale silently.
|
|
3. A file's name and doc comment describe what it contains today. When the
|
|
concept a file was named after moves out or disappears, rename the file.
|
|
4. Error messages name a remedy that actually exists today.
|
|
|
|
If you are having trouble getting into the mood of idiomatic Go, we recommend
|
|
reading through [Effective Go](https://go.dev/doc/effective_go). The
|
|
[Go Blog](https://go.dev/blog/) is also a great resource. Drinking the
|
|
kool-aid is a lot easier than going thirsty.
|