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