considerations.md: use clearer links to describe concepts

[erikh]

I felt the linking of the word are and content-addressible to foreign topics unrelated to the words needed to be changed to be more explicit. I hope you agree.

Thanks!

[wking]

On Tue, Mar 14, 2017 at 02:50:42AM -0700, Erik Hollensbe wrote: I felt the linking of the word `are` and `content-addressible` to foreign topics unrelated to the words needed to be changed to be more explicit.

image-layout.md is related to images being content addressable, because it discusses one way to store the content-addressable blobs which compose an image. descriptor.md is related to images being content addressable, because it defines the Merkle link structure. The current master approach is “link words in the vicinity of ‘content-addressable’” to those files”. To me, b081e61 seems like an awkward middle ground between “compact enough to not distract from the main point” (that canonical CAS blobs are useful) and “verbose enough to clearly motivate the links”. The compact approach is only a good idea if folks will be reasonably likely to understand how the linked files support the CAS nature of images. Since you've filed this PR, that's apparently not the case ;). b081e61 adds more words about *what* is getting linked, but you could see that by hovering over the links (or whatever your browser UI is for “show me where this goes”). I'd rather use something like my first paragraph in this comment to spell out *why* we're linking those two spec sections.

[jonboulle]

How about something like:

All of the constituent components of the OCI Image specification are content-addressable; for more background on this, see the [descriptor](descriptor.md) documentation.

[wking]

Well, the refs (now index.json) are not content addressable. But @jonboulle's proposal looks good to me if we replace:

All of the constituent components of the OCI Image specification

with:

OCI Images

That just assumes that no fundamental part of the image become mutable-refs-only, which hopefully remains true going forward ;).

[wking]

Hmm. While descriptor.md mentions Merkle DAGs, it doesn't say "content addressable". I think we need to update @jonboulle's suggestion to keep the image-layout.md link.

[jonboulle]

agree that i) current wording could be improved; ii) current diff is an awkward middle-ground

also, please no spelling regressions :-)

[erikh]

ah crap, I had a spelling error?

…

On Tue, Mar 14, 2017 at 7:54 AM, W. Trevor King ***@***.***> wrote: ***@***.**** commented on this pull request. ------------------------------ In considerations.md <#613 (comment)> : > @@ -5,7 +5,7 @@ Instead they MUST ignore unknown properties. # Canonicalization -OCI Images [are](descriptor.md) [content-addressable](image-layout.md). +OCI Images are content-addressible. See [Descriptors](descriptor.md) and [Image Layout](image-layout.md) for more information. Hmm. While descriptor.md mentions Merkle DAGs, it doesn't say "content addressable". I think we need to update @jonboulle </~https://github.com/jonboulle>'s suggestion to keep the image-layout.md link. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#613 (comment)>, or mute the thread </~https://github.com/notifications/unsubscribe-auth/AABJ64DJpUIYITJFnrN08etLAPj-Kt3Nks5rlqo0gaJpZM4McVu3> .

[erikh]

very sorry about the spelling error!

I've updated the verbiage to use jon's text. Please advise for future changes.

[wking]

I don't think we want to drop the image-layout.md link. Linking to descriptor.md (both in master and your 440aaba) establishes that we use a Merkle DAG. But you can have a Merkle DAG without content addressability (e.g. if you're using a Merkle tree for signing [1]). Merkle DAGs play nicely with hash-based content addressability, but you can have either without the other. The canonicalization point doesn't actually depend on the Merkle-DAG-ness of the image at all, so if we want to boil this down to a single reference, I suggest we stick with the image-layout.md link (and drop the descriptor.md link if you like). Of course, the image layout is optional (or at least that's my impression. I can't find spec wording to back it up). Image-storage systems may not all use CAS or benefit from canonicalization. But the fact that CAS-based storage is possible is enough to motivate the SHOULD-canonicalize here. How about wording like: OCI Images MAY be held in content-addressable storage (for example, in the [OCI Image Layout](image-layout.md)). [1]: https://www.google.com/patents/US4309569

[erikh]

I'm honestly not sure how much worth arguing over a single referenced link is, no matter the semantic necessity. That said, happy to make the changes if the maintainers agree.

…

On Wed, Mar 15, 2017 at 1:52 AM, W. Trevor King ***@***.***> wrote: I don't think we want to drop the image-layout.md link. Linking to descriptor.md (both in master and your 440aaba establishes that we use a Merkle DAG. But you can have a Merkle DAG without content addressability (e.g. if you're using a Merkle tree for signing [1]). Merkle DAGs play nicely with hash-based content addressability, but you can have either without the other. The canonicalization point doesn't actually depend on the Merkle-DAG-ness of the image at all, so if we want to boil this down to a single reference, I suggest we stick with the image-layout.md link (and drop the descriptor.md link if you like). Of course, the image layout is optional (or at least that's my impression. I can't find spec wording to back it up). Image-storage systems may not all use CAS or benefit from canonicalization. But the fact that CAS-based storage is possible is enough to motivate the SHOULD-canonicalize here. How about wording like: OCI Images MAY be held in content-addressable storage (for example, in the [OCI Image Layout](image-layout.md)). [1]: https://www.google.com/patents/US4309569 — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#613 (comment)>, or mute the thread </~https://github.com/notifications/unsubscribe-auth/AABJ63HqFjyWfN8YqHefUHZDujMp3e8zks5rl6a4gaJpZM4McVu3> .

[stevvooe]

image-layout.md is related to images being content addressable,
because it discusses one way to store the content-addressable blobs
which compose an image.

This is a WIDE stretch. Introducing content addressability through the image layout is not going to help the reader understand anything at all, and I think that is the point of this submission.

But you can have a Merkle DAG without content
addressability (e.g. if you're using a Merkle tree for signing [1]).
Merkle DAGs play nicely with hash-based content addressability, but
you can have either without the other.

This is an extremely odd understanding of merkle signatures. This distinction is nonsense. They are signatures that exploit the properties of merkle trees. They play nicely because one is an application of the other.

We employ content-addressable references in a tree, because they exploit the fact that holding the result of a "one way" function in a tree of references will always result in a DAG. This same property is employed in Merkle's paper in the implementation of a signature algorithm. Colloquially, trees with this property are call "Merkle trees".

@erikh It would be best to link out to the wikipedia article on content addressability and link to descriptors as the "vehicle" we use to implement content addressability.

[erikh]

Ok I will do that later tonight.

…

-Erik

On Mon, Mar 20, 2017 at 4:48 PM Stephen Day ***@***.***> wrote: image-layout.md is related to images being content addressable, because it discusses one way to store the content-addressable blobs which compose an image. This is a *WIDE* stretch. Introducing content addressability through the image layout is not going to help the reader understand anything at all, and I think that is the point of this submission. But you can have a Merkle DAG without content addressability (e.g. if you're using a Merkle tree for signing [1]). Merkle DAGs play nicely with hash-based content addressability, but you can have either without the other. This is an extremely odd understanding of merkle signatures. This distinction is nonsense. They are signatures that exploit the properties of merkle trees. They play nicely because one is an application of the other. We employ content-addressable references in a tree, because they exploit the fact that holding the result of a "one way" function in a tree of references will always result in a DAG. This same property is employed in Merkle's paper in the implementation of a signature algorithm. Colloquially, trees with this property are call "Merkle trees". @erikh </~https://github.com/erikh> It would be best to link out to the wikipedia article on content addressability and link to descriptors as the "vehicle" we use to implement content addressability. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#613 (comment)>, or mute the thread </~https://github.com/notifications/unsubscribe-auth/AABJ61oMdQBvZYEdCW1kfMGmL8T6DNNwks5rnxAugaJpZM4McVu3> .

[wking]

On Mon, Mar 20, 2017 at 04:48PM -0700, Stephen Day wrote: > But you can have a Merkle DAG without content addressability > (e.g. if you're using a Merkle tree for signing [1]). Merkle DAGs > play nicely with hash-based content addressability, but you can > have either without the other. This is an extremely odd understanding of merkle signatures. This distinction is nonsense. They are signatures that exploit the properties of merkle trees. They play nicely because one is an application of the other.

Having a Merkle DAG doesn't mean you have any way to access the tree nodes using their Merkle hash. Excepting image-layout, this spec only talks about hashing, and says nothing about addressing the blobs. And you could invent any number of image-store engines that were not content addressable. And if you were only ever going to use such stores, there would be no point in canonicalizing your JSON.

[erikh]

PTAL, updated with wikipedia link. On Mon, Mar 20, 2017 at 5:04 PM W. Trevor King <notifications@github.com> wrote:

…

On Mon, Mar 20, 2017 at 04:48PM -0700, Stephen Day wrote: > > But you can have a Merkle DAG without content addressability > > (e.g. if you're using a Merkle tree for signing [1]). Merkle DAGs > > play nicely with hash-based content addressability, but you can > > have either without the other. > > This is an extremely odd understanding of merkle signatures. This > distinction is nonsense. They are signatures that exploit the > properties of merkle trees. They play nicely because one is an > application of the other. Having a Merkle DAG doesn't mean you have any way to access the tree nodes using their Merkle hash. Excepting image-layout, this spec only talks about hashing, and says nothing about addressing the blobs. And you could invent any number of image-store engines that were not content addressable. And if you were only ever going to use such stores, there would be no point in canonicalizing your JSON. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#613 (comment)>, or mute the thread </~https://github.com/notifications/unsubscribe-auth/AABJ621JdeS6QxEMqH0yOsJFg5ElOzW8ks5rnxP7gaJpZM4McVu3> .

[AkihiroSuda]

As @wking mentioned (#613 (comment)), "All of the constituent components" seems misleading, because oci-layout and index.json are not

[vbatts]

this SGTM except the phrase "all the constituent components"

[erikh]

Ok hm. I will revisit in an hour or two.

…

-Erik

On Mon, Apr 3, 2017 at 4:27 PM Vincent Batts ***@***.***> wrote: this SGTM except the phrase "all the constituent components" — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#613 (comment)>, or mute the thread </~https://github.com/notifications/unsubscribe-auth/AABJ6_apfUp0_Uu8DwgsB1Xjuvg8_-l7ks5rsYBugaJpZM4McVu3> .

[erikh]

Actually unless you folks wish to re-incorporate some of the terms in here, the merge conflict is literally the whole paragraph between another bulleted-list patch I did that was merged today.

We kind of winded off the beaten path but I'm not seeing much that deserves keeping this PR around beyond clarification of the links. I've made those edits to the first line, and left the rest alone.

If there's something I should re-incorporate or otherwise needs to be changed, please LMK!

[jonboulle]

I agree we've kind of wandered into (and around) the weeds here, apologies about that. Latest incarnation LGTM in itself though.

[stevvooe]

LGTM