github.com/samsalisbury/distribution@v2.2.1-0.20151123021722-54f974340220+incompatible/CONTRIBUTING.md (about)

     1  # Contributing to the registry
     2  
     3  ## Before reporting an issue...
     4  
     5  ### If your problem is with...
     6  
     7   - automated builds
     8   - your account on the [Docker Hub](https://hub.docker.com/)
     9   - any other [Docker Hub](https://hub.docker.com/) issue
    10  
    11  Then please do not report your issue here - you should instead report it to [https://support.docker.com](https://support.docker.com)
    12  
    13  ### If you...
    14  
    15   - need help setting up your registry
    16   - can't figure out something
    17   - are not sure what's going on or what your problem is
    18  
    19  Then please do not open an issue here yet - you should first try one of the following support forums:
    20  
    21   - irc: #docker-distribution on freenode
    22   - mailing-list: <distribution@dockerproject.org> or https://groups.google.com/a/dockerproject.org/forum/#!forum/distribution
    23  
    24  ## Reporting an issue properly
    25  
    26  By following these simple rules you will get better and faster feedback on your issue.
    27  
    28   - search the bugtracker for an already reported issue
    29  
    30  ### If you found an issue that describes your problem:
    31  
    32   - please read other user comments first, and confirm this is the same issue: a given error condition might be indicative of different problems - you may also find a workaround in the comments
    33   - please refrain from adding "same thing here" or "+1" comments
    34   - you don't need to comment on an issue to get notified of updates: just hit the "subscribe" button
    35   - comment if you have some new, technical and relevant information to add to the case
    36   - __DO NOT__ comment on closed issues or merged PRs. If you think you have a related problem, open up a new issue and reference the PR or issue.
    37  
    38  ### If you have not found an existing issue that describes your problem:
    39  
    40   1. create a new issue, with a succinct title that describes your issue:
    41     - bad title: "It doesn't work with my docker"
    42     - good title: "Private registry push fail: 400 error with E_INVALID_DIGEST"
    43   2. copy the output of:
    44     - `docker version`
    45     - `docker info`
    46     - `docker exec <registry-container> registry -version`
    47   3. copy the command line you used to launch your Registry
    48   4. restart your docker daemon in debug mode (add `-D` to the daemon launch arguments)
    49   5. reproduce your problem and get your docker daemon logs showing the error
    50   6. if relevant, copy your registry logs that show the error
    51   7. provide any relevant detail about your specific Registry configuration (e.g., storage backend used)
    52   8. indicate if you are using an enterprise proxy, Nginx, or anything else between you and your Registry
    53  
    54  ## Contributing a patch for a known bug, or a small correction
    55  
    56  You should follow the basic GitHub workflow:
    57  
    58   1. fork
    59   2. commit a change
    60   3. make sure the tests pass
    61   4. PR
    62  
    63  Additionally, you must [sign your commits](https://github.com/docker/docker/blob/master/CONTRIBUTING.md#sign-your-work). It's very simple:
    64  
    65   - configure your name with git: `git config user.name "Real Name" && git config user.email mail@example.com`
    66   - sign your commits using `-s`: `git commit -s -m "My commit"`
    67  
    68  Some simple rules to ensure quick merge:
    69  
    70   - clearly point to the issue(s) you want to fix in your PR comment (e.g., `closes #12345`)
    71   - prefer multiple (smaller) PRs addressing individual issues over a big one trying to address multiple issues at once
    72   - if you need to amend your PR following comments, please squash instead of adding more commits
    73  
    74  ## Contributing new features
    75  
    76  You are heavily encouraged to first discuss what you want to do. You can do so on the irc channel, or by opening an issue that clearly describes the use case you want to fulfill, or the problem you are trying to solve.
    77  
    78  If this is a major new feature, you should then submit a proposal that describes your technical solution and reasoning.
    79  If you did discuss it first, this will likely be greenlighted very fast. It's advisable to address all feedback on this proposal before starting actual work. 
    80  
    81  Then you should submit your implementation, clearly linking to the issue (and possible proposal).
    82  
    83  Your PR will be reviewed by the community, then ultimately by the project maintainers, before being merged.
    84  
    85  It's mandatory to:
    86  
    87   - interact respectfully with other community members and maintainers - more generally, you are expected to abide by the [Docker community rules](https://github.com/docker/docker/blob/master/CONTRIBUTING.md#docker-community-guidelines)
    88   - address maintainers' comments and modify your submission accordingly
    89   - write tests for any new code
    90  
    91  Complying to these simple rules will greatly accelerate the review process, and will ensure you have a pleasant experience in contributing code to the Registry.
    92  
    93  Have a look at a great, succesful contribution: the [Ceph driver PR](https://github.com/docker/distribution/pull/443)
    94  
    95  ## Coding Style
    96  
    97  Unless explicitly stated, we follow all coding guidelines from the Go
    98  community. While some of these standards may seem arbitrary, they somehow seem
    99  to result in a solid, consistent codebase.
   100  
   101  It is possible that the code base does not currently comply with these
   102  guidelines. We are not looking for a massive PR that fixes this, since that
   103  goes against the spirit of the guidelines. All new contributions should make a
   104  best effort to clean up and make the code base better than they left it.
   105  Obviously, apply your best judgement. Remember, the goal here is to make the
   106  code base easier for humans to navigate and understand. Always keep that in
   107  mind when nudging others to comply.
   108  
   109  The rules:
   110  
   111  1. All code should be formatted with `gofmt -s`.
   112  2. All code should pass the default levels of
   113     [`golint`](https://github.com/golang/lint).
   114  3. All code should follow the guidelines covered in [Effective
   115     Go](http://golang.org/doc/effective_go.html) and [Go Code Review
   116     Comments](https://github.com/golang/go/wiki/CodeReviewComments).
   117  4. Comment the code. Tell us the why, the history and the context.
   118  5. Document _all_ declarations and methods, even private ones. Declare
   119     expectations, caveats and anything else that may be important. If a type
   120     gets exported, having the comments already there will ensure it's ready.
   121  6. Variable name length should be proportional to its context and no longer.
   122     `noCommaALongVariableNameLikeThisIsNotMoreClearWhenASimpleCommentWouldDo`.
   123     In practice, short methods will have short variable names and globals will
   124     have longer names.
   125  7. No underscores in package names. If you need a compound name, step back,
   126     and re-examine why you need a compound name. If you still think you need a
   127     compound name, lose the underscore.
   128  8. No utils or helpers packages. If a function is not general enough to
   129     warrant its own package, it has not been written generally enough to be a
   130     part of a util package. Just leave it unexported and well-documented.
   131  9. All tests should run with `go test` and outside tooling should not be
   132     required. No, we don't need another unit testing framework. Assertion
   133     packages are acceptable if they provide _real_ incremental value.
   134  10. Even though we call these "rules" above, they are actually just
   135      guidelines. Since you've read all the rules, you now know that.
   136  
   137  If you are having trouble getting into the mood of idiomatic Go, we recommend
   138  reading through [Effective Go](http://golang.org/doc/effective_go.html). The
   139  [Go Blog](http://blog.golang.org/) is also a great resource. Drinking the
   140  kool-aid is a lot easier than going thirsty.