considerations.md: use clearer links to describe concepts #613
Conversation
|
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.
|
considerations.md
Outdated
| @@ -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. | |||
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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 ;).
There was a problem hiding this comment.
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.
|
agree that i) current wording could be improved; ii) current diff is an awkward middle-ground also, please no spelling regressions :-) |
|
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
force-pushed
the
considerations-rewrite
branch
from
b081e61
to
440aaba
Compare
|
very sorry about the spelling error! I've updated the verbiage to use jon's text. Please advise for future changes. |
|
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
|
|
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>
.
|
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.
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. |
|
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>
.
|
|
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
force-pushed
the
considerations-rewrite
branch
from
440aaba
to
f9f4b74
Compare
|
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>
.
|
|
As @wking mentioned (#613 (comment)), "All of the constituent components" seems misleading, because |
|
this SGTM except the phrase "all the constituent components" |
|
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>
.
|
Signed-off-by: Erik Hollensbe <github@hollensbe.org>
erikh
force-pushed
the
considerations-rewrite
branch
from
f9f4b74
to
6d8ec12
Compare
|
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! |
|
I agree we've kind of wandered into (and around) the weeds here, apologies about that. Latest incarnation LGTM in itself though. |
|
LGTM |
I felt the linking of the word
areandcontent-addressibleto foreign topics unrelated to the words needed to be changed to be more explicit. I hope you agree.Thanks!