github.com/nf/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.