spec: split serialization into image and layer#206
spec: split serialization into image and layer#206jonboulle merged 1 commit intoopencontainers:masterfrom
Conversation
Signed-off-by: Stephen J Day <stephen.day@docker.com>
| This specification outlines the format of these filesystem changes and corresponding parameters and describes how to create and use them for use with a container runtime and execution tool. | ||
| This specification outlines the JSON format describing images for use with a container runtime and execution tool and its relationship to filesystem change sets, described in [Layers](layer.md). | ||
|
|
||
| ## Terminology |
There was a problem hiding this comment.
While we're splitting things up, do we want to move the terminology into a glossary.md?
There was a problem hiding this comment.
This is terminology that is specific to the context of this format. Pulling it up would imply a larger context, which is both confusing and incorrect.
There was a problem hiding this comment.
On Thu, Aug 25, 2016 at 07:44:39AM -0700, Stephen Day wrote:
Terminology
This is terminology that is specific to the context of this format.
“Layer” is more general than this format, since it's now covered in a
separate file (layer.md). “Tag” and “Repository” seem like they're
waiting for some future naming spec, and don't seem to be specific to
this file's serialization spec. If we want to keep a terminology
section for the serialization spec, we should at least restrict it to
serialization-specific terms.
There was a problem hiding this comment.
@wking Layer has very specific to this version of the specification and config. For the most part, the meaning of a layer at the higher-level is largely agnostic. At this level, their meaning is narrow and part of their relationship with the image configuration.
Read through it again.
Pulling this detail up doesn't help for contextual understanding or clarity.
Either way, this is massively outside the scope of this PR. You may submit another PR that removes, but I won't LGTM, as it creates confusion, ambiguity and indirection that makes meaning impossible to interpret.
There was a problem hiding this comment.
On Fri, Aug 26, 2016 at 03:22:13PM -0700, Stephen Day wrote:
Either way, this is massively outside the scope of this PR.
I have no problem punting to a follow-up PR. No need to slow this one
down with the terminology move being contentious.
|
Can we make this not depend on #212? Getting this split merged quickly without any major changes is important to ensure this PR doesn't block other stuff. |
|
@philips They could probably be one PR. If you want me to do a simple split, then PR the fixups listed above, that would be okay, but I really don't want this to be "half-done". |
|
@stevvooe Your call. It just depends on how much rebasing you want to do. I think moving the files around with zero changes is something we should do first and quickly which will fix any rebasing issues. |
|
@philips This PR, currently, is as close to zero-changes as possible, so let's merge this one, as is. I'll create issues from the other items here. Dropped WIP |
stevvooe
changed the title
|
LGTM |
|
lgtm (definitely in need of various improvements per the comments, but let's split this out and follow up) |
71650f2 (spec: split serialization into image and layer, 2016-08-24, opencontainers#206) pulled layer.md out of serialization.md, but did not update these links. While touching the paragraph, reformat to one sentence per line as requested by the "Markdown style" section in the README. Signed-off-by: W. Trevor King <wking@tremily.us>
71650f2 (spec: split serialization into image and layer, 2016-08-24, opencontainers#206) pulled layer.md out of serialization.md, but did not update these links. I preferred the more generic "filesystem serialization" wording from before, because while README readers should understand that we're serializing the filesystem, they don't need to care about *how* the filesystem is serialized. Folks who do care about the serialization should be reading layer.md. But Brandon and Jonathan both liked the "filesystem layers" wording [1], so that's what we have here. While touching the paragraph, reformat to one sentence per line as requested by the "Markdown style" section in the README. [1]: https://github.com/opencontainers/image-spec/pull/285/files/05370b480e45a790dd86a8e3104e78fe802a786c#r78313284 Signed-off-by: W. Trevor King <wking@tremily.us>
4 participants
Signed-off-by: Stephen J Day stephen.day@docker.com
Open after merging this:
Closes #128,
Depends on #212