spec: Standardize language for actions ((un)packing, etc.)

[wking]

To set ourselves up for more consistent discussions. This also unifies the old “Overview” and “Understanding the Specification” sections, which had a fair amount of overlap.

Fixes #467.

[xiekeyang]

a blob -> series of tar-based blobs ?

[wking]

a blob -> series of tar-based blobs ?

I'm using "(un)packing" more generically than that. In the examples below, I also talk about (un)packing manifest(-list)s, and in that context it is "(de)serializing into JSON, potentially just in memory".

[xiekeyang]

This section is talking about packing image. If the title had better to be packing image?

Publishing might be relative to distribution.

[wking]

This section is talking about packing image. If the title had better to be packing image?

Done with d50a14b → 92980ec.

[xiekeyang]

Some suggestion:

1. desc of translate action seems a little unclear. It might need more explication (as enum the blob format).

2. As index PR is going to be landed, if we need consider to add delete action for specific manifest object included in index? This might be done in follow PR.

3. Actions might need include download or fetch. The fetch tool might be landed in OCI or external project. But I think it should be implied as one kind of action in image-spec.

[wking]

On Tue, Feb 07, 2017 at 01:52:49AM -0800, xiekeyang wrote: 1. desc of `translate` action seems a little unclear. It might need more explication (as enum the blob format).

I'm not clear on what you're asking for here. The ‘translate’ definition is supposed to be generic, to allow for translation between formats which are unknown to the OCI spec (e.g. a user's custom runtime config format).

2. As index PR is going to be landed, if we need `delete` action for manifest object in index? This might be done in follow PR.

Sounds good. I've pushed 92980ec → cb65bdf adding ‘put’, ‘get’, and ‘delete’ covering both CAS blobs and mutable references. The wording here will need some minor tweaking around #438, #533, and #546, so there will be rebasing as these related PRs land.

3. Actions might need include `download` or `fetch`. The fetch tool might be landed in OCI or external project. But I think it should be implied as one kind of `action` in image-spec.

I'd rather not use ‘download’, because it implies interaction with a remote system. What's important for the image workflow is put/get/delete vs. generic CAS and reference engines, which may or may not be remote. In production systems, you might put a blob in your local CAS cache and also put it in a remote CAS registry; and ‘put’ feels better there than “upload a blob to your local CAS cache”.

[RobDolinMS]

Is this intended for milestone==v1.0.0 or milestone==post-v1.0.0 ?

[wking]

On Thu, Apr 13, 2017 at 02:37:57PM -0700, Rob Dolin (MSFT) wrote: Is this intended for milestone==v1.0.0 or milestone==post-v1.0.0 ?

I think it helps, but probably shouldn't be a blocker for 1.0. I'd filed it because #467 was mentioned as a blocker for some image-tools stuff [1]. But opencontainers/image-tools#103 ended up getting merged without blocking on #467, which takes some of the pressure off here. [1]: opencontainers/image-tools#96 (comment)

[vbatts]

I think this PR is not clarifying the semantics around image-related actions. I'm inclined to close this and we can revisit this after 1.0

[wking]

On Thu, May 25, 2017 at 01:20:52PM -0700, v1.0.0.batts wrote: I think this PR is not clarifying the semantics around image-related actions.

Without this PR, the spec has nothing to say about image (un)packing (although it currently does say something about layer (un)packing). And I'm happy to field suggestions if folks have any quibbles with my current content. But I'm also ok with leaving this closed and letting @stevvooe file his own PR closing #467 [1], if that's easier for maintainers. [1]: #467 (comment)