Add a warning about portability to artifact.md #1004
Conversation
The artifact manifest is not backward compatible with OCI 1.0 registries, so it will not worth with older clients and registries that have not been updated to handle artifact manifests. Signed-off-by: Jon Johnson <[email protected]>
jonjohnsonjr
requested review from
jonboulle,
stevvooe,
sudo-bmitch,
sajayantony,
vbatts and
cyphar
as code owners
| @@ -1,5 +1,7 @@ | |||
| # OCI Artifact Manifest Specification | |||
|
|
|||
| Implementations concerned with portability SHOULD NOT use the Artifact Manifest. | |||
There was a problem hiding this comment.
"portability" would need to be explicitly defined for discussing this PR further
There was a problem hiding this comment.
Good point. I have in mind "portability" between 1.0 and 1.1 registries, so perhaps "backwards compatibility with OCI 1.0" is a better phrase? We could link to a section of image manifest describing its use for packaging non-container-image content.
There was a problem hiding this comment.
I agree with that messaging change. It should be OK for an implementation to decide its own destiny if they've already adopted OCI 1.0 image spec and they want to phase it out at a major version change, their compatibility story is their own business.
The same applies for all future versions, and in fact, all future image-spec types!
How about this in spec.md or in all manifest types?
Implementations that support creating alternative manifest types SHOULD NOT use the registry to determine the manifest type created.
@sudo-bmitch does that address your objection about non-deterministic behavior? I should be able to look at a tool like [email protected] and its command line arguments and know what it will produce. Tools that are clever and try to automatically fall back will end up surprising users.
And understanding @sudo-bmitch's concern, I'll also close this issue:
I don't think it's a good idea to specify fallback behavior any longer.
There was a problem hiding this comment.
@sudo-bmitch re:
I'm not sure that a warning is enough if OCI is tasked with portability and compatibility. I'm leaning towards saying that any tooling that produces the artifact manifest, without an experimental flag or some other end-user control
Such as a user intentionally upgrading to a new major version, i.e.: OCI client Foobarctl says "with major version v3, we default to artifact now and will fail on pushing to an OCI 1.0 registry. Opt out of this behavior by passing --oci-spec=v1.0"?
There was a problem hiding this comment.
After the conversations yesterday, some kind of verbiage could be useful. Let's steer to something hand-wavy, but maybe
**Introduced**: v1.1.0
_Notice_: Introduction of new manifest types requires client and server features. As implementations adopt a new manifest type it may cause portability challenges with legacy tools or services.
There was a problem hiding this comment.
I like the wording that @vbatts provides, with the addition that I'd like to include a "SHOULD NOT use" suggestion in there to stress our desire for portability.
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
|
I'm not sure that a warning is enough if OCI is tasked with portability and compatibility. I'm leaning towards saying that any tooling that produces the artifact manifest, without an experimental flag or some other end-user control, and before end-users have had time to upgrade, isn't following the OCI spec. We can delist those projects from OCI repos and insist they stop using the trademark in their own product description. That lets projects use the new features as long as they accept the sole responsibility for any issues they cause. And we can give a date that end-users need to upgrade their tooling to avoid potential issues. |
|
@sudo-bmitch I don't think this some flag like this is quite the workflow. This is exactly why SemVer was poor for this project, and should've used featureflags. (where is @wking for the historical references 😆 ) |
|
@vbatts a capabilities API only lets you know the capabilities of the registry you are directly connected to, and not the capabilities of all the tools that will consume the content downstream (in other words, it covers producer-transport, and not transport-consumer). I'm sure there's a good use for a new API, but most of the requests for this are concerning. As an example, if we introduced a capabilities API the same time OCI defined the new manifests for image and index, the example use cases would have changed from the docker to the OCI manifest types when the registry was upgraded, rather than when the various runtimes were all upgraded. I still encounter docker 1.13 installs in the wild that cannot run OCI manifests, those downstream consumers are upgraded on independent schedules. Given the amount of testing and collaboration that would be needed for an API, if that's brought into OCI, I'd want to do it with a working group. |
|
I think what bothers me about this is that OCI here is being prescriptive about the destiny of other tools using the spec. I think it's OK for Docker to say "We are going to move to a new manifest format by default, and that Docker 1.13 and below will not support it." The PR as written suggests to me that implementers SHOULD NOT do that. That's terrible because implementations following the spec to the letter, including all SHOULDs, are feature frozen to whatever version of OCI existed in their first release, full stop. (Or arguably, v1.0.) @sudo-bmitch, I've suggested a language tweak that tries to get to the heart of your issue around Artifact: that tools are doing "feature discovery" in effect against a registry to choose among a menu of options. I'm curious if you'd be more in favor of recommending against that, because that's the sort of "automatic" upgrade behavior you don't want clients to use. |
|
correct @AaronFriel . @sudo-bmitch your concern here is conflating the role of a spec. It is by offering a capability endpoint that is attempting to ease/enable tools. If you switch around this priority, then we block ourselves. |
|
I do feel like a broken record about history, but a capability endpoint has been desired by the community for a "long time", and it was in the old Docker Inc's benefit to keep the grip on that. It was and still is difficult for the community. Maybe that ship has sailed, but if we can not work towards that ideal now, then it will never get easier. |
|
@jonjohnsonjr Guess we can close this since #999 has been merged and we have removed the concerns with Artifact manifest. |
The artifact manifest is not backward compatible with OCI 1.0 registries, so it will not worth with older clients and registries that have not been updated to handle artifact manifests.
Signed-off-by: Jon Johnson [email protected]