spec.md: add some description about manifest list #455

coolljt0725 · 2016-11-10T07:55:09Z

Signed-off-by: Lei Jitang [email protected]

wking

I'm in favor of talking about manifest lists here. @jonboulle suggested avoiding a direct reference to to manifest lists down in the “Understanding the Specification” section. I'm not sure if he has the same concerns about these lines.

Stepping back, there is a lot of overlap between this “Overview” section and the following “Understanding the Specification” section. It seems like structure here could use a more thorough review.

wking · 2016-11-10T08:04:34Z

README.md

+At a high level the manifest list points to specific image manifests for one or more platform and the image manifest contains metadata about the contents and dependencies of the image including the content-addressable identity of one or more [filesystem layer changeset](layer.md) archives that will be unpacked to make up the final runnable filesystem.
 The image configuration includes information such as application arguments, environments, etc.
-The combination of the image manifest, image configuration, and one or more filesystem layers is called the "OCI Image".
+The combination of the image manifest list, image manifest, image configuration, and one or more filesystem layers is called the "OCI Image".


It's called an “OCI Image” with or without the manifest list. Maybe:

A manifest list (optional), manifest, configuration, and set of filesystem layers constitutes an "OCI Image".

I've also consolidated this with the earlier OCI Image sentence in #465. I'm happy to rebase that consoliation if this PR lands first.

wking · 2016-11-10T08:17:13Z

README.md

-This specification defines how to create an OCI Image, which will generally be done by a build system, and output an [image manifest](manifest.md), a set of [filesystem layers](layer.md), and an [image configuration](config.md).
-At a high level the image manifest contains metadata about the contents and dependencies of the image including the content-addressable identity of one or more [filesystem layer changeset](layer.md) archives that will be unpacked to make up the final runnable filesystem.
+This specification defines how to create an OCI Image, which will generally be done by a build system, and output an [image manifest](manifest.md) and may with a [manifest list](manifest-list.md), a set of [filesystem layers](layer.md), and an [image configuration](config.md).
+At a high level the manifest list points to specific image manifests for one or more platform and the image manifest contains metadata about the contents and dependencies of the image including the content-addressable identity of one or more [filesystem layer changeset](layer.md) archives that will be unpacked to make up the final runnable filesystem.


There's no need to wedge both manifest lists and manifests into the same sentence. Can we have an “At a high level, …” one-liner just for manifest lists followed by a separate line for manifests and layers?

I'm also tempted to move the manifest-list line below the manifest line, since fat, multi-platform images are easier to understand if you already know what a manifest is. Manifests rely on filesystems and configurations, but the reader is more likely to be able to guess at those than they are to guess the meaning of “manifest”.

coolljt0725 · 2016-11-14T08:17:52Z

@wking updated

wking · 2016-11-14T19:56:40Z

README.md

 The image configuration includes information such as application arguments, environments, etc.
-The combination of the image manifest, image configuration, and one or more filesystem layers is called the "OCI Image".
+The manifest list is a higher-level manifest which points to specific image manifest for one or more platform.
+The combination of the image manifest list(optional), image manifest, image configuration, and one or more filesystem layers is called the "OCI Image".


Missing a space in “list(optional)” (should be “list (optional)”).

wking · 2016-11-14T19:59:46Z

README.md

 ## Overview

-This specification defines how to create an OCI Image, which will generally be done by a build system, and output an [image manifest](manifest.md), a set of [filesystem layers](layer.md), and an [image configuration](config.md).
+This specification defines how to create an OCI Image, which will generally be done by a build system, and output an [image manifest](manifest.md) and may with a [manifest list](manifest-list.md), a set of [filesystem layers](layer.md), and an [image configuration](config.md).


“and may with” reads awkwardly to me. I'd rather leave this line alone, land your new “The manifest list” line, and then land a rerolled #456 mentioning manifest lists.

philips · 2016-11-16T21:28:40Z

LGTM

coolljt0725 · 2016-11-18T01:37:04Z

rebased after landing #456

wking · 2016-11-18T05:00:51Z

On Thu, Nov 17, 2016 at 05:37:04PM -0800, Lei Jitang wrote:

rebased after landing #456

6128dcd looks good to me, with the only additions being two instances
of “a manifest list (optional)” and one copy of the existing manifest
list introductory sentence 1.

jonboulle · 2016-11-24T14:11:56Z

README.md

+This specification defines an OCI Image, consisting of a [manifest](manifest.md), a [manifest list](manifest-list.md) (optional), a set of [filesystem layers](layer.md), and a [configuration](config.md).
 At a high level the image manifest contains metadata about the contents and dependencies of the image including the content-addressable identity of one or more [filesystem layer changeset](layer.md) archives that will be unpacked to make up the final runnable filesystem.
 The image configuration includes information such as application arguments, environments, etc.
+The manifest list is a higher-level manifest which points to specific image manifest for one or more platform.


manifest(s) for one or more platforms.

coolljt0725 · 2016-11-25T01:13:20Z

@jonboulle updated

jonboulle · 2016-11-25T12:22:27Z

@coolljt0725 sorry, not quite there: platforms plural

coolljt0725 · 2016-11-26T01:13:35Z

@jonboulle updated, thanks :)

coolljt0725 · 2016-12-07T09:28:36Z

rebased

vbatts · 2016-12-07T13:24:38Z

LGTM

wking · 2016-12-07T14:54:42Z

spec.md


 At a high level the image manifest contains metadata about the contents and dependencies of the image including the content-addressable identity of one or more [filesystem layer changeset](layer.md) archives that will be unpacked to make up the final runnable filesystem.
 The image configuration includes information such as application arguments, environments, etc.
+The manifest list is a higher-level manifest which points to specific image manifest(s) for one or more platforms


This line is from manifest-list.md, which uses "manifests". I'm fine with that or "manifest(s)", but I think we should use the same form in both places. So either use "manifests" here, or update image-manifest.md to use "manifest(s)".

The manifest list is a higher-level manifest which points to one or more manifests. Typically, these manifests may provide different implementations of the image, possibly varying by platform or other attributes.

@stevvooe's phrasing looks good to me, but I'd put it at the top of manifest-list.md. Here in spec.md, I'd only include the first line, but I'd make “manifest list” a link to manifest-list.md.

coolljt0725 · 2016-12-10T01:58:39Z

@stevvooe updated

Signed-off-by: Lei Jitang <[email protected]>

philips · 2017-01-18T21:42:13Z

LGTM

stevvooe · 2017-01-19T00:25:02Z

LGTM

coolljt0725 changed the title ~~README.md: add the some description about manifest list~~ README.md: add some description about manifest list Nov 10, 2016

wking mentioned this pull request Nov 10, 2016

README: Consolidate "OCI Image" definitions #456

Merged

wking reviewed Nov 10, 2016

View reviewed changes

coolljt0725 force-pushed the readme_manifest_list branch from 3e284d0 to b11e1b2 Compare November 14, 2016 08:14

wking reviewed Nov 14, 2016

View reviewed changes

coolljt0725 force-pushed the readme_manifest_list branch from b11e1b2 to d2e8f00 Compare November 15, 2016 02:00

wking mentioned this pull request Nov 16, 2016

Clean-up spec to remove non-spec-ish items #458

Merged

coolljt0725 force-pushed the readme_manifest_list branch 2 times, most recently from 3338eef to 32e07c4 Compare November 18, 2016 01:35

coolljt0725 force-pushed the readme_manifest_list branch from 32e07c4 to 6128dcd Compare November 18, 2016 03:14

jonboulle reviewed Nov 24, 2016

View reviewed changes

coolljt0725 force-pushed the readme_manifest_list branch from 6128dcd to 611c870 Compare November 25, 2016 01:11

coolljt0725 force-pushed the readme_manifest_list branch from 611c870 to d542c6f Compare November 26, 2016 01:12

coolljt0725 force-pushed the readme_manifest_list branch 2 times, most recently from fc1d451 to 94a29f4 Compare December 7, 2016 09:27

coolljt0725 changed the title ~~README.md: add some description about manifest list~~ spec.md: add some description about manifest list Dec 7, 2016

wking reviewed Dec 7, 2016

View reviewed changes

coolljt0725 force-pushed the readme_manifest_list branch from 94a29f4 to a3a7b2e Compare December 10, 2016 01:58

spec.md: add some description about manifest list

a3a7b2e

Signed-off-by: Lei Jitang <[email protected]>

stevvooe merged commit 7ccc18a into opencontainers:master Jan 19, 2017

coolljt0725 deleted the readme_manifest_list branch January 19, 2017 01:12

vbatts mentioned this pull request Jan 27, 2017

Bump version for v1.0.0-rc4 #537

Merged

spec.md: add some description about manifest list #455

spec.md: add some description about manifest list #455

Uh oh!

Conversation

coolljt0725 commented Nov 10, 2016

Uh oh!

wking left a comment • 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!

Choose a reason for hiding this comment

Uh oh!

coolljt0725 commented Nov 14, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

philips commented Nov 16, 2016 • edited by caniszczyk Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coolljt0725 commented Nov 18, 2016

Uh oh!

wking commented Nov 18, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

coolljt0725 commented Nov 25, 2016

Uh oh!

jonboulle commented Nov 25, 2016

Uh oh!

coolljt0725 commented Nov 26, 2016

Uh oh!

coolljt0725 commented Dec 7, 2016

Uh oh!

vbatts commented Dec 7, 2016 • edited by caniszczyk Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

wking Dec 7, 2016 • 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!

coolljt0725 commented Dec 10, 2016

Uh oh!

philips commented Jan 18, 2017 • edited by caniszczyk Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

stevvooe commented Jan 19, 2017 • edited by caniszczyk Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

wking left a comment •

edited

Loading

philips commented Nov 16, 2016 •

edited by caniszczyk

Loading

vbatts commented Dec 7, 2016 •

edited by caniszczyk

Loading

wking Dec 7, 2016 •

edited

Loading

philips commented Jan 18, 2017 •

edited by caniszczyk

Loading

stevvooe commented Jan 19, 2017 •

edited by caniszczyk

Loading