CONTRIBUTING.md 7.47 KB
Newer Older
Olivier Gambier's avatar
Olivier Gambier committed
1 2
# Contributing to the registry

Per Lundberg's avatar
Per Lundberg committed
3
## Before reporting an issue...
Olivier Gambier's avatar
Olivier Gambier committed
4

Olivier Gambier's avatar
Olivier Gambier committed
5
### If your problem is with...
Olivier Gambier's avatar
Olivier Gambier committed
6

7 8 9
 - automated builds
 - your account on the [Docker Hub](https://hub.docker.com/)
 - any other [Docker Hub](https://hub.docker.com/) issue
Olivier Gambier's avatar
Olivier Gambier committed
10

11
Then please do not report your issue here - you should instead report it to [https://support.docker.com](https://support.docker.com)
Olivier Gambier's avatar
Olivier Gambier committed
12

Olivier Gambier's avatar
Olivier Gambier committed
13
### If you...
Olivier Gambier's avatar
Olivier Gambier committed
14

15 16 17
 - need help setting up your registry
 - can't figure out something
 - are not sure what's going on or what your problem is
Olivier Gambier's avatar
Olivier Gambier committed
18

Olivier Gambier's avatar
Olivier Gambier committed
19
Then please do not open an issue here yet - you should first try one of the following support forums:
Olivier Gambier's avatar
Olivier Gambier committed
20

21 22
 - irc: #docker-distribution on freenode
 - mailing-list: <distribution@dockerproject.org> or https://groups.google.com/a/dockerproject.org/forum/#!forum/distribution
Olivier Gambier's avatar
Olivier Gambier committed
23

24 25 26 27 28 29 30 31
### Reporting security issues

The Docker maintainers take security seriously. If you discover a security
issue, please bring it to their attention right away!

Please **DO NOT** file a public issue, instead send your report privately to
[security@docker.com](mailto:security@docker.com).

Olivier Gambier's avatar
Olivier Gambier committed
32
## Reporting an issue properly
Olivier Gambier's avatar
Olivier Gambier committed
33

Olivier Gambier's avatar
Olivier Gambier committed
34
By following these simple rules you will get better and faster feedback on your issue.
Olivier Gambier's avatar
Olivier Gambier committed
35

36
 - search the bugtracker for an already reported issue
Olivier Gambier's avatar
Olivier Gambier committed
37

Per Lundberg's avatar
Per Lundberg committed
38
### If you found an issue that describes your problem:
Olivier Gambier's avatar
Olivier Gambier committed
39

40 41 42 43
 - 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
 - please refrain from adding "same thing here" or "+1" comments
 - you don't need to comment on an issue to get notified of updates: just hit the "subscribe" button
 - comment if you have some new, technical and relevant information to add to the case
44
 - __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.
Olivier Gambier's avatar
Olivier Gambier committed
45

Olivier Gambier's avatar
Olivier Gambier committed
46
### If you have not found an existing issue that describes your problem:
Olivier Gambier's avatar
Olivier Gambier committed
47

48 49 50 51 52 53
 1. create a new issue, with a succinct title that describes your issue:
   - bad title: "It doesn't work with my docker"
   - good title: "Private registry push fail: 400 error with E_INVALID_DIGEST"
 2. copy the output of:
   - `docker version`
   - `docker info`
54
   - `docker exec <registry-container> registry --version`
55 56 57 58 59 60
 3. copy the command line you used to launch your Registry
 4. restart your docker daemon in debug mode (add `-D` to the daemon launch arguments)
 5. reproduce your problem and get your docker daemon logs showing the error
 6. if relevant, copy your registry logs that show the error
 7. provide any relevant detail about your specific Registry configuration (e.g., storage backend used)
 8. indicate if you are using an enterprise proxy, Nginx, or anything else between you and your Registry
Olivier Gambier's avatar
Olivier Gambier committed
61

Olivier Gambier's avatar
Olivier Gambier committed
62
## Contributing a patch for a known bug, or a small correction
Olivier Gambier's avatar
Olivier Gambier committed
63

Olivier Gambier's avatar
Olivier Gambier committed
64
You should follow the basic GitHub workflow:
Olivier Gambier's avatar
Olivier Gambier committed
65

66 67 68 69
 1. fork
 2. commit a change
 3. make sure the tests pass
 4. PR
Olivier Gambier's avatar
Olivier Gambier committed
70

Olivier Gambier's avatar
Olivier Gambier committed
71 72
Additionally, you must [sign your commits](https://github.com/docker/docker/blob/master/CONTRIBUTING.md#sign-your-work). It's very simple:

73 74
 - configure your name with git: `git config user.name "Real Name" && git config user.email mail@example.com`
 - sign your commits using `-s`: `git commit -s -m "My commit"`
Olivier Gambier's avatar
Olivier Gambier committed
75 76 77

Some simple rules to ensure quick merge:

78 79 80
 - clearly point to the issue(s) you want to fix in your PR comment (e.g., `closes #12345`)
 - prefer multiple (smaller) PRs addressing individual issues over a big one trying to address multiple issues at once
 - if you need to amend your PR following comments, please squash instead of adding more commits
Olivier Gambier's avatar
Olivier Gambier committed
81 82 83 84 85 86

## Contributing new features

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.

If this is a major new feature, you should then submit a proposal that describes your technical solution and reasoning.
87
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.
Olivier Gambier's avatar
Olivier Gambier committed
88 89 90 91 92 93 94

Then you should submit your implementation, clearly linking to the issue (and possible proposal).

Your PR will be reviewed by the community, then ultimately by the project maintainers, before being merged.

It's mandatory to:

95 96 97
 - 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)
 - address maintainers' comments and modify your submission accordingly
 - write tests for any new code
Olivier Gambier's avatar
Olivier Gambier committed
98 99 100

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.

101
Have a look at a great, successful contribution: the [Swift driver PR](https://github.com/docker/distribution/pull/493)
Stephen J Day's avatar
Stephen J Day committed
102 103 104 105 106 107 108

## Coding Style

Unless explicitly stated, we follow all coding guidelines from the Go
community. While some of these standards may seem arbitrary, they somehow seem
to result in a solid, consistent codebase.

109 110 111 112 113 114 115 116
It is possible that the code base does not currently comply with these
guidelines. We are not looking for a massive PR that fixes this, since that
goes against the spirit of the guidelines. All new contributions should make a
best effort to clean up and make the code base better than they left it.
Obviously, apply your best judgement. Remember, the goal here is to make the
code base easier for humans to navigate and understand. Always keep that in
mind when nudging others to comply.

Stephen J Day's avatar
Stephen J Day committed
117 118 119 120 121
The rules:

1. All code should be formatted with `gofmt -s`.
2. All code should pass the default levels of
   [`golint`](https://github.com/golang/lint).
122 123 124
3. All code should follow the guidelines covered in [Effective
   Go](http://golang.org/doc/effective_go.html) and [Go Code Review
   Comments](https://github.com/golang/go/wiki/CodeReviewComments).
Stephen J Day's avatar
Stephen J Day committed
125 126 127 128
4. Comment the code. Tell us the why, the history and the context.
5. Document _all_ declarations and methods, even private ones. Declare
   expectations, caveats and anything else that may be important. If a type
   gets exported, having the comments already there will ensure it's ready.
129 130 131
6. Variable name length should be proportional to its context and no longer.
   `noCommaALongVariableNameLikeThisIsNotMoreClearWhenASimpleCommentWouldDo`.
   In practice, short methods will have short variable names and globals will
Stephen J Day's avatar
Stephen J Day committed
132 133 134 135 136
   have longer names.
7. No underscores in package names. If you need a compound name, step back,
   and re-examine why you need a compound name. If you still think you need a
   compound name, lose the underscore.
8. No utils or helpers packages. If a function is not general enough to
137
   warrant its own package, it has not been written generally enough to be a
Stephen J Day's avatar
Stephen J Day committed
138
   part of a util package. Just leave it unexported and well-documented.
139 140 141
9. All tests should run with `go test` and outside tooling should not be
   required. No, we don't need another unit testing framework. Assertion
   packages are acceptable if they provide _real_ incremental value.
Stephen J Day's avatar
Stephen J Day committed
142 143 144 145
10. Even though we call these "rules" above, they are actually just
    guidelines. Since you've read all the rules, you now know that.

If you are having trouble getting into the mood of idiomatic Go, we recommend
146
reading through [Effective Go](http://golang.org/doc/effective_go.html). The
Stephen J Day's avatar
Stephen J Day committed
147 148
[Go Blog](http://blog.golang.org/) is also a great resource. Drinking the
kool-aid is a lot easier than going thirsty.