Update readme and contributing docs
Update project details to align more closely with community updates in OCI and containerd. Signed-off-by: Derek McGowan <derek@mcgstyle.net>
This commit is contained in:
Derek McGowan
parent
1fb7fffdb2
commit
f5e84a4939
3 changed files with 42 additions and 152 deletions
100
CONTRIBUTING.md
100
CONTRIBUTING.md
|
|
@ -16,10 +16,8 @@ Then please do not report your issue here - you should instead report it to [htt
|
||||||
- can't figure out something
|
- can't figure out something
|
||||||
- are not sure what's going on or what your problem is
|
- are not sure what's going on or what your problem is
|
||||||
|
|
||||||
Then please do not open an issue here yet - you should first try one of the following support forums:
|
Please ask first in the #distribution channel on Docker community slack.
|
||||||
|
[Click here for an invite to Docker community slack](https://dockr.ly/slack)
|
||||||
- irc: #docker-distribution on freenode
|
|
||||||
- mailing-list: <distribution@dockerproject.org> or https://groups.google.com/a/dockerproject.org/forum/#!forum/distribution
|
|
||||||
|
|
||||||
### Reporting security issues
|
### Reporting security issues
|
||||||
|
|
||||||
|
|
@ -59,90 +57,18 @@ By following these simple rules you will get better and faster feedback on your
|
||||||
7. provide any relevant detail about your specific Registry configuration (e.g., storage backend used)
|
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
|
8. indicate if you are using an enterprise proxy, Nginx, or anything else between you and your Registry
|
||||||
|
|
||||||
## Contributing a patch for a known bug, or a small correction
|
## Contributing Code
|
||||||
|
|
||||||
|
Contributions should be made via pull requests. Pull requests will be reviewed
|
||||||
|
by one or more maintainers or reviewers and merged when acceptable.
|
||||||
|
|
||||||
You should follow the basic GitHub workflow:
|
You should follow the basic GitHub workflow:
|
||||||
|
|
||||||
1. fork
|
1. Use your own [fork](https://help.github.com/en/articles/about-forks)
|
||||||
2. commit a change
|
2. Create your [change](https://github.com/containerd/project/blob/master/CONTRIBUTING.md#successful-changes)
|
||||||
3. make sure the tests pass
|
3. Test your code
|
||||||
4. PR
|
4. [Commit](https://github.com/containerd/project/blob/master/CONTRIBUTING.md#commit-messages) your work, always [sign your commits](https://github.com/containerd/project/blob/master/CONTRIBUTING.md#commit-messages)
|
||||||
|
5. Push your change to your fork and create a [Pull Request](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork)
|
||||||
|
|
||||||
Additionally, you must [sign your commits](https://github.com/docker/docker/blob/master/CONTRIBUTING.md#sign-your-work). It's very simple:
|
Refer to [containerd's contribution guide](https://github.com/containerd/project/blob/master/CONTRIBUTING.md#successful-changes)
|
||||||
|
for tips on creating a successful contribution.
|
||||||
- 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"`
|
|
||||||
|
|
||||||
Some simple rules to ensure quick merge:
|
|
||||||
|
|
||||||
- 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
|
|
||||||
|
|
||||||
## 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.
|
|
||||||
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.
|
|
||||||
|
|
||||||
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:
|
|
||||||
|
|
||||||
- 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
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
Have a look at a great, successful contribution: the [Swift driver PR](https://github.com/docker/distribution/pull/493)
|
|
||||||
|
|
||||||
## 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.
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
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).
|
|
||||||
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).
|
|
||||||
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.
|
|
||||||
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
|
|
||||||
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
|
|
||||||
warrant its own package, it has not been written generally enough to be a
|
|
||||||
part of a util package. Just leave it unexported and well-documented.
|
|
||||||
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.
|
|
||||||
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
|
|
||||||
reading through [Effective Go](http://golang.org/doc/effective_go.html). The
|
|
||||||
[Go Blog](http://blog.golang.org/) is also a great resource. Drinking the
|
|
||||||
kool-aid is a lot easier than going thirsty.
|
|
||||||
|
|
|
||||||
91
README.md
91
README.md
|
|
@ -2,31 +2,32 @@
|
||||||
|
|
||||||
The Docker toolset to pack, ship, store, and deliver content.
|
The Docker toolset to pack, ship, store, and deliver content.
|
||||||
|
|
||||||
This repository's main product is the Docker Registry 2.0 implementation
|
This repository's main product is the Open Source Docker Registry implementation
|
||||||
for storing and distributing Docker images. It supersedes the
|
for storing and distributing Docker and OCI images using the
|
||||||
[docker/docker-registry](https://github.com/docker/docker-registry)
|
[OCI Distribution Specification](https://github.com/opencontainers/distribution-spec).
|
||||||
project with a new API design, focused around security and performance.
|
The goal of this project is to provide a simple, secure, and scalable base
|
||||||
|
for building a registry solution or running a simple private registry.
|
||||||
|
|
||||||
<img src="https://www.docker.com/sites/default/files/oyster-registry-3.png" width=200px/>
|
<img src="https://www.docker.com/sites/default/files/oyster-registry-3.png" width=200px/>
|
||||||
|
|
||||||
[](https://circleci.com/gh/docker/distribution/tree/master)
|
[](https://travis-ci.org/docker/distribution)
|
||||||
[](https://godoc.org/github.com/docker/distribution)
|
[](https://godoc.org/github.com/docker/distribution)
|
||||||
|
|
||||||
This repository contains the following components:
|
This repository contains the following components:
|
||||||
|
|
||||||
|**Component** |Description |
|
|**Component** |Description |
|
||||||
|--------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
|--------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||||
| **registry** | An implementation of the [Docker Registry HTTP API V2](docs/spec/api.md) for use with docker 1.6+. |
|
| **registry** | An implementation of the [OCI Distribution Specification](https://github.com/opencontainers/distribution-spec). |
|
||||||
| **libraries** | A rich set of libraries for interacting with distribution components. Please see [godoc](https://godoc.org/github.com/docker/distribution) for details. **Note**: These libraries are **unstable**. |
|
| **libraries** | A rich set of libraries for interacting with distribution components. Please see [godoc](https://godoc.org/github.com/docker/distribution) for details. **Note**: The interfaces for these libraries are **unstable**. |
|
||||||
| **specifications** | _Distribution_ related specifications are available in [docs/spec](docs/spec) |
|
|
||||||
| **documentation** | Docker's full documentation set is available at [docs.docker.com](https://docs.docker.com). This repository [contains the subset](docs/) related just to the registry. |
|
| **documentation** | Docker's full documentation set is available at [docs.docker.com](https://docs.docker.com). This repository [contains the subset](docs/) related just to the registry. |
|
||||||
|
|
||||||
### How does this integrate with Docker engine?
|
### How does this integrate with Docker, containerd, and other OCI client?
|
||||||
|
|
||||||
This project should provide an implementation to a V2 API for use in the [Docker
|
Clients implement against the OCI specification and communicate with the
|
||||||
core project](https://github.com/docker/docker). The API should be embeddable
|
registry using HTTP. This project contains an client implementation which
|
||||||
and simplify the process of securely pulling and pushing content from `docker`
|
is currently in use by Docker, however, it is deprecated for the
|
||||||
daemons.
|
[implementation in containerd](https://github.com/containerd/containerd/tree/master/remotes/docker)
|
||||||
|
and will not support new features.
|
||||||
|
|
||||||
### What are the long term goals of the Distribution project?
|
### What are the long term goals of the Distribution project?
|
||||||
|
|
||||||
|
|
@ -43,18 +44,6 @@ system that allow users to:
|
||||||
* Implement their own home made solution through good specs, and solid
|
* Implement their own home made solution through good specs, and solid
|
||||||
extensions mechanism.
|
extensions mechanism.
|
||||||
|
|
||||||
## More about Registry 2.0
|
|
||||||
|
|
||||||
The new registry implementation provides the following benefits:
|
|
||||||
|
|
||||||
- faster push and pull
|
|
||||||
- new, more efficient implementation
|
|
||||||
- simplified deployment
|
|
||||||
- pluggable storage backend
|
|
||||||
- webhook notifications
|
|
||||||
|
|
||||||
For information on upcoming functionality, please see [ROADMAP.md](ROADMAP.md).
|
|
||||||
|
|
||||||
### Who needs to deploy a registry?
|
### Who needs to deploy a registry?
|
||||||
|
|
||||||
By default, Docker users pull images from Docker's public registry instance.
|
By default, Docker users pull images from Docker's public registry instance.
|
||||||
|
|
@ -78,53 +67,25 @@ For those who have previously deployed their own registry based on the Registry
|
||||||
data migration is required. A tool to assist with migration efforts has been
|
data migration is required. A tool to assist with migration efforts has been
|
||||||
created. For more information see [docker/migrator](https://github.com/docker/migrator).
|
created. For more information see [docker/migrator](https://github.com/docker/migrator).
|
||||||
|
|
||||||
## Contribute
|
## Contribution
|
||||||
|
|
||||||
Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to contribute
|
Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to contribute
|
||||||
issues, fixes, and patches to this project. If you are contributing code, see
|
issues, fixes, and patches to this project. If you are contributing code, see
|
||||||
the instructions for [building a development environment](BUILDING.md).
|
the instructions for [building a development environment](BUILDING.md).
|
||||||
|
|
||||||
## Support
|
## Communication
|
||||||
|
|
||||||
If any issues are encountered while using the _Distribution_ project, several
|
For async communication and long running discussions please use issues and pull requests on the github repo.
|
||||||
avenues are available for support:
|
This will be the best place to discuss design and implementation.
|
||||||
|
|
||||||
<table>
|
For sync communication we have a community slack with a #distribution channel that everyone is welcome to join and chat about development.
|
||||||
<tr>
|
|
||||||
<th align="left">
|
|
||||||
IRC
|
|
||||||
</th>
|
|
||||||
<td>
|
|
||||||
#docker-distribution on FreeNode
|
|
||||||
</td>
|
|
||||||
</tr>
|
|
||||||
<tr>
|
|
||||||
<th align="left">
|
|
||||||
Issue Tracker
|
|
||||||
</th>
|
|
||||||
<td>
|
|
||||||
github.com/docker/distribution/issues
|
|
||||||
</td>
|
|
||||||
</tr>
|
|
||||||
<tr>
|
|
||||||
<th align="left">
|
|
||||||
Google Groups
|
|
||||||
</th>
|
|
||||||
<td>
|
|
||||||
https://groups.google.com/a/dockerproject.org/forum/#!forum/distribution
|
|
||||||
</td>
|
|
||||||
</tr>
|
|
||||||
<tr>
|
|
||||||
<th align="left">
|
|
||||||
Mailing List
|
|
||||||
</th>
|
|
||||||
<td>
|
|
||||||
docker@dockerproject.org
|
|
||||||
</td>
|
|
||||||
</tr>
|
|
||||||
</table>
|
|
||||||
|
|
||||||
|
**Slack:** Catch us in the #distribution channels on dockercommunity.slack.com.
|
||||||
|
[Click here for an invite to Docker community slack.](https://dockr.ly/slack)
|
||||||
|
|
||||||
## License
|
## Licenses
|
||||||
|
|
||||||
This project is distributed under [Apache License, Version 2.0](LICENSE).
|
The distribution codebase is released under the [Apache 2.0 license](LICENSE).
|
||||||
|
The README.md file, and files in the "docs" folder are licensed under the
|
||||||
|
Creative Commons Attribution 4.0 International License. You may obtain a
|
||||||
|
copy of the license, titled CC-BY-4.0, at http://creativecommons.org/licenses/by/4.0/.
|
||||||
|
|
|
||||||
3
code-of-conduct.md
Normal file
3
code-of-conduct.md
Normal file
|
|
@ -0,0 +1,3 @@
|
||||||
|
## Docker Distribution Community Code of Conduct
|
||||||
|
|
||||||
|
Docker Distribution follows the [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md).
|
||||||
Loading…
Reference in a new issue