github.com/iamlotus/docker@v1.8.1/docs/project/advanced-contributing.md (about) 1 <!--[metadata]> 2 +++ 3 title = "Advanced contributing" 4 description = "Explains workflows for refactor and design proposals" 5 keywords = ["contribute, project, design, refactor, proposal"] 6 [menu.main] 7 parent = "smn_contribute" 8 weight=6 9 +++ 10 <![end-metadata]--> 11 12 # Advanced contributing 13 14 In this section, you learn about the more advanced contributions you can make. 15 They are advanced because they have a more involved workflow or require greater 16 programming experience. Don't be scared off though, if you like to stretch and 17 challenge yourself, this is the place for you. 18 19 This section gives generalized instructions for advanced contributions. You'll 20 read about the workflow but there are not specific descriptions of commands. 21 Your goal should be to understand the processes described. 22 23 At this point, you should have read and worked through the earlier parts of 24 the project contributor guide. You should also have 25 <a href="../make-a-contribution/" target="_blank"> made at least one project contribution</a>. 26 27 ## Refactor or cleanup proposal 28 29 A refactor or cleanup proposal changes Docker's internal structure without 30 altering the external behavior. To make this type of proposal: 31 32 1. Fork `docker/docker`. 33 34 2. Make your changes in a feature branch. 35 36 3. Sync and rebase with `master` as you work. 37 38 3. Run the full test suite. 39 40 4. Submit your code through a pull request (PR). 41 42 The PR's title should have the format: 43 44 **Cleanup:** _short title_ 45 46 If your changes required logic changes, note that in your request. 47 48 5. Work through Docker's review process until merge. 49 50 51 ## Design proposal 52 53 A design proposal solves a problem or adds a feature to the Docker software. 54 The process for submitting design proposals requires two pull requests, one 55 for the design and one for the implementation. 56 57 ![Simple process](/project/images/proposal.png) 58 59 The important thing to notice is that both the design pull request and the 60 implementation pull request go through a review. In other words, there is 61 considerable time commitment in a design proposal; so, you might want to pair 62 with someone on design work. 63 64 The following provides greater detail on the process: 65 66 1. Come up with an idea. 67 68 Ideas usually come from limitations users feel working with a product. So, 69 take some time to really use Docker. Try it on different platforms; explore 70 how it works with different web applications. Go to some community events 71 and find out what other users want. 72 73 2. Review existing issues and proposals to make sure no other user is proposing a similar idea. 74 75 The design proposals are <a 76 href="https://github.com/docker/docker/pulls?q=is%3Aopen+is%3Apr+label% 77 3Akind%2Fproposal" target="_blank">all online in our GitHub pull requests</a>. 78 79 3. Talk to the community about your idea. 80 81 We have lots of <a href="../get-help/" target="_blank">community forums</a> 82 where you can get feedback on your idea. Float your idea in a forum or two 83 to get some commentary going on it. 84 85 4. Fork `docker/docker` and clone the repo to your local host. 86 87 5. Create a new Markdown file in the area you wish to change. 88 89 For example, if you want to redesign our daemon create a new file under the 90 `daemon/` folder. 91 92 6. Name the file descriptively, for example `redesign-daemon-proposal.md`. 93 94 7. Write a proposal for your change into the file. 95 96 This is a Markdown file that describes your idea. Your proposal 97 should include information like: 98 99 * Why is this change needed or what are the use cases? 100 * What are the requirements this change should meet? 101 * What are some ways to design/implement this feature? 102 * Which design/implementation do you think is best and why? 103 * What are the risks or limitations of your proposal? 104 105 This is your chance to convince people your idea is sound. 106 107 8. Submit your proposal in a pull request to `docker/docker`. 108 109 The title should have the format: 110 111 **Proposal:** _short title_ 112 113 The body of the pull request should include a brief summary of your change 114 and then say something like "_See the file for a complete description_". 115 116 9. Refine your proposal through review. 117 118 The maintainers and the community review your proposal. You'll need to 119 answer questions and sometimes explain or defend your approach. This is 120 chance for everyone to both teach and learn. 121 122 10. Pull request accepted. 123 124 Your request may also be rejected. Not every idea is a good fit for Docker. 125 Let's assume though your proposal succeeded. 126 127 11. Implement your idea. 128 129 Implementation uses all the standard practices of any contribution. 130 131 * fork `docker/docker` 132 * create a feature branch 133 * sync frequently back to master 134 * test as you go and full test before a PR 135 136 If you run into issues, the community is there to help. 137 138 12. When you have a complete implementation, submit a pull request back to `docker/docker`. 139 140 13. Review and iterate on your code. 141 142 If you are making a large code change, you can expect greater scrutiny 143 during this phase. 144 145 14. Acceptance and merge! 146 147 ## About the advanced process 148 149 Docker is a large project. Our core team gets a great many design proposals. 150 Design proposal discussions can span days, weeks, and longer. The number of comments can reach the 100s. 151 In that situation, following the discussion flow and the decisions reached is crucial. 152 153 Making a pull request with a design proposal simplifies this process: 154 * you can leave comments on specific design proposal line 155 * replies around line are easy to track 156 * as a proposal changes and is updated, pages reset as line items resolve 157 * GitHub maintains the entire history 158 159 While proposals in pull requests do not end up merged into a master repository, they provide a convenient tool for managing the design process.