mini update 4: fill in definitions section by jdolitsky · Pull Request #161 · opencontainers/distribution-spec

jdolitsky · 2020-06-10T19:57:02Z

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).

This PR is built on top of #160, so the diff is misleading. Please see the following for a true diff: bloodorangeio/distribution-spec@mini-update-3...bloodorangeio:mini-update-4

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 <393494+jdolitsky@users.noreply.github.com>

rchincha · 2020-06-15T04:06:52Z

+- **Manifest**: a JSON document which defines an artifact
+- **Layer**: a single part of all the parts which comprise an artifact
+- **Config**: a special layer defined at the top of a manifest containing artifact metadata
+- **Blob**: a single binary content stored in a registry


Do we want to distinguish between "Layer" and "Blob" here?

@rchincha how would you best describe the difference?

the definitions appear to be circular, use words not defined.. For example from these definitions:

layer is a part in parts (part not defined) which comprises an artifact.. artifact is a piece of content (content is content that is addressable and can be downloaded choose one: manifest or blob) made up of a manifest and one or more layers (one or more undefined parts) blob is binary content (content is content -- either manifest or blob)

A blob is the binary form of metadata OR [most commonly] content that is stored by the registry.
An artifact is one conceptual piece of content stored as blobs with an accompanying manifest containing metadata.
A layer is one kind of blob used for container image artifacts

@jzelinskie vaguely remember you had a carefully compiled set of definitions. Let's look at that and see if we can just reuse that prose.

…-spec into HEAD Signed-off-by: jdolitsky <393494+jdolitsky@users.noreply.github.com>

Signed-off-by: jdolitsky <393494+jdolitsky@users.noreply.github.com>

mikebrow

see comments.. needs a rebase

mikebrow · 2020-06-27T16:00:05Z


-An implementation is not compliant if it fails to satisfy one or more of the MUST, MUST NOT, REQUIRED, SHALL, or SHALL NOT requirements for the protocols it implements.
-An implementation is compliant if it satisfies all the MUST, MUST NOT, REQUIRED, SHALL, and SHALL NOT requirements for the protocols it implements.
+### Document Language


pr needs rebase

mikebrow · 2020-06-27T16:00:10Z

+- **Manifest**: a JSON document which defines an artifact
+- **Layer**: a single part of all the parts which comprise an artifact
+- **Config**: a special layer defined at the top of a manifest containing artifact metadata
+- **Blob**: a single binary content stored in a registry


the definitions appear to be circular, use words not defined.. For example from these definitions:

layer is a part in parts (part not defined) which comprises an artifact.. artifact is a piece of content (content is content that is addressable and can be downloaded choose one: manifest or blob) made up of a manifest and one or more layers (one or more undefined parts) blob is binary content (content is content -- either manifest or blob)

mikebrow · 2020-06-27T16:26:13Z

+- **Pull**: the act of downloading content from a registry
+- **Artifact**: a single piece of content, made up of a manifest and one or more layers
+- **Manifest**: a JSON document which defines an artifact
+- **Layer**: a single part of all the parts which comprise an artifact


Layer explanation from image spec: https://github.com/opencontainers/image-spec/blob/master/config.md#oci-image-configuration

suggest: **Layer**: a set of filesystem changes; Layers are typically used by a layer-based or union filesystem to form the mountable root file system of a container. and maybe link to the oci spec

I think we should avoid using the term layers except in the context of images. I wish we would have just renamed layers to references. I don't think we need to inject that confusion here.

fair.. in the context of container images image layers are a set of..

I don't think the image spec is useful in this context. I'd rather define Layer as legacy terminology referring to blobs that are specifically for container images.

what is "this context?" ... at the moment it says "Several terms are used frequently in this document" seems pretty broad :-)

Why is OCI image not useful in this context? Let's say an OCI image is but one type of OCI artifact... still Most definitions include examples, for example, in the context of OCI container images, layers are a set of ... IMO the inclusion of examples does not make a definition as confusing as the lack of examples does. Esp. when highjacking a term that is common in the vernacular. As derek mentioned it may be useful to just avoid the term except in the context of images. You could have, for example, a different location for oci image terms.

mikebrow · 2020-06-27T16:41:49Z

+- **Config**: a special layer defined at the top of a manifest containing artifact metadata
+- **Blob**: a single binary content stored in a registry
+- **Digest**: a unique blob identifier, calculated from the blob's content
+- **Content**: a general term for content that can be downloaded from a registry (manifest or blob), and are addressable by a digest


content is being used as a noun to represent a great many things throughout the spec.. in each case the thing being represented is or should be specified by the context.

Suggest removing this definition since what is meant by it's use is really just the dictionary definition. Or just use the dictionary definition:
1a : something contained —usually used in plural
the layer's contents
the manifest's contents
the contents of the http response...

maybe a picture.. would help

mikebrow

suggest not focusing on HTTP in high level concepts and definitions

…nto mini-update-4 Signed-off-by: jdolitsky <393494+jdolitsky@users.noreply.github.com>

Signed-off-by: jdolitsky <393494+jdolitsky@users.noreply.github.com>

jdolitsky · 2020-07-10T20:18:45Z

@jzelinskie @mikebrow can I please have a second review? I've updated the definitions based on your comments.

The following terms have been removed:

Content
Layer

The following terms are unchanged:

Manifest
Digest

The following terms have been updated:

Registry: a service that handles the required APIs defined in this specification
Client: a tool that communicates with registries
Push: the act of uploading blobs and manifests to a registry
Pull: the act of downloading blobs and manifests from a registry
Blob: the binary form of content that is stored by a registry, addressable by a digest
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

Signed-off-by: jdolitsky <393494+jdolitsky@users.noreply.github.com>

jdolitsky · 2020-07-10T21:16:09Z

CC @dmcgowan

mikebrow

looks good just a small change request on digest definition

Signed-off-by: jdolitsky <393494+jdolitsky@users.noreply.github.com>

dmcgowan

LGTM

mikebrow

LGTM

This was referenced Jun 10, 2020

mini update 5: fill in conformance section (sans workflows) #162

Merged

[tracker] mini spec updates for 1.0 #163

Closed

rchincha reviewed Jun 15, 2020

View reviewed changes

Comment thread spec.md Outdated

adamwg reviewed Jun 16, 2020

View reviewed changes

Comment thread spec.md Outdated

jdolitsky added 2 commits June 26, 2020 17:20

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

cb92506

…-spec into HEAD Signed-off-by: jdolitsky <393494+jdolitsky@users.noreply.github.com>

update digest and content definitions

a1836fd

Signed-off-by: jdolitsky <393494+jdolitsky@users.noreply.github.com>

mikebrow reviewed Jun 27, 2020

View reviewed changes

Comment thread spec.md Outdated

Comment thread spec.md Outdated

vbatts reviewed Jun 29, 2020

View reviewed changes

Comment thread spec.md

jdolitsky added 5 commits June 29, 2020 16:10

Merge branch 'reorg' of github.com:opencontainers/distribution-spec i…

018c546

…nto mini-update-4 Signed-off-by: jdolitsky <393494+jdolitsky@users.noreply.github.com>

update definitions based on github review

2e03587

Signed-off-by: jdolitsky <393494+jdolitsky@users.noreply.github.com>

add addressable by a digest

2babed2

Signed-off-by: jdolitsky <393494+jdolitsky@users.noreply.github.com>

replace the with a

3b458ec

Signed-off-by: jdolitsky <393494+jdolitsky@users.noreply.github.com>

replace metadata with config

16ef458

Signed-off-by: jdolitsky <393494+jdolitsky@users.noreply.github.com>

add and associated blob

58e7334

Signed-off-by: jdolitsky <393494+jdolitsky@users.noreply.github.com>

mikebrow reviewed Jul 10, 2020

View reviewed changes

Comment thread spec.md Outdated

jdolitsky added 2 commits July 13, 2020 09:32

update digest definition

4b5e4e0

Signed-off-by: jdolitsky <393494+jdolitsky@users.noreply.github.com>

a cryptographic hash vs. the

43fd99d

Signed-off-by: jdolitsky <393494+jdolitsky@users.noreply.github.com>

dmcgowan approved these changes Jul 13, 2020

View reviewed changes

mikebrow approved these changes Jul 13, 2020

View reviewed changes

jdolitsky merged commit 585b882 into opencontainers:reorg Jul 14, 2020

Conversation

jdolitsky commented Jun 10, 2020

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mikebrow Jun 27, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

mikebrow left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mikebrow Jun 27, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mikebrow Jun 29, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mikebrow Jul 6, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mikebrow left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jdolitsky commented Jul 10, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jdolitsky commented Jul 10, 2020

Uh oh!

mikebrow left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

dmcgowan left a comment

Choose a reason for hiding this comment

Uh oh!

mikebrow left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

mikebrow Jun 27, 2020 •

edited

Loading

mikebrow Jun 27, 2020 •

edited

Loading

mikebrow Jun 29, 2020 •

edited

Loading

mikebrow Jul 6, 2020 •

edited

Loading

jdolitsky commented Jul 10, 2020 •

edited

Loading