image-layout: Drop manifest ref example description

[wking]

A ref → descriptor example caption gained “blobs the manifest references” wording with 2f24791, #136, but I don't see a direct relationship between descriptors and those deeper-ancestor blobs. I think we either want to revert the changes 2f24791 made to this line or drop the line. In this commit I drop the line, because the other points covered by the sentence are already covered in other descriptor docs. And it's pretty clear just from the example command and output that this is showing the content of a ref pointing at a manifest list.

Fixes #427.

[jonboulle]

lgtm

[stevvooe]

This example is completely bare of context if you drop this line. I don't think this is clear at all for new readers of this specification. The content needs to be reinforced.

[wking]

On Tue, Dec 20, 2016 at 11:39:19AM -0800, Stephen Day wrote: This example is completely bare of context…

There's a whole bunch of context in the “Refs” section which contains this “Example Ref” subsection.

I don't think this is clear at all for new readers of this specification. The content needs to be reinforced.

Which content needs reinforcing? The line I remove says: a. “This illustrates the expected contents of a given ref” (I think this is covered by the “Example Ref” header and ‘cat ./refs/v1.0’ command). b. “the manifest list it points to” (I think this is covered by the ‘mediaType": "application/vnd.oci.image.manifest.list.v1+json"’ output). c. “and the blobs the manifest references” (I think this is wrong, #427). Are you pushing back on my reasoning for any of those? For all of them?

[stevvooe]

@wking This block of json just needs some human language introductory text. Just say what it does, reinforcing the language above.

[wking]

On Tue, Dec 20, 2016 at 07:17:11PM -0800, Stephen Day wrote: @wking This block of json just needs some human language introductory text. Just say what it does, reinforcing the language above.

*shrug* I added something closer to what we had originally with 909ecab → 1143e26.

[jonboulle]

Ehh, this language doesn't add anything, and the document remains inconsistent: "Example Blobs" has no intro text, and "Example Layout" just has the vague/unhelpful "This is an example image layout:". Can we just strike all of them?

[wking]

On Tue, Dec 20, 2016 at 11:59:14PM -0800, Jonathan Boulle wrote: Can we just strike all of them?

That's my preference :). But I don't really care. Let me know what to do once you've sorted it out with @stevvooe ;).

[RobDolinMS]

@stevvooe, @wking, @jonboulle - can you get to consensus on this?

[stevvooe]

Looking back at this, I think this change is fine, but I'd like to see it followed up by PR that introduces the examples in a way that clarifies.

LGTM with follow up.

[wking]

On Wed, Jan 18, 2017 at 03:48:46PM -0800, Stephen Day wrote: Looking back at this, I think this change is fine…

I'm ok with all of the proposals that let us drop the current “blobs the manifest references”, although I'd be happier if we could drop 1143e26. I don't really care though (which is why I pushed 1143e26 when you asked for it ;). As long as you and @jonboulle (who also sounded like he wasn't particularly excited about 1143e26 [1]) are both happy with things as they stand, then lets get this thing landed. If you need any further tweaks (short of restoring “blobs the manifest references”), just tell me what to do.

… but I'd like to see it followed up by PR that introduces the examples in a way that clarifies.

If other folks have different wording they want to add to clarify any examples, that sounds fine to me. I don't have any ideas myself for those follow-up PRs though. [1]: #507 (comment)

[philips]

LGTM

I don't understand what @stevvooe wants in the followup so I will let him make the call on merging.

[vbatts]

LGTM