mini update 13: update definitions #177

pmengelbert · 2020-07-29T19:12:51Z

This PR is based on #175 .

See the relevant diff below:
https://github.com/bloodorangeio/distribution-spec/compare/mini-update-12...bloodorangeio:mini-update-13?expand=1

Signed-off-by: Peter Engelbert <[email protected]>

This is a new table of contents for the spec, designed to add simplicity and organization. Existing content will later be moved into one of these sections, or removed entirely if considered superfluous. Signed-off-by: jdolitsky <[email protected]>

Signed-off-by: jdolitsky <[email protected]>

Fill in the overview section, including new introduction referring to "content" (vs. just container images). Move historical context section underneath overview. Signed-off-by: jdolitsky <[email protected]>

Fill in the definitions section, introducing several terms and defintions which will serve as reference for the rest of the document. Also moved the "notational conventions" section into this section, removing any language that seemed unnecessary or related to compliance (which will be covered in the conformance section). Signed-off-by: jdolitsky <[email protected]>

Signed-off-by: jdolitsky <[email protected]>

Fill in conformance section, adding minimum requirements stating that all compliant registries must at least support Pull. Added a section regarding certification, linking to the opencontainers/oci-conformance repo. For the workflow sections, intentionally left blank, and will be added in a follow-up PR. Signed-off-by: jdolitsky <[email protected]>

Signed-off-by: Peter Engelbert <[email protected]>

…-spec into mini-update-6 Signed-off-by: Peter Engelbert <[email protected]>

…-spec into mini-update-6 Signed-off-by: jdolitsky <[email protected]>

Signed-off-by: Peter Engelbert <[email protected]>

spec.md

hallyn · 2020-08-05T16:49:03Z

spec.md

+
+`<name>` is the namespace of the repository, and `<digest>` being the blob's digest.
+
+A GET request to an existing blob URL MUST provide the expected blob, with a reponse code that MUST be `200 OK`.


Ignorant question - is there any question of permissions here?

hallyn · 2020-08-05T16:50:01Z

spec.md

+
+`<name>` refers to the namespace of the repository. `<reference>` MUST be either (a) the digest of the manifest or (b) a tag name.
+
+The `<reference>` MUST NOT be in any other format.


It seems like the two sentences referring to should be in the same paragraph?

hallyn · 2020-08-05T16:50:29Z

spec.md

+
+The `<reference>` MUST NOT be in any other format.
+
+A GET request to an existing manifest URL MUST provide the expected manifest, with a response code that MUST be `200 OK`.


Again, any question of permissions or authentication here?

hallyn · 2020-08-05T16:52:28Z

spec.md

 - **Config**: a section in the manifest (and associated blob) which contains artifact metadata
 - **Artifact**: one conceptual piece of content stored as blobs with an accompanying manifest containing a config
- **Digest**: a unique identifier created from a cryptographic hash of a blob's content
+- **Digest**: a unique identifier created from a cryptographic hash of a blob's content. Digests are defined under the [OCI Image Spec](https://github.com/opencontainers/image-spec/blob/b6e51fa50549ee0bd5188494912a7f4c382cb0d4/descriptor.md#digests)


Is that a commit id in the link? That will quickly make itself obsolete won't it?

hallyn · 2020-08-05T16:53:43Z

spec.md

@@ -803,7 +801,7 @@ Range: bytes=0-0
 To get the status of an upload, issue a GET request to the upload URL:

 ```HTTP
-GET /v2/<name>/blobs/uploads/<session_id>
+GET /v2/<name>/globs/uploads/<session_id>


Is this a real thing? globs?

hallyn · 2020-08-05T16:54:57Z

spec.md

+    {
+        "errors": [
+            {
+                "code": "<error identifier>",


Should this say "(see below)" ?

hallyn · 2020-08-05T16:59:56Z

spec.md

+
+`<name>` is the namespace of the repository, and `<tag>` is the name of the tag to be deleted. Upon success, the registry
+MUST respond with a `202 Accepted` code. If tag deletion is disabled, the registry MUST respond with a `400 Bad Request`
+code.


Does the spec want to take a stand on auto-deletion of a manifest when the last tag to it is removed? In particular, should that be disallowed? Else clients may have to try and guess what a repo will do...

hallyn · 2020-08-05T17:01:15Z

spec.md

+`/v2/<name>/tags/list`
+
+`<name>` is the namespace of the repository. Assuming a repository is found, Content Discovery endpoints MUST return a
+`200 OK` response code. The list of tags MAY be empty, if there are no tags on the repository. If the list is not empty,


nit - maybe drop the comma after 'empty'?

hallyn · 2020-08-05T17:11:13Z

spec.md

+next), the list returned will start at the beginning of the list and include `<int>` results. As above, the tags MUST be
+in lexical order.
+
+The `last` query parameter provides further means for limiting the number of tags. It is used exclusively in combination with the


last seems weird. I know startafter is longer, but it's more correct, no?

hallyn · 2020-08-05T17:12:56Z

(weird, gh was saying there were only 2 comments when i hit approve, so i thought maybe it was for just that commit's review. Would have marked it 'changes requested' otherwise)

jdolitsky · 2020-08-11T20:00:15Z

Closing this in favor of #178

@hallyn if you could port your comments there - thank you!

pmengelbert and others added 24 commits June 16, 2020 11:48

Describe the pull workflow

2848dfe

Signed-off-by: Peter Engelbert <[email protected]>

mini update 2: new table of contents

5404eba

This is a new table of contents for the spec, designed to add simplicity and organization. Existing content will later be moved into one of these sections, or removed entirely if considered superfluous. Signed-off-by: jdolitsky <[email protected]>

remove top-level defintions section

5f59ff7

Signed-off-by: jdolitsky <[email protected]>

mini update 3: fill in overview section

2ded6d5

Fill in the overview section, including new introduction referring to "content" (vs. just container images). Move historical context section underneath overview. Signed-off-by: jdolitsky <[email protected]>

update digest and content definitions

922acfd

Signed-off-by: jdolitsky <[email protected]>

Describe the pull workflow

a367759

Signed-off-by: Peter Engelbert <[email protected]>

Merge branch 'mini-update-5' of github.com:bloodorangeio/distribution…

515e36c

…-spec into mini-update-6 Signed-off-by: Peter Engelbert <[email protected]>

Merge branch 'mini-update-6' of github.com:bloodorangeio/distribution…

07e23a1

…-spec into mini-update-6 Signed-off-by: Peter Engelbert <[email protected]>

Merge branch 'mini-update-5' of github.com:bloodorangeio/distribution…

1072ba0

…-spec into mini-update-6 Signed-off-by: jdolitsky <[email protected]>

Adjust grammar

801afc1

Signed-off-by: Peter Engelbert <[email protected]>

Describe push workflow

4933b31

Signed-off-by: Peter Engelbert <[email protected]>

Fix typos and English errors

d44db2d

Signed-off-by: Peter Engelbert <[email protected]>

Add content discovery section to spec

b5adeb6

Signed-off-by: Peter Engelbert <[email protected]>

Make small language improvements

4797796

Signed-off-by: Peter Engelbert <[email protected]>

Describe content management workflow

1e90b55

Signed-off-by: Peter Engelbert <[email protected]>

Make small language fixes

c03bb79

Signed-off-by: Peter Engelbert <[email protected]>

Add endpoint table to spec

a2b8c84

Signed-off-by: Peter Engelbert <[email protected]>

Add summary and place method into its own column

08f7078

Signed-off-by: Peter Engelbert <[email protected]>

Add 'error codes' section

ecf4822

Signed-off-by: Peter Engelbert <[email protected]>

Add references and links to endpoint IDs

35df229

Signed-off-by: Peter Engelbert <[email protected]>

Update definitions

a4ce092

Signed-off-by: Peter Engelbert <[email protected]>

jdolitsky mentioned this pull request Jul 29, 2020

[tracker] mini spec updates for 1.0 #163

Closed

14 tasks

hallyn approved these changes Aug 5, 2020

View reviewed changes

jdolitsky changed the title ~~mini update 13: update definitions~~ Distribution spec reorganization Aug 11, 2020

jdolitsky changed the title ~~Distribution spec reorganization~~ mini update 13: update definitions Aug 11, 2020

jdolitsky closed this Aug 11, 2020

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

mini update 13: update definitions #177

mini update 13: update definitions #177

pmengelbert commented Jul 29, 2020

hallyn Aug 5, 2020

hallyn Aug 5, 2020

hallyn Aug 5, 2020

hallyn Aug 5, 2020

hallyn Aug 5, 2020

hallyn Aug 5, 2020

hallyn Aug 5, 2020

hallyn Aug 5, 2020

hallyn Aug 5, 2020

hallyn commented Aug 5, 2020

jdolitsky commented Aug 11, 2020


		`<name>` is the namespace of the repository, and `<digest>` being the blob's digest.

		A GET request to an existing blob URL MUST provide the expected blob, with a reponse code that MUST be `200 OK`.


		`<name>` refers to the namespace of the repository. `<reference>` MUST be either (a) the digest of the manifest or (b) a tag name.

		The `<reference>` MUST NOT be in any other format.


		The `<reference>` MUST NOT be in any other format.

		A GET request to an existing manifest URL MUST provide the expected manifest, with a response code that MUST be `200 OK`.

mini update 13: update definitions #177

mini update 13: update definitions #177

Conversation

pmengelbert commented Jul 29, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hallyn commented Aug 5, 2020

jdolitsky commented Aug 11, 2020