README: rework description of spec components #621

erikh · 2017-03-21T02:37:18Z

This replaces the inline links with a bulleted list that clearly states each part of the spec and a little blurb that describes it. I think it's a much easier way to navigate, I hope you agree.

I also made the README link to the spec a lot more prominent.

vbatts · 2017-03-21T13:22:57Z

@RobDolinMS is this PR what you were referring to?

jbouzane · 2017-03-22T21:00:13Z

I'm concerned about this PR because it presents itself as a formatting change, but it's removing some text from spec.md. Is that intentional, or did it just get lost in the change?

erikh · 2017-03-23T01:11:31Z

What text concerns you specifically? The goal really is to clarify, so if I made something worse, happy to fix it.

…

On Wed, Mar 22, 2017 at 2:00 PM Jason Bouzane ***@***.***> wrote: I'm concerned about this PR because it presents itself as a formatting change, but it's removing some text from spec.md. Is that intentional, or did it just get lost in the change? — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#621 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AABJ6wZSeIyjXylsMxmO8y3PEPKphUOQks5roYvdgaJpZM4MjQl8> .

stevvooe · 2017-04-03T21:10:38Z

I'm concerned about this PR because it presents itself as a formatting change, but it's removing some text from spec.md. Is that intentional, or did it just get lost in the change?

These changes represent a more realistic presentation of the specification.

It looks like there is some language here that was removed for road map items (signatures and naming/federation).

@erikh Would you mind adding those bullets back?

erikh · 2017-04-04T00:17:07Z

I will do it in an hour or so.

…

-Erik

On Mon, Apr 3, 2017 at 2:10 PM Stephen Day ***@***.***> wrote: I'm concerned about this PR because it presents itself as a formatting change, but it's removing some text from spec.md. Is that intentional, or did it just get lost in the change? These changes represent a more realistic presentation of the specification. It looks like there is some language here that was removed for road map items (signatures and naming/federation). @erikh <https://github.com/erikh> Would you mind adding those bullets back? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#621 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AABJ60SwqaHXUxZAGyviMLCLW-gdl4isks5rsWBOgaJpZM4MjQl8> .

erikh · 2017-04-04T08:38:15Z

@stevvooe I've made the updates, is this what you're after?

jonboulle

I appreciate the effort, but frankly I find all these short descriptions a bit confusing. Do we need them here? If so, can we just re-use the tagline or high level description from the respective documents?

jonboulle · 2017-04-04T13:33:06Z

spec.md

-* An archival format for container images, consisting of an [image manifest](manifest.md), an [image index](image-index.md) (optional), an [image layout](image-layout.md), a set of [filesystem layers](layer.md), and [image configuration](config.md) (base OCI layer)
-* A [process of referencing container images by a cryptographic hash of their content](descriptor.md) (base OCI layer)
-* A format for [storing CAS blobs and references to them](image-layout.md) (optional OCI layer)
+* [Image Manifest](manifest.md) - the stored document describing an image's properties


Where is the "stored document" stored?

jonboulle · 2017-04-04T13:33:09Z

spec.md

-* A [process of referencing container images by a cryptographic hash of their content](descriptor.md) (base OCI layer)
-* A format for [storing CAS blobs and references to them](image-layout.md) (optional OCI layer)
+* [Image Manifest](manifest.md) - the stored document describing an image's properties
+* [Image Index](image-index.md) - the stored document describing a collection of images redistributed as one


Is an image index really a collection of images redistributed as one? (It sort of implies it's bundled together, is that necessarily the case?)

More or less. Effectively, they reference one or more manifests, annotating the underlying content with platform information "pulled up" config. In practice, we could compare this to a "fat binary", although the content isn't embedded.

"An index of annotated image manifests distributed as a complete unit."

Not great, but that might help to better describe this.

jonboulle · 2017-04-04T13:33:56Z

spec.md

+* [Image Manifest](manifest.md) - the stored document describing an image's properties
+* [Image Index](image-index.md) - the stored document describing a collection of images redistributed as one
+* [Image Layout](image-layout.md) - the filesystem layout representing the contents of an image
+* [Filesystem Layers](layer.md) - the building block of image data


IMHO this description is a bit vague

"changesets that describe a container's filesystem"

jonboulle · 2017-04-04T13:34:47Z

spec.md

+* [Image Layout](image-layout.md) - the filesystem layout representing the contents of an image
+* [Filesystem Layers](layer.md) - the building block of image data
+* [Image Configuration](config.md) - the stored document determining layer ordering and configuration of the image suitable for consumption by runtime-spec
+* [Descriptors](descriptor.md) - a concept used to refer to container images by the hash of their content


it's not just container images, it's all components of the spec

"Describes the type, metadata and content address of referenced content."

jonboulle · 2017-04-04T13:35:50Z

spec.md

+* [Image Index](image-index.md) - the stored document describing a collection of images redistributed as one
+* [Image Layout](image-layout.md) - the filesystem layout representing the contents of an image
+* [Filesystem Layers](layer.md) - the building block of image data
+* [Image Configuration](config.md) - the stored document determining layer ordering and configuration of the image suitable for consumption by runtime-spec


Not really suitable for consumption; maybe this would more appropriately link to what comes out of #492

what do we do for now though?

erikh · 2017-04-04T17:23:33Z

Ok. I will pull the information from the other docs; didn't think of that.

…

On Tue, Apr 4, 2017 at 6:36 AM Jonathan Boulle ***@***.***> wrote: ***@***.**** commented on this pull request. I appreciate the effort, but frankly I find all these short descriptions a bit confusing. Do we need them here? If so, can we just re-use the tagline or high level description from the respective documents? ------------------------------ In spec.md <#621 (comment)> : > @@ -51,9 +51,12 @@ The [OCI Image Media Types](media-types.md) document is a starting point to unde The high-level components of the spec include: -* An archival format for container images, consisting of an [image manifest](manifest.md), an [image index](image-index.md) (optional), an [image layout](image-layout.md), a set of [filesystem layers](layer.md), and [image configuration](config.md) (base OCI layer) -* A [process of referencing container images by a cryptographic hash of their content](descriptor.md) (base OCI layer) -* A format for [storing CAS blobs and references to them](image-layout.md) (optional OCI layer) +* [Image Manifest](manifest.md) - the stored document describing an image's properties Where is the "stored document" stored? ------------------------------ In spec.md <#621 (comment)> : > @@ -51,9 +51,12 @@ The [OCI Image Media Types](media-types.md) document is a starting point to unde The high-level components of the spec include: -* An archival format for container images, consisting of an [image manifest](manifest.md), an [image index](image-index.md) (optional), an [image layout](image-layout.md), a set of [filesystem layers](layer.md), and [image configuration](config.md) (base OCI layer) -* A [process of referencing container images by a cryptographic hash of their content](descriptor.md) (base OCI layer) -* A format for [storing CAS blobs and references to them](image-layout.md) (optional OCI layer) +* [Image Manifest](manifest.md) - the stored document describing an image's properties +* [Image Index](image-index.md) - the stored document describing a collection of images redistributed as one Is an image index really a collection of images redistributed *as one*? (It sort of implies it's bundled together, is that necessarily the case?) ------------------------------ In spec.md <#621 (comment)> : > @@ -51,9 +51,12 @@ The [OCI Image Media Types](media-types.md) document is a starting point to unde The high-level components of the spec include: -* An archival format for container images, consisting of an [image manifest](manifest.md), an [image index](image-index.md) (optional), an [image layout](image-layout.md), a set of [filesystem layers](layer.md), and [image configuration](config.md) (base OCI layer) -* A [process of referencing container images by a cryptographic hash of their content](descriptor.md) (base OCI layer) -* A format for [storing CAS blobs and references to them](image-layout.md) (optional OCI layer) +* [Image Manifest](manifest.md) - the stored document describing an image's properties +* [Image Index](image-index.md) - the stored document describing a collection of images redistributed as one +* [Image Layout](image-layout.md) - the filesystem layout representing the contents of an image +* [Filesystem Layers](layer.md) - the building block of image data IMHO this description is a bit vague ------------------------------ In spec.md <#621 (comment)> : > @@ -51,9 +51,12 @@ The [OCI Image Media Types](media-types.md) document is a starting point to unde The high-level components of the spec include: -* An archival format for container images, consisting of an [image manifest](manifest.md), an [image index](image-index.md) (optional), an [image layout](image-layout.md), a set of [filesystem layers](layer.md), and [image configuration](config.md) (base OCI layer) -* A [process of referencing container images by a cryptographic hash of their content](descriptor.md) (base OCI layer) -* A format for [storing CAS blobs and references to them](image-layout.md) (optional OCI layer) +* [Image Manifest](manifest.md) - the stored document describing an image's properties +* [Image Index](image-index.md) - the stored document describing a collection of images redistributed as one +* [Image Layout](image-layout.md) - the filesystem layout representing the contents of an image +* [Filesystem Layers](layer.md) - the building block of image data +* [Image Configuration](config.md) - the stored document determining layer ordering and configuration of the image suitable for consumption by runtime-spec +* [Descriptors](descriptor.md) - a concept used to refer to container images by the hash of their content it's not just container images, it's all components of the spec ------------------------------ In spec.md <#621 (comment)> : > @@ -51,9 +51,12 @@ The [OCI Image Media Types](media-types.md) document is a starting point to unde The high-level components of the spec include: -* An archival format for container images, consisting of an [image manifest](manifest.md), an [image index](image-index.md) (optional), an [image layout](image-layout.md), a set of [filesystem layers](layer.md), and [image configuration](config.md) (base OCI layer) -* A [process of referencing container images by a cryptographic hash of their content](descriptor.md) (base OCI layer) -* A format for [storing CAS blobs and references to them](image-layout.md) (optional OCI layer) +* [Image Manifest](manifest.md) - the stored document describing an image's properties +* [Image Index](image-index.md) - the stored document describing a collection of images redistributed as one +* [Image Layout](image-layout.md) - the filesystem layout representing the contents of an image +* [Filesystem Layers](layer.md) - the building block of image data +* [Image Configuration](config.md) - the stored document determining layer ordering and configuration of the image suitable for consumption by runtime-spec Not really suitable for consumption; maybe this would more appropriately link to what comes out of #492 <#492> — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#621 (review)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AABJ69uQdKvXaf-1K3DTI3x_ZT9GF1mQks5rskdQgaJpZM4MjQl8> .

stevvooe · 2017-04-04T21:29:08Z

@stevvooe I've made the updates, is this what you're after?

Yea, the separation looks good.

The descriptions of each component need a little work. I'll comment in line.

stevvooe · 2017-04-04T21:29:38Z

spec.md

-* An archival format for container images, consisting of an [image manifest](manifest.md), an [image index](image-index.md) (optional), an [image layout](image-layout.md), a set of [filesystem layers](layer.md), and [image configuration](config.md) (base OCI layer)
-* A [process of referencing container images by a cryptographic hash of their content](descriptor.md) (base OCI layer)
-* A format for [storing CAS blobs and references to them](image-layout.md) (optional OCI layer)
+* [Image Manifest](manifest.md) - the stored document describing an image's properties


"Describes the components that make up a container image."

jonboulle · 2017-04-04T22:08:10Z

Steve's suggestions look good to me Am 04.04.2017 23:31 schrieb "Stephen Day" <notifications@github.com>:

…

***@***.**** commented on this pull request. ------------------------------ In spec.md <#621 (comment)> : > @@ -51,9 +51,12 @@ The [OCI Image Media Types](media-types.md) document is a starting point to unde The high-level components of the spec include: -* An archival format for container images, consisting of an [image manifest](manifest.md), an [image index](image-index.md) (optional), an [image layout](image-layout.md), a set of [filesystem layers](layer.md), and [image configuration](config.md) (base OCI layer) -* A [process of referencing container images by a cryptographic hash of their content](descriptor.md) (base OCI layer) -* A format for [storing CAS blobs and references to them](image-layout.md) (optional OCI layer) +* [Image Manifest](manifest.md) - the stored document describing an image's properties +* [Image Index](image-index.md) - the stored document describing a collection of images redistributed as one +* [Image Layout](image-layout.md) - the filesystem layout representing the contents of an image +* [Filesystem Layers](layer.md) - the building block of image data +* [Image Configuration](config.md) - the stored document determining layer ordering and configuration of the image suitable for consumption by runtime-spec +* [Descriptors](descriptor.md) - a concept used to refer to container images by the hash of their content "Describes the type, metadata and content address of referenced content." — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#621 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ACewNxwshhDHWO22_L0fTO6U8c6u2S-qks5rsra0gaJpZM4MjQl8> .

erikh · 2017-04-05T08:49:56Z

Thanks for the guidance, should have these incorporated by EOD. I know the schedule is tight.

Signed-off-by: Erik Hollensbe <github@hollensbe.org>

erikh · 2017-04-05T11:29:52Z

PTAL

vbatts · 2017-04-05T13:57:45Z

LGTM

stevvooe · 2017-04-05T19:12:01Z

LGTM

Chasing opencontainers#621, standardise on case/punctuation/articles Signed-off-by: Jonathan Boulle <jonathanboulle@gmail.com>

erikh force-pushed the rewrite-spec-links branch from 940c59f to c4fa2fa Compare March 21, 2017 02:38

erikh mentioned this pull request Mar 21, 2017

FINAL v1.0 RELEASE BURN DOWN #615

Closed

2 tasks

erikh force-pushed the rewrite-spec-links branch from c4fa2fa to d9c9df9 Compare April 4, 2017 08:37

jonboulle reviewed Apr 4, 2017

View reviewed changes

jonboulle changed the title ~~Rewrite spec links~~ README: rework description of spec components Apr 4, 2017

stevvooe reviewed Apr 4, 2017

View reviewed changes

erikh force-pushed the rewrite-spec-links branch from d9c9df9 to 702d8a7 Compare April 5, 2017 11:28

spec.md: rewrite links to spec parts to be more obvious

687d989

Signed-off-by: Erik Hollensbe <github@hollensbe.org>

erikh force-pushed the rewrite-spec-links branch from 702d8a7 to 687d989 Compare April 5, 2017 11:29

stevvooe merged commit e9f698e into opencontainers:master Apr 5, 2017

erikh deleted the rewrite-spec-links branch April 6, 2017 09:29

jonboulle added a commit to jonboulle/image-spec that referenced this pull request Apr 6, 2017

spec: consistent wording

e10b04d

Chasing opencontainers#621, standardise on case/punctuation/articles Signed-off-by: Jonathan Boulle <jonathanboulle@gmail.com>

jonboulle mentioned this pull request Apr 6, 2017

spec: consistent wording #641

Merged

jonboulle added a commit to jonboulle/image-spec that referenced this pull request Apr 7, 2017

spec: consistent wording

0cc871e

Chasing opencontainers#621, standardise on case/punctuation/articles Signed-off-by: Jonathan Boulle <jonathanboulle@gmail.com>

vbatts mentioned this pull request May 19, 2017

Bump version to rc6 #681

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README: rework description of spec components #621

README: rework description of spec components #621

erikh commented Mar 21, 2017

vbatts commented Mar 21, 2017

jbouzane commented Mar 22, 2017

erikh commented Mar 23, 2017 via email

stevvooe commented Apr 3, 2017

erikh commented Apr 4, 2017 via email

erikh commented Apr 4, 2017

jonboulle left a comment

jonboulle Apr 4, 2017

jonboulle Apr 4, 2017

stevvooe Apr 4, 2017

jonboulle Apr 4, 2017

stevvooe Apr 4, 2017

jonboulle Apr 4, 2017

stevvooe Apr 4, 2017

jonboulle Apr 4, 2017

erikh Apr 5, 2017

erikh commented Apr 4, 2017 via email

stevvooe commented Apr 4, 2017

stevvooe Apr 4, 2017

jonboulle commented Apr 4, 2017 via email

erikh commented Apr 5, 2017

erikh commented Apr 5, 2017

vbatts commented Apr 5, 2017 •

edited by caniszczyk

Loading

stevvooe commented Apr 5, 2017 •

edited by caniszczyk

Loading

README: rework description of spec components #621

README: rework description of spec components #621

Conversation

erikh commented Mar 21, 2017

vbatts commented Mar 21, 2017

jbouzane commented Mar 22, 2017

erikh commented Mar 23, 2017 via email

stevvooe commented Apr 3, 2017

erikh commented Apr 4, 2017 via email

erikh commented Apr 4, 2017

jonboulle left a 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

Choose a reason for hiding this comment

Choose a reason for hiding this comment

erikh commented Apr 4, 2017 via email

stevvooe commented Apr 4, 2017

Choose a reason for hiding this comment

jonboulle commented Apr 4, 2017 via email

erikh commented Apr 5, 2017

erikh commented Apr 5, 2017

vbatts commented Apr 5, 2017 • edited by caniszczyk Loading

stevvooe commented Apr 5, 2017 • edited by caniszczyk Loading

vbatts commented Apr 5, 2017 •

edited by caniszczyk

Loading

stevvooe commented Apr 5, 2017 •

edited by caniszczyk

Loading