Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

image-layout: clarification of oci-layout #434

Merged
merged 1 commit into from
Dec 7, 2016
Merged

image-layout: clarification of oci-layout #434

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 5 additions & 2 deletions image-layout.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,9 +18,12 @@ The image layout MUST contain two top level directories:

Both `blobs` and `refs` MAY be empty.

The image layout MUST also contain a file that is used to identify the layout version:
The image layout MUST also contain an `oci-layout` file:

- `oci-layout` MUST contain a JSON object with a version field `{"imageLayoutVersion": "1.0.0"}` and MAY include additional fields.
- It MUST be a JSON object
- It MUST contain an `imageLayoutVersion` field
- The `imageLayoutVersion` value will align with the OCI Image Specification version at the time changes to the layout are made, and will pin a given version until changes to the layout are required
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You've gone with “OCI Image Specification”, but the title for this spec is “Open Container Initiative Image Format Specification”. I'm fine changing “Open Container Initiative” → “OCI”, but don't think we should be dropping “Format” here unless we also drop it from the spec title. I don't mind which way we go, but I think we should stay consistent.

I also still think we should either semantically version imageLayoutVersion or point out that this is not semantically versioned.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I went with this because the image-layout.md doc is titled "OCI Image Layout Specification".

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This file is about the OCI Image Layout Specification, and if imageLayoutVersion semantically versions that, I'm happy. However, it seems like the “pin” language was adding a relationship to the project-wide OCI Image Format Specification version.

To distinguish the two cases, pretend we had already cut 1.0.0, and say there is a backwards-compatible change to the image layout (e.g. you add an optional index, #438) and a backwards-incompatible change to something else (e.g. we drop support for .wh.*, #24). The backwards-incompatible change means the project as a whole goes to 2.0.0. With the independently-SemVer'ed approach, the backwards-compatible image-layout change moves imageLayoutVersion to 1.1.0. With the pinned-to-the-project-version approach, imageLayoutVersion moves to 2.0.0. Which of those is your intended result?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Dare I say that some kind of specific-feature based compatibility would most closely be like the bittorrent BEP process, where specific features or enhancements are assigned an indicator (i.e. BEP0001). Rather than rev'ing a version that requires compliance of all features, an implementation can specify the specific features they accommodate.
Your pretending may certainly find benefits and drawbacks to both approaches. Neither is perfect. What is your intended result?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm fine with tagged features (opencontainers/runtime-spec#15), but the OCI specs seemed to be leaning towards linearized versioning. With linearized versioning, my preferred result is 1.1.0 (because it avoids confusing implementers and layout authors who are interested in image-layout but not with the other spec features). I don't expect much feature fragmentation in image-layout, so shifting to tagged features would be a small gain. However, just because I don't foresee fragmentation doesn't mean we won't have it ;). So I'm also fine switching to tagged features proactively.

- It MAY include additional fields

This is an example image layout:

Expand Down