Begin adjustments on the imported specs #12

vbatts · 2016-04-07T18:30:29Z

As #6 was tangled up with WIP modifications, this splits out into a new PR all the modifications.

philips · 2016-04-08T15:43:35Z

@vbatts can you rebase on top of master?

vbatts · 2016-04-08T16:17:07Z

done

On Fri, Apr 8, 2016 at 11:43 AM, Brandon Philips [email protected]
wrote:

@vbatts https://github.com/vbatts can you rebase on top of master?

—
You are receiving this because you were mentioned.
Reply to this email directly or view it on GitHub
#12 (comment)

stevvooe · 2016-04-08T18:21:05Z

manifest.md

-  This field specifies the image manifest schema version as an integer. This
-  schema uses the version `2`.
+
+  This REQUIRED property specifies the image manifest schema version.


This reset will make the format incompatible with Docker's manifest format. I'd rather we maintain this at 2 and deprecate the field.

k. changed.

On Fri, Apr 8, 2016 at 2:21 PM, Stephen Day [email protected]
wrote:

In manifest.md
#12 (comment)
:

Manifest List Field Descriptions

- schemaVersion int

This field specifies the image manifest schema version as an integer. This

schema uses the version 2.

This REQUIRED property specifies the image manifest schema version.

This reset will make the format incompatible with Docker's manifest
format. I'd rather we maintain this at 2 and deprecate the field.

—
You are receiving this because you were mentioned.
Reply to this email directly or view it on GitHub
https://github.com/opencontainers/image-spec/pull/12/files/c146488d55d702f2c7103da26ac5a20dfc5f34c1#r59068108

We will need a note as to why it is at 2. Leaving it at 2 is fine by me.

perhaps as a part of the compatibility matrix/table

On Fri, Apr 8, 2016 at 2:43 PM, Brandon Philips [email protected]
wrote:

In manifest.md
#12 (comment)
:

Manifest List Field Descriptions

- schemaVersion int

This field specifies the image manifest schema version as an integer. This

schema uses the version 2.

This REQUIRED property specifies the image manifest schema version.

We will need a note as to why it is at 2. Leaving it at 2 is fine by me.

—
You are receiving this because you were mentioned.
Reply to this email directly or view it on GitHub
https://github.com/opencontainers/image-spec/pull/12/files/c146488d55d702f2c7103da26ac5a20dfc5f34c1#r59079019

stevvooe · 2016-04-11T19:25:00Z

manifest.md

-respective blobs. The registry will create these configurations and their IDs
-using the same scheme as Docker 1.10 when it creates a legacy manifest to push
-to a registry which doesn't support the new format.
+The registry will continue to accept uploads of manifests in both the old and new formats.


After some thought, we may need to word this in a way that doesn't assume the existence of a registry. We can use the Accept/Allow headers to frame a fallback story, but we should talking about expressing compatibility in transport agnostic manner.

The behavior here is going to be very important to ensure we have a specification that is beneficial to the community of users. Part of the problem here is that content-addressability (content security, really), needs to be balanced against backwards compatibility and usability.

@stevvooe I think we can just refer to the non-existent mime-type table: #14

Then add concrete language around handling those mime-types in the optional distribution layer: #15

We really need to add distribution-agnostic fallback. A mimetype table and optional distribution layer aren't really sufficient for describing fallback that will work across transports. Otherwise, we risk losing compatibility across transports.

Perhaps, this section should describe the structure of the table.

@stevvooe It is a bit hard to design with a strawman of "distribution-agnostic". Do you have a concrete example?

I'm not sure if "distribution-agnostic" or "transport-agnostic" is a "strawman". It simply means to describe mediatype fallback outside of the context of http, which may refer to Accept headers. A concrete example would be if application/vnd.oci.image.manifest.v1+json is encountered, and only application/vnd.docker.image.manifest.v2+json is supported, what should be done?

Another issue is expressing a fallback precedence. For example, one might declare they can handle application/vnd.oci.image.manifest.v1+json and application/vnd.docker.image.manifest.v2+json but only supports the latter. Both are provided. Should the client convert or fallback to the format they support natively?

Do you have an example transport in mind? I am confused what you are trying to ask for here. Perhaps we can move it to a separate issue?

Do you just want language like what is in the HTTP spec about quality factors?

Quality factors allow the user or user agent to indicate the relative degree of preference for that media-range, using the qvalue scale from 0 to 1 (section 3.9). The default value is q=1. The example Accept: audio/*; q=0.2, audio/basic SHOULD be interpreted as "I prefer audio/basic, but send me any audio type if it is the best available after an 80% mark-down in quality."

This section discusses fallback in the context of http. Let's remove the transport-specific items and describe what was here generically.

I'm really confused as to why this is an unreasonable request for this stage of the specification process. If you believe this is outside the scope of this PR, we can file a separate issue, but let's make sure it is followed up.

philips · 2016-04-12T19:16:41Z

overall LGTM.

duglin · 2016-04-13T09:09:37Z

manifest.md

-move the Docker engine towards content-addressable images, by supporting
-an image model where the image's configuration can be hashed to generate
-an ID for the image.
+The first goal is content-addressable images, by supporting an image model where the image's configuration can be hashed to generate an ID for the image and its components.


Let's add some kind of intro sentence to this section - even something as simple as:

There are three main goals of the Image Manifest.

s/generate an ID/generate a unique ID/

stevvooe · 2016-04-13T22:08:42Z

manifest.md

-for one or more platforms. Its use is optional, and relatively few images will
-use one of these manifests. A client will distinguish a manifest list from an
-image manifest based on the Content-Type returned in the HTTP response.
+The manifest list is the "fat manifest" which points to specific image manifests for one or more platforms.


We can deprecate the term "fat manifest". I'm not sure if it helps the understanding here.

philips · 2016-04-13T23:13:09Z

@vbatts Can we please just merge this, @stevvooe has some additional comments but we can fix those elsewhere. I have some other fixes I want to make but this is going to conflict with this huge change.

jonboulle · 2016-04-14T14:00:03Z

Needs a rebase before merging.

Signed-off-by: Vincent Batts <[email protected]>

vbatts · 2016-04-14T14:32:16Z

rebased. merging now.

Signed-off-by: Brandon Mitchell <[email protected]>

vbatts mentioned this pull request Apr 7, 2016

Initial import of specs #6

Merged

vbatts force-pushed the begin_import_adjustments branch from bb25b9c to c146488 Compare April 8, 2016 16:12

stevvooe reviewed Apr 8, 2016
View reviewed changes

vbatts force-pushed the begin_import_adjustments branch from c146488 to 8046ab7 Compare April 8, 2016 18:48

stevvooe reviewed Apr 11, 2016
View reviewed changes

duglin reviewed Apr 13, 2016
View reviewed changes

vbatts force-pushed the begin_import_adjustments branch from 8046ab7 to 022d77d Compare April 13, 2016 14:58

stevvooe reviewed Apr 13, 2016
View reviewed changes

philips added component/serialization spec component/manifest spec kind/cleanup priority/P0 labels Apr 14, 2016

philips added this to the v0.1.0 milestone Apr 14, 2016

*: update for oc/image-spec

f7ffdbd

Signed-off-by: Vincent Batts <[email protected]>

vbatts force-pushed the begin_import_adjustments branch from 022d77d to f7ffdbd Compare April 14, 2016 14:30

vbatts merged commit 2273702 into opencontainers:master Apr 14, 2016

vbatts deleted the begin_import_adjustments branch April 14, 2016 14:32

sajayantony pushed a commit to sajayantony/image-spec that referenced this pull request Aug 10, 2022

Adding referrers annotation (opencontainers#12)

1939123

Signed-off-by: Brandon Mitchell <[email protected]>

Begin adjustments on the imported specs #12

Begin adjustments on the imported specs #12

Uh oh!

Conversation

vbatts commented Apr 7, 2016

Uh oh!

philips commented Apr 8, 2016

Uh oh!

vbatts commented Apr 8, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Manifest List Field Descriptions

- schemaVersion int

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Manifest List Field Descriptions

- schemaVersion int

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!

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!

Choose a reason for hiding this comment

Uh oh!

philips commented Apr 12, 2016

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!

Choose a reason for hiding this comment

Uh oh!

philips commented Apr 13, 2016

Uh oh!

jonboulle commented Apr 14, 2016

Uh oh!

vbatts commented Apr 14, 2016

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

- `schemaVersion` int

- `schemaVersion` int