spec.md: add some description about manifest list #455
Conversation
coolljt0725
changed the title
There was a problem hiding this comment.
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.
| 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". |
There was a problem hiding this comment.
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".
There was a problem hiding this comment.
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.
| 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 was a problem hiding this comment.
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
force-pushed
the
readme_manifest_list
branch
from
3e284d0
to
b11e1b2
Compare
|
@wking updated |
| 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 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". |
There was a problem hiding this comment.
Missing a space in “list(optional)” (should be “list (optional)”).
| @@ -19,10 +19,11 @@ The goal of this specification is to enable the creation of interoperable tools | |||
|
|
|||
| ## 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). | |||
There was a problem hiding this comment.
“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.
coolljt0725
force-pushed
the
readme_manifest_list
branch
from
b11e1b2
to
d2e8f00
Compare
|
LGTM |
coolljt0725
force-pushed
the
readme_manifest_list
branch
2 times, most recently
from
3338eef
to
32e07c4
Compare
|
rebased after landing #456 |
coolljt0725
force-pushed
the
readme_manifest_list
branch
from
32e07c4
to
6128dcd
Compare
| 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. |
There was a problem hiding this comment.
manifest(s) for one or more platforms.
coolljt0725
force-pushed
the
readme_manifest_list
branch
from
6128dcd
to
611c870
Compare
|
@jonboulle updated |
|
@coolljt0725 sorry, not quite there: platforms plural |
coolljt0725
force-pushed
the
readme_manifest_list
branch
from
611c870
to
d542c6f
Compare
|
@jonboulle updated, thanks :) |
coolljt0725
force-pushed
the
readme_manifest_list
branch
2 times, most recently
from
fc1d451
to
94a29f4
Compare
coolljt0725
changed the title
|
rebased |
|
LGTM |
| @@ -29,6 +29,7 @@ The key words "unspecified", "undefined", and "implementation-defined" are to be | |||
|
|
|||
| 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 | |||
There was a problem hiding this comment.
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)".
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
@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
force-pushed
the
readme_manifest_list
branch
from
94a29f4
to
a3a7b2e
Compare
|
@stevvooe updated |
Signed-off-by: Lei Jitang <leijitang@huawei.com>
|
LGTM |
1 similar comment
|
LGTM |
Signed-off-by: Lei Jitang leijitang@huawei.com