github.com/a4a881d4/docker@v1.9.0-rc2/CONTRIBUTING.md (about) 1 # Contributing to Docker 2 3 Want to hack on Docker? Awesome! We have a contributor's guide that explains 4 [setting up a Docker development environment and the contribution 5 process](https://docs.docker.com/project/who-written-for/). 6 7 ![Contributors guide](docs/static_files/contributors.png) 8 9 This page contains information about reporting issues as well as some tips and 10 guidelines useful to experienced open source contributors. Finally, make sure 11 you read our [community guidelines](#docker-community-guidelines) before you 12 start participating. 13 14 ## Topics 15 16 * [Reporting Security Issues](#reporting-security-issues) 17 * [Design and Cleanup Proposals](#design-and-cleanup-proposals) 18 * [Reporting Issues](#reporting-other-issues) 19 * [Quick Contribution Tips and Guidelines](#quick-contribution-tips-and-guidelines) 20 * [Community Guidelines](#docker-community-guidelines) 21 22 ## Reporting security issues 23 24 The Docker maintainers take security seriously. If you discover a security 25 issue, please bring it to their attention right away! 26 27 Please **DO NOT** file a public issue, instead send your report privately to 28 [security@docker.com](mailto:security@docker.com). 29 30 Security reports are greatly appreciated and we will publicly thank you for it. 31 We also like to send gifts—if you're into Docker schwag, make sure to let 32 us know. We currently do not offer a paid security bounty program, but are not 33 ruling it out in the future. 34 35 36 ## Reporting other issues 37 38 A great way to contribute to the project is to send a detailed report when you 39 encounter an issue. We always appreciate a well-written, thorough bug report, 40 and will thank you for it! 41 42 Check that [our issue database](https://github.com/docker/docker/issues) 43 doesn't already include that problem or suggestion before submitting an issue. 44 If you find a match, add a quick "+1" or "I have this problem too." Doing this 45 helps prioritize the most common problems and requests. **DO NOT DO THAT** to 46 subscribe to the issue unless you have something meaningful to add to the 47 conversation. The best way to subscribe the issue is by clicking Subscribe 48 button in top right of the page. 49 50 When reporting issues, please include your host OS (Ubuntu 12.04, Fedora 19, 51 etc). Please include: 52 53 * The output of `uname -a`. 54 * The output of `docker version`. 55 * The output of `docker info`. 56 57 Please also include the steps required to reproduce the problem if possible and 58 applicable. This information will help us review and fix your issue faster. 59 60 **Issue Report Template**: 61 62 ``` 63 Description of problem: 64 65 66 `docker version`: 67 68 69 `docker info`: 70 71 72 `uname -a`: 73 74 75 Environment details (AWS, VirtualBox, physical, etc.): 76 77 78 How reproducible: 79 80 81 Steps to Reproduce: 82 1. 83 2. 84 3. 85 86 87 Actual Results: 88 89 90 Expected Results: 91 92 93 Additional info: 94 95 96 97 ``` 98 99 100 ##Quick contribution tips and guidelines 101 102 This section gives the experienced contributor some tips and guidelines. 103 104 ###Pull requests are always welcome 105 106 Not sure if that typo is worth a pull request? Found a bug and know how to fix 107 it? Do it! We will appreciate it. Any significant improvement should be 108 documented as [a GitHub issue](https://github.com/docker/docker/issues) before 109 anybody starts working on it. 110 111 We are always thrilled to receive pull requests. We do our best to process them 112 quickly. If your pull request is not accepted on the first try, 113 don't get discouraged! Our contributor's guide explains [the review process we 114 use for simple changes](https://docs.docker.com/project/make-a-contribution/). 115 116 ### Design and cleanup proposals 117 118 You can propose new designs for existing Docker features. You can also design 119 entirely new features. We really appreciate contributors who want to refactor or 120 otherwise cleanup our project. For information on making these types of 121 contributions, see [the advanced contribution 122 section](https://docs.docker.com/project/advanced-contributing/) in the 123 contributors guide. 124 125 We try hard to keep Docker lean and focused. Docker can't do everything for 126 everybody. This means that we might decide against incorporating a new feature. 127 However, there might be a way to implement that feature *on top of* Docker. 128 129 ### Talking to other Docker users and contributors 130 131 <table class="tg"> 132 <col width="45%"> 133 <col width="65%"> 134 <tr> 135 <td>Internet Relay Chat (IRC)</td> 136 <td> 137 <p> 138 IRC a direct line to our most knowledgeable Docker users; we have 139 both the <code>#docker</code> and <code>#docker-dev</code> group on 140 <strong>irc.freenode.net</strong>. 141 IRC is a rich chat protocol but it can overwhelm new users. You can search 142 <a href="https://botbot.me/freenode/docker/#" target="_blank">our chat archives</a>. 143 </p> 144 Read our <a href="https://docs.docker.com/project/get-help/#irc-quickstart" target="_blank">IRC quickstart guide</a> for an easy way to get started. 145 </td> 146 </tr> 147 <tr> 148 <td>Google Groups</td> 149 <td> 150 There are two groups. 151 <a href="https://groups.google.com/forum/#!forum/docker-user" target="_blank">Docker-user</a> 152 is for people using Docker containers. 153 The <a href="https://groups.google.com/forum/#!forum/docker-dev" target="_blank">docker-dev</a> 154 group is for contributors and other people contributing to the Docker 155 project. 156 </td> 157 </tr> 158 <tr> 159 <td>Twitter</td> 160 <td> 161 You can follow <a href="https://twitter.com/docker/" target="_blank">Docker's Twitter feed</a> 162 to get updates on our products. You can also tweet us questions or just 163 share blogs or stories. 164 </td> 165 </tr> 166 <tr> 167 <td>Stack Overflow</td> 168 <td> 169 Stack Overflow has over 7000K Docker questions listed. We regularly 170 monitor <a href="https://stackoverflow.com/search?tab=newest&q=docker" target="_blank">Docker questions</a> 171 and so do many other knowledgeable Docker users. 172 </td> 173 </tr> 174 </table> 175 176 177 ### Conventions 178 179 Fork the repository and make changes on your fork in a feature branch: 180 181 - If it's a bug fix branch, name it XXXX-something where XXXX is the number of 182 the issue. 183 - If it's a feature branch, create an enhancement issue to announce 184 your intentions, and name it XXXX-something where XXXX is the number of the 185 issue. 186 187 Submit unit tests for your changes. Go has a great test framework built in; use 188 it! Take a look at existing tests for inspiration. [Run the full test 189 suite](https://docs.docker.com/project/test-and-docs/) on your branch before 190 submitting a pull request. 191 192 Update the documentation when creating or modifying features. Test your 193 documentation changes for clarity, concision, and correctness, as well as a 194 clean documentation build. See our contributors guide for [our style 195 guide](https://docs.docker.com/project/doc-style) and instructions on [building 196 the documentation](https://docs.docker.com/project/test-and-docs/#build-and-test-the-documentation). 197 198 Write clean code. Universally formatted code promotes ease of writing, reading, 199 and maintenance. Always run `gofmt -s -w file.go` on each changed file before 200 committing your changes. Most editors have plug-ins that do this automatically. 201 202 Pull request descriptions should be as clear as possible and include a reference 203 to all the issues that they address. 204 205 Commit messages must start with a capitalized and short summary (max. 50 chars) 206 written in the imperative, followed by an optional, more detailed explanatory 207 text which is separated from the summary by an empty line. 208 209 Code review comments may be added to your pull request. Discuss, then make the 210 suggested modifications and push additional commits to your feature branch. Post 211 a comment after pushing. New commits show up in the pull request automatically, 212 but the reviewers are notified only when you comment. 213 214 Pull requests must be cleanly rebased on top of master without multiple branches 215 mixed into the PR. 216 217 **Git tip**: If your PR no longer merges cleanly, use `rebase master` in your 218 feature branch to update your pull request rather than `merge master`. 219 220 Before you make a pull request, squash your commits into logical units of work 221 using `git rebase -i` and `git push -f`. A logical unit of work is a consistent 222 set of patches that should be reviewed together: for example, upgrading the 223 version of a vendored dependency and taking advantage of its now available new 224 feature constitute two separate units of work. Implementing a new function and 225 calling it in another file constitute a single logical unit of work. The very 226 high majority of submissions should have a single commit, so if in doubt: squash 227 down to one. 228 229 After every commit, [make sure the test suite passes] 230 (https://docs.docker.com/project/test-and-docs/). Include documentation 231 changes in the same pull request so that a revert would remove all traces of 232 the feature or fix. 233 234 Include an issue reference like `Closes #XXXX` or `Fixes #XXXX` in commits that 235 close an issue. Including references automatically closes the issue on a merge. 236 237 Please do not add yourself to the `AUTHORS` file, as it is regenerated regularly 238 from the Git history. 239 240 Please see the [Coding Style](#coding-style) for further guidelines. 241 242 ### Merge approval 243 244 Docker maintainers use LGTM (Looks Good To Me) in comments on the code review to 245 indicate acceptance. 246 247 A change requires LGTMs from an absolute majority of the maintainers of each 248 component affected. For example, if a change affects `docs/` and `registry/`, it 249 needs an absolute majority from the maintainers of `docs/` AND, separately, an 250 absolute majority of the maintainers of `registry/`. 251 252 For more details, see the [MAINTAINERS](MAINTAINERS) page. 253 254 ### Sign your work 255 256 The sign-off is a simple line at the end of the explanation for the patch. Your 257 signature certifies that you wrote the patch or otherwise have the right to pass 258 it on as an open-source patch. The rules are pretty simple: if you can certify 259 the below (from [developercertificate.org](http://developercertificate.org/)): 260 261 ``` 262 Developer Certificate of Origin 263 Version 1.1 264 265 Copyright (C) 2004, 2006 The Linux Foundation and its contributors. 266 660 York Street, Suite 102, 267 San Francisco, CA 94110 USA 268 269 Everyone is permitted to copy and distribute verbatim copies of this 270 license document, but changing it is not allowed. 271 272 Developer's Certificate of Origin 1.1 273 274 By making a contribution to this project, I certify that: 275 276 (a) The contribution was created in whole or in part by me and I 277 have the right to submit it under the open source license 278 indicated in the file; or 279 280 (b) The contribution is based upon previous work that, to the best 281 of my knowledge, is covered under an appropriate open source 282 license and I have the right under that license to submit that 283 work with modifications, whether created in whole or in part 284 by me, under the same open source license (unless I am 285 permitted to submit under a different license), as indicated 286 in the file; or 287 288 (c) The contribution was provided directly to me by some other 289 person who certified (a), (b) or (c) and I have not modified 290 it. 291 292 (d) I understand and agree that this project and the contribution 293 are public and that a record of the contribution (including all 294 personal information I submit with it, including my sign-off) is 295 maintained indefinitely and may be redistributed consistent with 296 this project or the open source license(s) involved. 297 ``` 298 299 Then you just add a line to every git commit message: 300 301 Signed-off-by: Joe Smith <joe.smith@email.com> 302 303 Use your real name (sorry, no pseudonyms or anonymous contributions.) 304 305 If you set your `user.name` and `user.email` git configs, you can sign your 306 commit automatically with `git commit -s`. 307 308 Note that the old-style `Docker-DCO-1.1-Signed-off-by: ...` format is still 309 accepted, so there is no need to update outstanding pull requests to the new 310 format right away, but please do adjust your processes for future contributions. 311 312 ### How can I become a maintainer? 313 314 * Step 1: Learn the component inside out 315 * Step 2: Make yourself useful by contributing code, bug fixes, support etc. 316 * Step 3: Volunteer on the IRC channel (#docker at Freenode) 317 * Step 4: Propose yourself at a scheduled docker meeting in #docker-dev 318 319 Don't forget: being a maintainer is a time investment. Make sure you 320 will have time to make yourself available. You don't have to be a 321 maintainer to make a difference on the project! 322 323 ### IRC meetings 324 325 There are two monthly meetings taking place on #docker-dev IRC to accommodate all 326 timezones. Anybody can propose a topic for discussion prior to the meeting. 327 328 If you feel the conversation is going off-topic, feel free to point it out. 329 330 For the exact dates and times, have a look at [the irc-minutes 331 repo](https://github.com/docker/irc-minutes). The minutes also contain all the 332 notes from previous meetings. 333 334 ## Docker community guidelines 335 336 We want to keep the Docker community awesome, growing and collaborative. We need 337 your help to keep it that way. To help with this we've come up with some general 338 guidelines for the community as a whole: 339 340 * Be nice: Be courteous, respectful and polite to fellow community members: 341 no regional, racial, gender, or other abuse will be tolerated. We like 342 nice people way better than mean ones! 343 344 * Encourage diversity and participation: Make everyone in our community feel 345 welcome, regardless of their background and the extent of their 346 contributions, and do everything possible to encourage participation in 347 our community. 348 349 * Keep it legal: Basically, don't get us in trouble. Share only content that 350 you own, do not share private or sensitive information, and don't break 351 the law. 352 353 * Stay on topic: Make sure that you are posting to the correct channel and 354 avoid off-topic discussions. Remember when you update an issue or respond 355 to an email you are potentially sending to a large number of people. Please 356 consider this before you update. Also remember that nobody likes spam. 357 358 ### Guideline violations — 3 strikes method 359 360 The point of this section is not to find opportunities to punish people, but we 361 do need a fair way to deal with people who are making our community suck. 362 363 1. First occurrence: We'll give you a friendly, but public reminder that the 364 behavior is inappropriate according to our guidelines. 365 366 2. Second occurrence: We will send you a private message with a warning that 367 any additional violations will result in removal from the community. 368 369 3. Third occurrence: Depending on the violation, we may need to delete or ban 370 your account. 371 372 **Notes:** 373 374 * Obvious spammers are banned on first occurrence. If we don't do this, we'll 375 have spam all over the place. 376 377 * Violations are forgiven after 6 months of good behavior, and we won't hold a 378 grudge. 379 380 * People who commit minor infractions will get some education, rather than 381 hammering them in the 3 strikes process. 382 383 * The rules apply equally to everyone in the community, no matter how much 384 you've contributed. 385 386 * Extreme violations of a threatening, abusive, destructive or illegal nature 387 will be addressed immediately and are not subject to 3 strikes or forgiveness. 388 389 * Contact abuse@docker.com to report abuse or appeal violations. In the case of 390 appeals, we know that mistakes happen, and we'll work with you to come up with a 391 fair solution if there has been a misunderstanding. 392 393 ## Coding Style 394 395 Unless explicitly stated, we follow all coding guidelines from the Go 396 community. While some of these standards may seem arbitrary, they somehow seem 397 to result in a solid, consistent codebase. 398 399 It is possible that the code base does not currently comply with these 400 guidelines. We are not looking for a massive PR that fixes this, since that 401 goes against the spirit of the guidelines. All new contributions should make a 402 best effort to clean up and make the code base better than they left it. 403 Obviously, apply your best judgement. Remember, the goal here is to make the 404 code base easier for humans to navigate and understand. Always keep that in 405 mind when nudging others to comply. 406 407 The rules: 408 409 1. All code should be formatted with `gofmt -s`. 410 2. All code should pass the default levels of 411 [`golint`](https://github.com/golang/lint). 412 3. All code should follow the guidelines covered in [Effective 413 Go](http://golang.org/doc/effective_go.html) and [Go Code Review 414 Comments](https://github.com/golang/go/wiki/CodeReviewComments). 415 4. Comment the code. Tell us the why, the history and the context. 416 5. Document _all_ declarations and methods, even private ones. Declare 417 expectations, caveats and anything else that may be important. If a type 418 gets exported, having the comments already there will ensure it's ready. 419 6. Variable name length should be proportional to it's context and no longer. 420 `noCommaALongVariableNameLikeThisIsNotMoreClearWhenASimpleCommentWouldDo`. 421 In practice, short methods will have short variable names and globals will 422 have longer names. 423 7. No underscores in package names. If you need a compound name, step back, 424 and re-examine why you need a compound name. If you still think you need a 425 compound name, lose the underscore. 426 8. No utils or helpers packages. If a function is not general enough to 427 warrant it's own package, it has not been written generally enough to be a 428 part of a util package. Just leave it unexported and well-documented. 429 9. All tests should run with `go test` and outside tooling should not be 430 required. No, we don't need another unit testing framework. Assertion 431 packages are acceptable if they provide _real_ incremental value. 432 10. Even though we call these "rules" above, they are actually just 433 guidelines. Since you've read all the rules, you now know that. 434 435 If you are having trouble getting into the mood of idiomatic Go, we recommend 436 reading through [Effective Go](http://golang.org/doc/effective_go.html). The 437 [Go Blog](http://blog.golang.org/) is also a great resource. Drinking the 438 kool-aid is a lot easier than going thirsty.