github.com/varun06/docker@v1.6.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/sources/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)</th> 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="http://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 majory 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 ### Merge approval 238 239 Docker maintainers use LGTM (Looks Good To Me) in comments on the code review to 240 indicate acceptance. 241 242 A change requires LGTMs from an absolute majority of the maintainers of each 243 component affected. For example, if a change affects `docs/` and `registry/`, it 244 needs an absolute majority from the maintainers of `docs/` AND, separately, an 245 absolute majority of the maintainers of `registry/`. 246 247 For more details, see the [MAINTAINERS](MAINTAINERS) page. 248 249 ### Sign your work 250 251 The sign-off is a simple line at the end of the explanation for the patch. Your 252 signature certifies that you wrote the patch or otherwise have the right to pass 253 it on as an open-source patch. The rules are pretty simple: if you can certify 254 the below (from [developercertificate.org](http://developercertificate.org/)): 255 256 ``` 257 Developer Certificate of Origin 258 Version 1.1 259 260 Copyright (C) 2004, 2006 The Linux Foundation and its contributors. 261 660 York Street, Suite 102, 262 San Francisco, CA 94110 USA 263 264 Everyone is permitted to copy and distribute verbatim copies of this 265 license document, but changing it is not allowed. 266 267 Developer's Certificate of Origin 1.1 268 269 By making a contribution to this project, I certify that: 270 271 (a) The contribution was created in whole or in part by me and I 272 have the right to submit it under the open source license 273 indicated in the file; or 274 275 (b) The contribution is based upon previous work that, to the best 276 of my knowledge, is covered under an appropriate open source 277 license and I have the right under that license to submit that 278 work with modifications, whether created in whole or in part 279 by me, under the same open source license (unless I am 280 permitted to submit under a different license), as indicated 281 in the file; or 282 283 (c) The contribution was provided directly to me by some other 284 person who certified (a), (b) or (c) and I have not modified 285 it. 286 287 (d) I understand and agree that this project and the contribution 288 are public and that a record of the contribution (including all 289 personal information I submit with it, including my sign-off) is 290 maintained indefinitely and may be redistributed consistent with 291 this project or the open source license(s) involved. 292 ``` 293 294 Then you just add a line to every git commit message: 295 296 Signed-off-by: Joe Smith <joe.smith@email.com> 297 298 Use your real name (sorry, no pseudonyms or anonymous contributions.) 299 300 If you set your `user.name` and `user.email` git configs, you can sign your 301 commit automatically with `git commit -s`. 302 303 Note that the old-style `Docker-DCO-1.1-Signed-off-by: ...` format is still 304 accepted, so there is no need to update outstanding pull requests to the new 305 format right away, but please do adjust your processes for future contributions. 306 307 ### How can I become a maintainer? 308 309 * Step 1: Learn the component inside out 310 * Step 2: Make yourself useful by contributing code, bug fixes, support etc. 311 * Step 3: Volunteer on the IRC channel (#docker at Freenode) 312 * Step 4: Propose yourself at a scheduled docker meeting in #docker-dev 313 314 Don't forget: being a maintainer is a time investment. Make sure you 315 will have time to make yourself available. You don't have to be a 316 maintainer to make a difference on the project! 317 318 ### IRC meetings 319 320 There are two monthly meetings taking place on #docker-dev IRC to accomodate all 321 timezones. Anybody can propose a topic for discussion prior to the meeting. 322 323 If you feel the conversation is going off-topic, feel free to point it out. 324 325 For the exact dates and times, have a look at [the irc-minutes 326 repo](https://github.com/docker/irc-minutes). The minutes also contain all the 327 notes from previous meetings. 328 329 ## Docker community guidelines 330 331 We want to keep the Docker community awesome, growing and collaborative. We need 332 your help to keep it that way. To help with this we've come up with some general 333 guidelines for the community as a whole: 334 335 * Be nice: Be courteous, respectful and polite to fellow community members: 336 no regional, racial, gender, or other abuse will be tolerated. We like 337 nice people way better than mean ones! 338 339 * Encourage diversity and participation: Make everyone in our community feel 340 welcome, regardless of their background and the extent of their 341 contributions, and do everything possible to encourage participation in 342 our community. 343 344 * Keep it legal: Basically, don't get us in trouble. Share only content that 345 you own, do not share private or sensitive information, and don't break 346 the law. 347 348 * Stay on topic: Make sure that you are posting to the correct channel and 349 avoid off-topic discussions. Remember when you update an issue or respond 350 to an email you are potentially sending to a large number of people. Please 351 consider this before you update. Also remember that nobody likes spam. 352 353 ### Guideline violations — 3 strikes method 354 355 The point of this section is not to find opportunities to punish people, but we 356 do need a fair way to deal with people who are making our community suck. 357 358 1. First occurrence: We'll give you a friendly, but public reminder that the 359 behavior is inappropriate according to our guidelines. 360 361 2. Second occurrence: We will send you a private message with a warning that 362 any additional violations will result in removal from the community. 363 364 3. Third occurrence: Depending on the violation, we may need to delete or ban 365 your account. 366 367 **Notes:** 368 369 * Obvious spammers are banned on first occurrence. If we don't do this, we'll 370 have spam all over the place. 371 372 * Violations are forgiven after 6 months of good behavior, and we won't hold a 373 grudge. 374 375 * People who commit minor infractions will get some education, rather than 376 hammering them in the 3 strikes process. 377 378 * The rules apply equally to everyone in the community, no matter how much 379 you've contributed. 380 381 * Extreme violations of a threatening, abusive, destructive or illegal nature 382 will be addressed immediately and are not subject to 3 strikes or forgiveness. 383 384 * Contact abuse@docker.com to report abuse or appeal violations. In the case of 385 appeals, we know that mistakes happen, and we'll work with you to come up with a 386 fair solution if there has been a misunderstanding. 387