Is the image-spec frozen?

[dlorenc]

Hey image-spec maintainers!

I'm filing this issue to request some clarify on your intentions for the image-spec going forward. There are a few different proposed changes (including one of my own) to the image-spec, and I've noticed a recurring discussion point and lingering questions around what types of changes are still acceptable to the image-spec.

This has come up in at least the following proposals:

• Add reference field #828
• Define the data field #826
• Add standard base image annotations #822

We started discussing this a month or so ago but decided to pause on that until the ongoing image-spec maintainer cleanup was finished. That hasn't finished completely, but it seems to have stabilized for now so I'd like to raise this discussion point again and try to get a clear answer to (at least) the following questions:

• Is the image-spec frozen?
  • My understanding (based on all the discussions I linked below) is that no, the image-spec is not frozen.
• Can changes be made to the v1 version of the image spec, or do all new changes need to go to a new version?
  • EDIT June 8th per @cyphar's response: Backwards compatible changes can still be made to a v1 of the spec. We should prefer backwards compatible changes that do not increase the major version where possible. At the discretion of the maintainers, large changes may still require bumping versions, even if they are technically backwards compatible. This would be surfaced at the design phase.
    I think some direction from the image-spec maintainers on these questions would help the community make progress on getting some form of reference type support in the specification, so I'd appreciate any input you may have! I'm of course interested in feedback from all members of the community, but I'm particularly interested in the opinions of the maintainers, who as of this time are: @brendandburns @jonjohnsonjr @jonboulle @jstarks @stevvooe @vbatts @cyphar.

Previous Discussions

To save people time, I've tried to include a list of previous discussions on this topic here. Let me know if I've missed any and I'll continue to merge in. I've tried to break this grouping down into two separate questions: "Are backwards compatible changes still allowed?" and "What is a backwards compatible change?"

Discussions around whether or not changes are still allowed

• @SteveLasker raised some questions about how spec changes can be made were raised on a proposal by @jonjohnsonjr to add support for a previously reserved field.
• The general topic of changes to the OCI overall was raised here at the TOB by @SteveLasker. From @vbatts:

  Incremental iteration on the specs, now that folks have production hardened uses cases is exactly the improvement we're looking for. Such that it isn't breaking change, and isn't "weaponizing" any aspect of the community discussion.

• @SteveLasker raised some concerns on Slack in a discussion on June 4th/5th here about the spec being frozen again: There's been comments "the spec is frozen"
  • @samuelkarp replied here:

  I don't see any comments there from any of the image-spec maintainers. I haven't yet seen anything that says one way or another that "the spec is frozen", that adding new optional fields would require a new major version of the spec, or that there is no desire to increment the spec beyond 1.0.

• @imjasonh asked for clarification on frozen-ness from the image-spec maintainers/OCI TOB on June 3rd on Slack here

Backwards Compatibility

• I (@dlorenc) took a stab at defining backwards compatible changes here.
• @SteveLasker raised some questions around backwards compatibility in this discussion.
  • @imjasonh responded in a comment here.

[imjasonh]

Thanks for filing this issue Dan!

I look forward to getting some clarity from the maintainers here, and hopefully some clear guidelines about what kinds of changes (if any) can be made to image-spec going forward. If it is frozen, that should be clearly stated somewhere to avoid confusion for users, and to turn potential contributors toward where/how changes can be made.

[cyphar]

The spec is not frozen, but we want to avoid backwards-incompatible changes. The only thing I don't really agree with is what you said here:

My understanding is that small, backwards compatible changes can still be made to a v1 of the spec, while larger, backwards compatible changes should be made against a new version. [emphasis added]

Any backward compatible change can be made without changing the major version number, and we want to avoid bumping the major version number as much as possible (to avoid issues similar to the python3/python2 split). Now, it's theoretically possible that some really big changes would be deemed to have been too much of a departure from the spec (while still technically being backwards compatible) but that's something that would come up during design discussions I expect.

(I really hope my use of the term "OCiv2" hasn't caused this misunderstanding -- the reason I used the term was to indicate that it was a second version of one aspect of the image-spec (the layer format and some other peripheral bits) not of the image-spec as a whole. In retrospect I should've used a different name for the effort.) I never intended "OCIv2 images" to literally mean a v2.0.0 of the specification -- though I now see how confusing that is.)

[dlorenc]

Any backward compatible change can be made without changing the major version number, and we want to avoid bumping the major version number as much as possible (to avoid issues similar to the python3/python2 split). Now, it's theoretically possible that some really big changes would be deemed to have been too much of a departure from the spec (while still technically being backwards compatible) but that's something that would come up during design discussions I expect.

Thank you! I'll try to incorporate that. Let me know if I captured it correctly!

[dlorenc]

Closing this one out! As discussed in the OCI dev call today (June 9th 2021), the spec is not frozen and it should be possible to make changes with a minor version bump.