distribution: Add in-scope and out-of-scope wording

Docker's use of Bearer requires information beyond what's covered in
RFC 6749 and 6750 [1].  Folks writing a client that will interact with
a Docker registry that uses that auth approach will need a "Docker
registry's 'Bearer' additions" spec to follow, but Derek believes the
situation is salvageable with external work [2].

Also pin the docker/registry links to a specific version so the links
will survive future docker/registry changes (including removing the
docs after the OCI picks them up).  As long as the TOB-selected
version isn't far behind (how far will the spec move during a week of
voting?), it should be easy for the new maintainets to catch up on any
subsequent drift.

The signing scope language is from Stephen in [3].  The discovery
scope language is from Derek [4].

[1]: xiekeyang/oci-discovery#64 (comment)
[2]: #37 (comment)
[3]: #35 (comment)
[4]: #34 (comment)

Signed-off-by: W. Trevor King <[email protected]>

Author: wking

proposals/distribution.md

@@ -1,19 +1,25 @@
 # Abstract
 
-The Docker registry protocol has become the defacto standard across the container registry world ([https://github.com/docker/distribution/blob/master/docs/spec/api.md](https://github.com/docker/distribution/blob/master/docs/spec/api.md)).
+The Docker registry protocol has become the defacto standard across the container registry world.
 
 In the OCI, having a solid, common distribution specification with conformance testing will ensure long lasting security and interoperability throughout the container ecosystem.
 
 ## Proposal
 
-TL;DR; Move [https://github.com/docker/distribution/tree/master/docs/spec](https://github.com/docker/distribution/tree/master/docs/spec) to [https://github.com/opencontainers/distribution-spec](https://github.com/opencontainers/distribution-spec)
+TL;DR; Move [`api.md`][api.md] to a new [distribution-spec project](https://github.com/opencontainers/distribution-spec).
 
 This proposal covers the distribution API spec, and while it does not cover the code for the docker-registry, that implementation is considered the reference implementation. There are other implementations of this protocol, not all are open-source though (Google gcr.io, Amazon ECR, CoreOS Quay, Gitlab registry, JFrog Artifactory registry, Huawei Dockyard, etc).
 
 In the past when the topic of having an OCI specification around the distribution of container images was discussed, it was deferred as "let’s get the image format defined, meanwhile the industry will settle on a distribution standard". Fast forward, OCI image format is out and adopted, and the Registry v2 is the defacto standard. There is and will be use-cases for alternate methods and the future will likely hold creative ways to push, fetch and share container images, but right now this promotion serves to acknowledge by the OCI the current industry standard of distributing container images.
 
 There is polish that is needed e.g. broken links to storage-driver docs, as well as making sections more generic regarding the OCI descriptors and media-types, but on the whole this is a lateral move.
 
+This project is scoped to cover the client ↔ registry interaction.  The following are out of scope:
+
+* Authentication and authorization.  Docker's current registry uses an [extension][token] of the [`Bearer`][rfc6750] [auth scheme][rfc7235-s2.1].  Work on specifying Docker's scheme will continue independently, and is orthogonal to the registry API.
+* Signing images.  All resources are content-addressable and can be signed in external systems.
+* Discovering images.  Discovery and registry protocols are completely separate and do not need to be added together.
+
 ## Initial Maintainers
 
 * Stephen Day <[email protected]> (@stevvooe)
@@ -64,3 +70,8 @@ The API spec is currently considered v2 and we will start the specification at v
 
 * Simplifies tag listing: docker/distribution#2169
 * Allows listing of manifests: docker/distribution#2199
+
+[api.md]: https://github.com/docker/distribution/blob/cb406d511b7b9163bff9b6439072e4892e5ae3b/docs/spec/api.md
+[token]: https://github.com/docker/distribution/blob/5cb406d511b7b9163bff9b6439072e4892e5ae3b/docs/spec/auth/token.md
+[rfc6750]: https://tools.ietf.org/html/rfc6750
+[rfc7235-s2.1]: https://tools.ietf.org/html/rfc7235#section-2.1