Use layer digest in the description of DiffID #328

coolljt0725 · 2016-09-19T11:40:04Z

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

manifest digest means the digest of manifest, I think this is wrong.

wking · 2016-09-19T17:30:21Z

config.md

@@ -32,7 +32,7 @@ This specification uses the following terms:
    <dd>
 	A layer DiffID is a SHA256 digest over the layer's uncompressed tar archive and serialized in the descriptor digest format, e.g., <code>sha256:a9561eb1b190625c9adb5a9513e72c4dedafc1cb2d4c5236c9a6957ec7dfd5a9</code>.
 	Layers must be packed and unpacked reproducibly to avoid changing the layer ID, for example by using tar-split to save the tar headers.
-	NOTE: the DiffID is different than the digest in the manifest list because the manifest digest is taken over the gzipped layer for <code>application/vnd.oci.image.layer.tar+gzip</code> types.
+	NOTE: the DiffID is different than the digest in the manifest list because the digest in the manifest is taken over the gzipped layer for <code>application/vnd.oci.image.layer.tar+gzip</code> types.


+1 to avoiding “manifest digest”. But to make it extra clear that we're comparing with layer digests, how about a separate paragraph:

The DiffID is different than the layer digest in the <a href="manifest.md#image-manifest-property-descriptions">manifest's <code>layers</code></a> because the layer digest is taken over the blob regardless of compression, while the DiffID is taken after removing any compression. For an <code>application/vnd.oci.image.layer.tar+gzip</code> layer.md, the layer digest is taken over the <code>application/vnd.oci.image.layer.tar+gzip</code> content, while the DiffID is take over the <code>application/vnd.oci.image.layer.tar</code> content.

Although that gets into defining a +gzip suffix (more on that in #316).

@wking You suggestion make it much more clear, but the application/vnd.oci.image.layer.tar is not explicit define at the moment.

Mentioning manifests here is the real problem. We should probably just say this is the content of the uncompressed layer tar.

wking · 2016-09-20T08:37:01Z

On Mon, Sep 19, 2016 at 07:35:57PM -0700, Lei Jitang wrote:

NOTE: the DiffID is different than the digest in the manifest list because the manifest digest is taken over the gzipped layer for application/vnd.oci.image.layer.tar+gzip types.

NOTE: the DiffID is different than the digest in the manifest list because the digest in the manifest is taken over the gzipped layer for application/vnd.oci.image.layer.tar+gzip types.

@wking You suggestion make it much more clear, but the
application/vnd.oci.image.layer.tar is not explicit define at the
moment.

So we wait until #316 or similar lands with a definition of the +gzip
suffix? I'll work up a PR for the suffix.

vbatts · 2016-09-21T19:57:01Z

On 20/09/16 01:37 -0700, W. Trevor King wrote:

So we wait until #316 or similar lands with a definition of the +gzip
suffix? I'll work up a PR for the suffix.

This change does not require waiting on the +gzip wording. That is one
of the ways that removing it here causes confusion.

vbatts · 2016-09-21T19:59:42Z

This LGTM though perhaps it could go a step further to word that "the digest in the manifest is taken over the entire object" or " ... opaque blob"? So it is not so specific to just gzipped layers?

wking · 2016-09-21T20:13:34Z

On Wed, Sep 21, 2016 at 12:57:02PM -0700, Vincent Batts wrote:

On 20/09/16 01:37 -0700, W. Trevor King wrote:

So we wait until #316 or similar lands with a definition of the
+gzip suffix? I'll work up a PR for the suffix.

This change does not require waiting on the +gzip wording. That is
one of the ways that removing it here causes confusion.

With the suffix defined, we could use the wording I've proposed in
1. @coolljt0725 liked that wording, but (correctly) pointed out
that it only makes sense once application/vnd.oci.image.layer.tar has
been defined 2. With the +gzip PR (#332), both
application/vnd.oci.image.layer.tar and
application/vnd.oci.image.layer.tar+gzip will be defined, and we can
use the wording from 1.

stevvooe · 2016-09-21T23:53:39Z

config.md

@@ -32,7 +32,7 @@ This specification uses the following terms:
    <dd>
 	A layer DiffID is a SHA256 digest over the layer's uncompressed tar archive and serialized in the descriptor digest format, e.g., <code>sha256:a9561eb1b190625c9adb5a9513e72c4dedafc1cb2d4c5236c9a6957ec7dfd5a9</code>.
 	Layers must be packed and unpacked reproducibly to avoid changing the layer ID, for example by using tar-split to save the tar headers.
-	NOTE: the DiffID is different than the digest in the manifest list because the manifest digest is taken over the gzipped layer for <code>application/vnd.oci.image.layer.tar+gzip</code> types.
+	NOTE: the DiffID is different than the digest in the manifest list because the digest in the manifest is taken over the gzipped layer for <code>application/vnd.oci.image.layer.tar+gzip</code> types.


Mentioning manifests here is the real problem. We should probably just say this is the content of the uncompressed layer tar.

coolljt0725 · 2016-09-22T03:24:57Z

updated
@vbatts @stevvooe

vbatts · 2016-09-22T19:31:12Z

config.md

@@ -32,7 +32,7 @@ This specification uses the following terms:
    <dd>
 	A layer DiffID is a SHA256 digest over the layer's uncompressed tar archive and serialized in the descriptor digest format, e.g., <code>sha256:a9561eb1b190625c9adb5a9513e72c4dedafc1cb2d4c5236c9a6957ec7dfd5a9</code>.
 	Layers must be packed and unpacked reproducibly to avoid changing the layer ID, for example by using tar-split to save the tar headers.
-	NOTE: the DiffID is different than the digest in the manifest list because the manifest digest is taken over the gzipped layer for <code>application/vnd.oci.image.layer.tar+gzip</code> types.
+	NOTE: the DiffID is different than the layer digest because the digest is taken over the content of the uncompressted layer tar for <code>application/vnd.oci.image.layer.tar+gzip</code> types.


uncompressed

@vbatts fixed, thx

coolljt0725 · 2016-09-28T01:41:42Z

@vbatts @stevvooe rebased after #333

vbatts · 2016-10-06T18:03:28Z

LGTM

vbatts · 2016-10-19T13:29:17Z

the needs another LGTM

stevvooe · 2016-10-19T22:11:27Z

config.md

@@ -28,7 +28,7 @@ Changing it means creating a new derived image, instead of changing the existing
 A layer DiffID is a SHA256 digest over the layer's uncompressed tar archive and serialized in the descriptor digest format, e.g., `sha256:a9561eb1b190625c9adb5a9513e72c4dedafc1cb2d4c5236c9a6957ec7dfd5a9`.
 Layers must be packed and unpacked reproducibly to avoid changing the layer DiffID, for example by using tar-split to save the tar headers.

-NOTE: the DiffID is different than the digest in the manifest list because the manifest digest is taken over the gzipped layer for `application/vnd.oci.image.layer.v1.tar+gzip` types.
+NOTE: the DiffID is different than the layer digest because the layer digest is taken over the content of the gzipped layer for `application/vnd.oci.image.layer.v1.tar+gzip` types.


NOTE: the DiffID is different than the layer digest because it is taken over the uncompressed content of the gzipped layer for application/vnd.oci.image.layer.v1.tar+gzip types.

Your suggested language points out the DiffID being over the uncompressed content. @coolljt0725's current wording points out the layer digest being over the (raw) gzipped content. Both of these are important for understanding the difference, and while the uncompressed-ness of DiffID is mentioned in the previous paragraph, I think it's worth talking about both of them in this note. I have wording for that in my earlier suggestion. Until something like #332 or #388 lands, we could just use “over the uncompressed content” instead of “over the application/vnd.oci.image.layer.v1.tar content”.

coolljt0725 · 2016-10-20T01:28:14Z

@stevvooe updated

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

stevvooe · 2016-10-21T18:33:34Z

LGTM

coolljt0725 · 2016-10-24T02:18:00Z

ping @vbatts needs re-LGTM after rebasing

vbatts · 2016-10-24T13:14:55Z

LGTM

wking reviewed Sep 19, 2016

View reviewed changes

wking mentioned this pull request Sep 20, 2016

media-types: Define '+gzip' structured syntax suffix #332

Closed

stevvooe requested changes Sep 21, 2016

View reviewed changes

coolljt0725 force-pushed the digest branch from d6633bf to f06fef7 Compare September 22, 2016 03:22

coolljt0725 changed the title ~~Replace 'manifest digest' with 'the digest in manifest'~~ Use layer digest in the description of DiffID Sep 22, 2016

vbatts reviewed Sep 22, 2016

View reviewed changes

coolljt0725 force-pushed the digest branch 2 times, most recently from 3b5a4b2 to a319777 Compare September 28, 2016 01:39

coolljt0725 force-pushed the digest branch from a319777 to f7b5cb5 Compare October 3, 2016 12:58

stevvooe reviewed Oct 19, 2016

View reviewed changes

coolljt0725 force-pushed the digest branch from f7b5cb5 to 5fb15b3 Compare October 20, 2016 01:27

coolljt0725 force-pushed the digest branch from 5fb15b3 to ffcaa5e Compare October 20, 2016 01:31

Use layer digest in the description of DiffID

ffcaa5e

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

stevvooe approved these changes Oct 21, 2016

View reviewed changes

vbatts merged commit 48e3743 into opencontainers:master Oct 24, 2016

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Use layer digest in the description of DiffID #328

Use layer digest in the description of DiffID #328

coolljt0725 commented Sep 19, 2016

wking Sep 19, 2016

coolljt0725 Sep 20, 2016

stevvooe Sep 21, 2016

wking commented Sep 20, 2016

vbatts commented Sep 21, 2016

vbatts commented Sep 21, 2016 via email

wking commented Sep 21, 2016

stevvooe Sep 21, 2016

coolljt0725 commented Sep 22, 2016

vbatts Sep 22, 2016

coolljt0725 Sep 23, 2016

coolljt0725 commented Sep 28, 2016

vbatts commented Oct 6, 2016 •

edited by caniszczyk

Loading

vbatts commented Oct 19, 2016

stevvooe Oct 19, 2016

wking Oct 19, 2016 •

edited

Loading

coolljt0725 commented Oct 20, 2016

stevvooe commented Oct 21, 2016 •

edited by caniszczyk

Loading

coolljt0725 commented Oct 24, 2016

vbatts commented Oct 24, 2016 •

edited by caniszczyk

Loading

Use layer digest in the description of DiffID #328

Use layer digest in the description of DiffID #328

Conversation

coolljt0725 commented Sep 19, 2016

wking Sep 19, 2016

Choose a reason for hiding this comment

coolljt0725 Sep 20, 2016

Choose a reason for hiding this comment

stevvooe Sep 21, 2016

Choose a reason for hiding this comment

wking commented Sep 20, 2016

vbatts commented Sep 21, 2016

vbatts commented Sep 21, 2016 via email

wking commented Sep 21, 2016

stevvooe Sep 21, 2016

Choose a reason for hiding this comment

coolljt0725 commented Sep 22, 2016

vbatts Sep 22, 2016

Choose a reason for hiding this comment

coolljt0725 Sep 23, 2016

Choose a reason for hiding this comment

coolljt0725 commented Sep 28, 2016

vbatts commented Oct 6, 2016 • edited by caniszczyk Loading

vbatts commented Oct 19, 2016

stevvooe Oct 19, 2016

Choose a reason for hiding this comment

wking Oct 19, 2016 • edited Loading

Choose a reason for hiding this comment

coolljt0725 commented Oct 20, 2016

stevvooe commented Oct 21, 2016 • edited by caniszczyk Loading

coolljt0725 commented Oct 24, 2016

vbatts commented Oct 24, 2016 • edited by caniszczyk Loading

vbatts commented Oct 6, 2016 •

edited by caniszczyk

Loading

wking Oct 19, 2016 •

edited

Loading

stevvooe commented Oct 21, 2016 •

edited by caniszczyk

Loading

vbatts commented Oct 24, 2016 •

edited by caniszczyk

Loading