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