|
| 1 | +# Contributing to Docker |
| 2 | + |
| 3 | +This page contains information about reporting issues as well as some tips and |
| 4 | +guidelines useful to experienced open source contributors. Finally, make sure |
| 5 | +you read our [community guidelines](#docker-community-guidelines) before you |
| 6 | +start participating. |
| 7 | + |
| 8 | +## Topics |
| 9 | + |
| 10 | +* [Reporting Security Issues](#reporting-security-issues) |
| 11 | +* [Reporting Issues](#reporting-other-issues) |
| 12 | +* [Quick Contribution Tips and Guidelines](#quick-contribution-tips-and-guidelines) |
| 13 | +* [Community Guidelines](#docker-community-guidelines) |
| 14 | + |
| 15 | +## Reporting security issues |
| 16 | + |
| 17 | +The Docker maintainers take security seriously. If you discover a security |
| 18 | +issue, please bring it to their attention right away! |
| 19 | + |
| 20 | +Please **DO NOT** file a public issue, instead send your report privately to |
| 21 | + |
| 22 | + |
| 23 | +Security reports are greatly appreciated and we will publicly thank you for it. |
| 24 | +We also like to send gifts—if you're into Docker schwag, make sure to let |
| 25 | +us know. We currently do not offer a paid security bounty program, but are not |
| 26 | +ruling it out in the future. |
| 27 | + |
| 28 | +## Reporting other issues |
| 29 | + |
| 30 | +A great way to contribute to the project is to send a detailed report when you |
| 31 | +encounter an issue. We always appreciate a well-written, thorough bug report, |
| 32 | +and will thank you for it! |
| 33 | + |
| 34 | +Check that [our issue database](https://github.com/docker/gen-ai-stack/issues) |
| 35 | +doesn't already include that problem or suggestion before submitting an issue. |
| 36 | +If you find a match, you can use the "subscribe" button to get notified on |
| 37 | +updates. Do *not* leave random "+1" or "I have this too" comments, as they |
| 38 | +only clutter the discussion, and don't help resolving it. However, if you |
| 39 | +have ways to reproduce the issue or have additional information that may help |
| 40 | +resolving the issue, please leave a comment. |
| 41 | + |
| 42 | +When reporting issues, always include: |
| 43 | + |
| 44 | +* The output of `docker version`. |
| 45 | +* The output of `docker info`. |
| 46 | + |
| 47 | +Also include the steps required to reproduce the problem if possible and |
| 48 | +applicable. This information will help us review and fix your issue faster. |
| 49 | +When sending lengthy log-files, consider posting them as a gist (https://gist.github.com). |
| 50 | +Don't forget to remove sensitive data from your logfiles before posting (you can |
| 51 | +replace those parts with "REDACTED"). |
| 52 | + |
| 53 | +## Quick contribution tips and guidelines |
| 54 | + |
| 55 | +This section gives the experienced contributor some tips and guidelines. |
| 56 | + |
| 57 | +### Pull requests are always welcome |
| 58 | + |
| 59 | +Not sure if that typo is worth a pull request? Found a bug and know how to fix |
| 60 | +it? Do it! We will appreciate it. Any significant improvement should be |
| 61 | +documented as [a GitHub issue](https://github.com/docker/gen-ai-stack/issues) before |
| 62 | +anybody starts working on it. |
| 63 | + |
| 64 | +We are always thrilled to receive pull requests. We do our best to process them |
| 65 | +quickly. If your pull request is not accepted on the first try, |
| 66 | +don't get discouraged! Our contributor's guide explains [the review process we |
| 67 | +use for simple changes](https://docs.docker.com/opensource/workflow/make-a-contribution/). |
| 68 | + |
| 69 | +### Talking to other Docker users and contributors |
| 70 | + |
| 71 | +<table class="tg"> |
| 72 | + <col width="45%"> |
| 73 | + <col width="65%"> |
| 74 | + <tr> |
| 75 | + <td>Community Slack</td> |
| 76 | + <td> |
| 77 | + The Docker Community has a dedicated Slack chat to discuss features and issues. You can sign-up <a href="https://dockr.ly/slack" target="_blank">with this link</a>. |
| 78 | + </td> |
| 79 | + </tr> |
| 80 | + <tr> |
| 81 | + <td>Twitter</td> |
| 82 | + <td> |
| 83 | + You can follow <a href="https://twitter.com/docker/" target="_blank">Docker's Twitter feed</a> |
| 84 | + to get updates on our products. You can also tweet us questions or just |
| 85 | + share blogs or stories. |
| 86 | + </td> |
| 87 | + </tr> |
| 88 | +</table> |
| 89 | + |
| 90 | + |
| 91 | +### Conventions |
| 92 | + |
| 93 | +Fork the repository and make changes on your fork in a feature branch: |
| 94 | + |
| 95 | +- If it's a bug fix branch, name it XXXX-something where XXXX is the number of |
| 96 | + the issue. |
| 97 | +- If it's a feature branch, create an enhancement issue to announce |
| 98 | + your intentions, and name it XXXX-something where XXXX is the number of the |
| 99 | + issue. |
| 100 | + |
| 101 | +Pull request descriptions should be as clear as possible and include a reference |
| 102 | +to all the issues that they address. |
| 103 | + |
| 104 | +Commit messages must start with a capitalized and short summary (max. 50 chars) |
| 105 | +written in the imperative, followed by an optional, more detailed explanatory |
| 106 | +text which is separated from the summary by an empty line. |
| 107 | + |
| 108 | +Code review comments may be added to your pull request. Discuss, then make the |
| 109 | +suggested modifications and push additional commits to your feature branch. Post |
| 110 | +a comment after pushing. New commits show up in the pull request automatically, |
| 111 | +but the reviewers are notified only when you comment. |
| 112 | + |
| 113 | +Pull requests must be cleanly rebased on top of master without multiple branches |
| 114 | +mixed into the PR. |
| 115 | + |
| 116 | +**Git tip**: If your PR no longer merges cleanly, use `rebase main` in your |
| 117 | +feature branch to update your pull request rather than `merge main`. |
| 118 | + |
| 119 | +Before you make a pull request, squash your commits into logical units of work |
| 120 | +using `git rebase -i` and `git push -f`. A logical unit of work is a consistent |
| 121 | +set of patches that should be reviewed together: for example, upgrading the |
| 122 | +version of a vendored dependency and taking advantage of its now available new |
| 123 | +feature constitute two separate units of work. Implementing a new function and |
| 124 | +calling it in another file constitute a single logical unit of work. The very |
| 125 | +high majority of submissions should have a single commit, so if in doubt: squash |
| 126 | +down to one. |
| 127 | + |
| 128 | +Include an issue reference like `Closes #XXXX` or `Fixes #XXXX` in the pull request |
| 129 | +description that close an issue. Including references automatically closes the issue |
| 130 | +on a merge. |
| 131 | + |
| 132 | +### Sign your work |
| 133 | + |
| 134 | +The sign-off is a simple line at the end of the explanation for the patch. Your |
| 135 | +signature certifies that you wrote the patch or otherwise have the right to pass |
| 136 | +it on as an open-source patch. The rules are pretty simple: if you can certify |
| 137 | +the below (from [developercertificate.org](https://developercertificate.org): |
| 138 | + |
| 139 | +``` |
| 140 | +Developer Certificate of Origin |
| 141 | +Version 1.1 |
| 142 | +
|
| 143 | +Copyright (C) 2004, 2006 The Linux Foundation and its contributors. |
| 144 | +660 York Street, Suite 102, |
| 145 | +San Francisco, CA 94110 USA |
| 146 | +
|
| 147 | +Everyone is permitted to copy and distribute verbatim copies of this |
| 148 | +license document, but changing it is not allowed. |
| 149 | +
|
| 150 | +Developer's Certificate of Origin 1.1 |
| 151 | +
|
| 152 | +By making a contribution to this project, I certify that: |
| 153 | +
|
| 154 | +(a) The contribution was created in whole or in part by me and I |
| 155 | + have the right to submit it under the open source license |
| 156 | + indicated in the file; or |
| 157 | +
|
| 158 | +(b) The contribution is based upon previous work that, to the best |
| 159 | + of my knowledge, is covered under an appropriate open source |
| 160 | + license and I have the right under that license to submit that |
| 161 | + work with modifications, whether created in whole or in part |
| 162 | + by me, under the same open source license (unless I am |
| 163 | + permitted to submit under a different license), as indicated |
| 164 | + in the file; or |
| 165 | +
|
| 166 | +(c) The contribution was provided directly to me by some other |
| 167 | + person who certified (a), (b) or (c) and I have not modified |
| 168 | + it. |
| 169 | +
|
| 170 | +(d) I understand and agree that this project and the contribution |
| 171 | + are public and that a record of the contribution (including all |
| 172 | + personal information I submit with it, including my sign-off) is |
| 173 | + maintained indefinitely and may be redistributed consistent with |
| 174 | + this project or the open source license(s) involved. |
| 175 | +``` |
| 176 | + |
| 177 | +Then you just add a line to every git commit message: |
| 178 | + |
| 179 | + Signed-off-by: Joe Smith <[email protected]> |
| 180 | + |
| 181 | +Use your real name (sorry, no pseudonyms or anonymous contributions.) |
| 182 | + |
| 183 | +If you set your `user.name` and `user.email` git configs, you can sign your |
| 184 | +commit automatically with `git commit -s`. |
| 185 | + |
| 186 | +## Docker community guidelines |
| 187 | + |
| 188 | +We want to keep the Docker community awesome, growing and collaborative. We need |
| 189 | +your help to keep it that way. To help with this we've come up with some general |
| 190 | +guidelines for the community as a whole: |
| 191 | + |
| 192 | +* Be nice: Be courteous, respectful and polite to fellow community members: |
| 193 | + no regional, racial, gender, or other abuse will be tolerated. We like |
| 194 | + nice people way better than mean ones! |
| 195 | + |
| 196 | +* Encourage diversity and participation: Make everyone in our community feel |
| 197 | + welcome, regardless of their background and the extent of their |
| 198 | + contributions, and do everything possible to encourage participation in |
| 199 | + our community. |
| 200 | + |
| 201 | +* Keep it legal: Basically, don't get us in trouble. Share only content that |
| 202 | + you own, do not share private or sensitive information, and don't break |
| 203 | + the law. |
| 204 | + |
| 205 | +* Stay on topic: Make sure that you are posting to the correct channel and |
| 206 | + avoid off-topic discussions. Remember when you update an issue or respond |
| 207 | + to an email you are potentially sending to a large number of people. Please |
| 208 | + consider this before you update. Also remember that nobody likes spam. |
| 209 | + |
| 210 | +* Don't send email to the maintainers: There's no need to send email to the |
| 211 | + maintainers to ask them to investigate an issue or to take a look at a |
| 212 | + pull request. Instead of sending an email, GitHub mentions should be |
| 213 | + used to ping maintainers to review a pull request, a proposal or an |
| 214 | + issue. |
| 215 | + |
| 216 | +### Guideline violations — 3 strikes method |
| 217 | + |
| 218 | +The point of this section is not to find opportunities to punish people, but we |
| 219 | +do need a fair way to deal with people who are making our community suck. |
| 220 | + |
| 221 | +1. First occurrence: We'll give you a friendly, but public reminder that the |
| 222 | + behavior is inappropriate according to our guidelines. |
| 223 | + |
| 224 | +2. Second occurrence: We will send you a private message with a warning that |
| 225 | + any additional violations will result in removal from the community. |
| 226 | + |
| 227 | +3. Third occurrence: Depending on the violation, we may need to delete or ban |
| 228 | + your account. |
| 229 | + |
| 230 | +**Notes:** |
| 231 | + |
| 232 | +* Obvious spammers are banned on first occurrence. If we don't do this, we'll |
| 233 | + have spam all over the place. |
| 234 | + |
| 235 | +* Violations are forgiven after 6 months of good behavior, and we won't hold a |
| 236 | + grudge. |
| 237 | + |
| 238 | +* People who commit minor infractions will get some education, rather than |
| 239 | + hammering them in the 3 strikes process. |
| 240 | + |
| 241 | +* The rules apply equally to everyone in the community, no matter how much |
| 242 | + you've contributed. |
| 243 | + |
| 244 | +* Extreme violations of a threatening, abusive, destructive or illegal nature |
| 245 | + will be addressed immediately and are not subject to 3 strikes or forgiveness. |
| 246 | + |
| 247 | +* Contact [email protected] to report abuse or appeal violations. In the case of |
| 248 | + appeals, we know that mistakes happen, and we'll work with you to come up with a |
| 249 | + fair solution if there has been a misunderstanding. |
| 250 | + |
0 commit comments