github.com/dlintw/docker@v1.5.0-rc4/CONTRIBUTING.md (about) 1 # Contributing to Docker 2 3 Want to hack on Docker? Awesome! Here are instructions to get you 4 started. They are probably not perfect, please let us know if anything 5 feels wrong or incomplete. 6 7 ## Topics 8 9 * [Reporting Security Issues](#reporting-security-issues) 10 * [Design and Cleanup Proposals](#design-and-cleanup-proposals) 11 * [Reporting Issues](#reporting-issues) 12 * [Build Environment](#build-environment) 13 * [Contribution Guidelines](#contribution-guidelines) 14 * [Community Guidelines](#docker-community-guidelines) 15 16 ## Reporting Security Issues 17 18 The Docker maintainers take security very seriously. If you discover a security issue, 19 please bring it to their attention right away! 20 21 Please send your report privately to [security@docker.com](mailto:security@docker.com), 22 please **DO NOT** file a public issue. 23 24 Security reports are greatly appreciated and we will publicly thank you for it. We also 25 like to send gifts - if you're into Docker shwag make sure to let us know :) 26 We currently do not offer a paid security bounty program, but are not ruling it out in 27 the future. 28 29 ## Design and Cleanup Proposals 30 31 When considering a design proposal, we are looking for: 32 33 * A description of the problem this design proposal solves 34 * A pull request, not an issue, that modifies the documentation describing 35 the feature you are proposing, adding new documentation if necessary. 36 * Please prefix your issue with `Proposal:` in the title 37 * Please review [the existing Proposals](https://github.com/docker/docker/pulls?q=is%3Aopen+is%3Apr+label%3AProposal) 38 before reporting a new one. You can always pair with someone if you both 39 have the same idea. 40 41 When considering a cleanup task, we are looking for: 42 43 * A description of the refactors made 44 * Please note any logic changes if necessary 45 * A pull request with the code 46 * Please prefix your PR's title with `Cleanup:` so we can quickly address it. 47 * Your pull request must remain up to date with master, so rebase as necessary. 48 49 ## Reporting Issues 50 51 A great way to contribute to the project is to send a detailed report when you 52 encounter an issue. We always appreciate a well-written, thorough bug report, 53 and will thank you for it! 54 55 When reporting [issues](https://github.com/docker/docker/issues) on 56 GitHub please include your host OS (Ubuntu 12.04, Fedora 19, etc). 57 Please include: 58 59 * The output of `uname -a`. 60 * The output of `docker version`. 61 * The output of `docker -D info`. 62 63 Please also include the steps required to reproduce the problem if 64 possible and applicable. This information will help us review and fix 65 your issue faster. 66 67 ### Template 68 69 ``` 70 Description of problem: 71 72 73 `docker version`: 74 75 76 `docker info`: 77 78 79 `uname -a`: 80 81 82 Environment details (AWS, VirtualBox, physical, etc.): 83 84 85 How reproducible: 86 87 88 Steps to Reproduce: 89 1. 90 2. 91 3. 92 93 94 Actual Results: 95 96 97 Expected Results: 98 99 100 Additional info: 101 102 103 104 ``` 105 106 ## Build Environment 107 108 For instructions on setting up your development environment, please 109 see our dedicated [dev environment setup 110 docs](http://docs.docker.com/contributing/devenvironment/). 111 112 ## Contribution guidelines 113 114 ### Pull requests are always welcome 115 116 We are always thrilled to receive pull requests, and do our best to 117 process them as quickly as possible. Not sure if that typo is worth a pull 118 request? Do it! We will appreciate it. 119 120 If your pull request is not accepted on the first try, don't be 121 discouraged! If there's a problem with the implementation, hopefully you 122 received feedback on what to improve. 123 124 We're trying very hard to keep Docker lean and focused. We don't want it 125 to do everything for everybody. This means that we might decide against 126 incorporating a new feature. However, there might be a way to implement 127 that feature *on top of* Docker. 128 129 ### Discuss your design on the mailing list 130 131 We recommend discussing your plans [on the mailing 132 list](https://groups.google.com/forum/?fromgroups#!forum/docker-dev) 133 before starting to code - especially for more ambitious contributions. 134 This gives other contributors a chance to point you in the right 135 direction, give feedback on your design, and maybe point out if someone 136 else is working on the same thing. 137 138 ### Create issues... 139 140 Any significant improvement should be documented as [a GitHub 141 issue](https://github.com/docker/docker/issues) before anybody 142 starts working on it. 143 144 ### ...but check for existing issues first! 145 146 Please take a moment to check that an issue doesn't already exist 147 documenting your bug report or improvement proposal. If it does, it 148 never hurts to add a quick "+1" or "I have this problem too". This will 149 help prioritize the most common problems and requests. 150 151 ### Conventions 152 153 Fork the repository and make changes on your fork in a feature branch: 154 155 - If it's a bug fix branch, name it XXXX-something where XXXX is the number of the 156 issue. 157 - If it's a feature branch, create an enhancement issue to announce your 158 intentions, and name it XXXX-something where XXXX is the number of the issue. 159 160 Submit unit tests for your changes. Go has a great test framework built in; use 161 it! Take a look at existing tests for inspiration. Run the full test suite on 162 your branch before submitting a pull request. 163 164 Update the documentation when creating or modifying features. Test 165 your documentation changes for clarity, concision, and correctness, as 166 well as a clean documentation build. See `docs/README.md` for more 167 information on building the docs and how they get released. 168 169 Write clean code. Universally formatted code promotes ease of writing, reading, 170 and maintenance. Always run `gofmt -s -w file.go` on each changed file before 171 committing your changes. Most editors have plug-ins that do this automatically. 172 173 Pull requests descriptions should be as clear as possible and include a 174 reference to all the issues that they address. 175 176 Commit messages must start with a capitalized and short summary (max. 50 177 chars) written in the imperative, followed by an optional, more detailed 178 explanatory text which is separated from the summary by an empty line. 179 180 Code review comments may be added to your pull request. Discuss, then make the 181 suggested modifications and push additional commits to your feature branch. Be 182 sure to post a comment after pushing. The new commits will show up in the pull 183 request automatically, but the reviewers will not be notified unless you 184 comment. 185 186 Pull requests must be cleanly rebased ontop of master without multiple branches 187 mixed into the PR. 188 189 **Git tip**: If your PR no longer merges cleanly, use `rebase master` in your 190 feature branch to update your pull request rather than `merge master`. 191 192 Before the pull request is merged, make sure that you squash your commits into 193 logical units of work using `git rebase -i` and `git push -f`. After every 194 commit the test suite should be passing. Include documentation changes in the 195 same commit so that a revert would remove all traces of the feature or fix. 196 197 Commits that fix or close an issue should include a reference like 198 `Closes #XXXX` or `Fixes #XXXX`, which will automatically close the 199 issue when merged. 200 201 Please do not add yourself to the `AUTHORS` file, as it is regenerated 202 regularly from the Git history. 203 204 ### Merge approval 205 206 Docker maintainers use LGTM (Looks Good To Me) in comments on the code review 207 to indicate acceptance. 208 209 A change requires LGTMs from an absolute majority of the maintainers of each 210 component affected. For example, if a change affects `docs/` and `registry/`, it 211 needs an absolute majority from the maintainers of `docs/` AND, separately, an 212 absolute majority of the maintainers of `registry/`. 213 214 For more details see [MAINTAINERS.md](project/MAINTAINERS.md) 215 216 ### Sign your work 217 218 The sign-off is a simple line at the end of the explanation for the 219 patch, which certifies that you wrote it or otherwise have the right to 220 pass it on as an open-source patch. The rules are pretty simple: if you 221 can certify the below (from 222 [developercertificate.org](http://developercertificate.org/)): 223 224 ``` 225 Developer Certificate of Origin 226 Version 1.1 227 228 Copyright (C) 2004, 2006 The Linux Foundation and its contributors. 229 660 York Street, Suite 102, 230 San Francisco, CA 94110 USA 231 232 Everyone is permitted to copy and distribute verbatim copies of this 233 license document, but changing it is not allowed. 234 235 Developer's Certificate of Origin 1.1 236 237 By making a contribution to this project, I certify that: 238 239 (a) The contribution was created in whole or in part by me and I 240 have the right to submit it under the open source license 241 indicated in the file; or 242 243 (b) The contribution is based upon previous work that, to the best 244 of my knowledge, is covered under an appropriate open source 245 license and I have the right under that license to submit that 246 work with modifications, whether created in whole or in part 247 by me, under the same open source license (unless I am 248 permitted to submit under a different license), as indicated 249 in the file; or 250 251 (c) The contribution was provided directly to me by some other 252 person who certified (a), (b) or (c) and I have not modified 253 it. 254 255 (d) I understand and agree that this project and the contribution 256 are public and that a record of the contribution (including all 257 personal information I submit with it, including my sign-off) is 258 maintained indefinitely and may be redistributed consistent with 259 this project or the open source license(s) involved. 260 ``` 261 262 Then you just add a line to every git commit message: 263 264 Signed-off-by: Joe Smith <joe.smith@email.com> 265 266 Using your real name (sorry, no pseudonyms or anonymous contributions.) 267 268 If you set your `user.name` and `user.email` git configs, you can sign your 269 commit automatically with `git commit -s`. 270 271 Note that the old-style `Docker-DCO-1.1-Signed-off-by: ...` format is still 272 accepted, so there is no need to update outstanding pull requests to the new 273 format right away, but please do adjust your processes for future contributions. 274 275 ### How can I become a maintainer? 276 277 * Step 1: Learn the component inside out 278 * Step 2: Make yourself useful by contributing code, bug fixes, support etc. 279 * Step 3: Volunteer on the IRC channel (#docker at Freenode) 280 * Step 4: Propose yourself at a scheduled docker meeting in #docker-dev 281 282 Don't forget: being a maintainer is a time investment. Make sure you 283 will have time to make yourself available. You don't have to be a 284 maintainer to make a difference on the project! 285 286 ### IRC Meetings 287 288 There are two monthly meetings taking place on #docker-dev IRC to accomodate all timezones. 289 Anybody can ask for a topic to be discussed prior to the meeting. 290 291 If you feel the conversation is going off-topic, feel free to point it out. 292 293 For the exact dates and times, have a look at [the irc-minutes repo](https://github.com/docker/irc-minutes). 294 They also contain all the notes from previous meetings. 295 296 ## Docker Community Guidelines 297 298 We want to keep the Docker community awesome, growing and collaborative. We 299 need your help to keep it that way. To help with this we've come up with some 300 general guidelines for the community as a whole: 301 302 * Be nice: Be courteous, respectful and polite to fellow community members: no 303 regional, racial, gender, or other abuse will be tolerated. We like nice people 304 way better than mean ones! 305 306 * Encourage diversity and participation: Make everyone in our community 307 feel welcome, regardless of their background and the extent of their 308 contributions, and do everything possible to encourage participation in 309 our community. 310 311 * Keep it legal: Basically, don't get us in trouble. Share only content that 312 you own, do not share private or sensitive information, and don't break the 313 law. 314 315 * Stay on topic: Make sure that you are posting to the correct channel 316 and avoid off-topic discussions. Remember when you update an issue or 317 respond to an email you are potentially sending to a large number of 318 people. Please consider this before you update. Also remember that 319 nobody likes spam. 320 321 ### Guideline Violations — 3 Strikes Method 322 323 The point of this section is not to find opportunities to punish people, but we 324 do need a fair way to deal with people who are making our community suck. 325 326 1. First occurrence: We'll give you a friendly, but public reminder that the 327 behavior is inappropriate according to our guidelines. 328 329 2. Second occurrence: We will send you a private message with a warning that 330 any additional violations will result in removal from the community. 331 332 3. Third occurrence: Depending on the violation, we may need to delete or ban 333 your account. 334 335 **Notes:** 336 337 * Obvious spammers are banned on first occurrence. If we don't do this, we'll 338 have spam all over the place. 339 340 * Violations are forgiven after 6 months of good behavior, and we won't 341 hold a grudge. 342 343 * People who commit minor infractions will get some education, 344 rather than hammering them in the 3 strikes process. 345 346 * The rules apply equally to everyone in the community, no matter how 347 much you've contributed. 348 349 * Extreme violations of a threatening, abusive, destructive or illegal nature 350 will be addressed immediately and are not subject to 3 strikes or 351 forgiveness. 352 353 * Contact abuse@docker.com to report abuse or appeal violations. In the case of 354 appeals, we know that mistakes happen, and we'll work with you to come up with 355 a fair solution if there has been a misunderstanding. 356