github.com/guilhermebr/docker@v1.4.2-0.20150428121140-67da055cebca/docs/sources/project/advanced-contributing.md (about)

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