update experimental flag image-spec

[qweeah]

OCI Artifact Manifest no longer exists in https://github.com/opencontainers/image-spec/tree/v1.1.0-rc4, oras CLI should remove the v1.1-artifact as an option of --image-spec.

For oras push:

• Remove v1.0-image and v1.1-artifact
• Add new options
  • v1.0: build manifest compliant to image spec v1.0, which doesn't allow --config and --artifact-type to be used at the same time
  • v1.1: build manifest compliant to image spec v1.1.0-rc4

For oras attach:

• Remove --image-spec: oras attach only generate manifests with both subject and artifactType presented

[Wwwsylvia]

Should we allow users to specify the image type of v1.1.0-rc2, in case the server does not support the image type of v1.1.0-rc4 which contains an artifactType field?

[shizhMSFT]

If it is oras push, then v1.1.0-rc2 is equivalent to v1.0.2 or simply v1.0.

[shizhMSFT]

Since it impacts oras push, I suggest keeping the --image-spec flag and change the values to be {v1.0, v1.1} where v1.0 is the default value to avoid breaking changes in minor versions of oras.

For oras attach, --image-spec can be removed or remained. If the flag remains, the only acceptable value is v1.1.

[qweeah]

For oras attach, --image-spec can be removed or remained. If the flag remains, the only acceptable value is v1.1.

Sorry I am confused, why removing --image-spec is not a breaking change for oras attach? oras v1.0.0 will also tuck user-provided artifact type into config.mediaType for oras attach. Is it because attach is a preview command?

[qweeah]

In my opinion, oras push should by default generate manifests with artifactType and empty descriptor presented. The default behavior of oras push --artifact-type xxx in v1.0.0 generates defected manifests as is pointed out in #1011 (comment).

For oras attach, we should remove this flag entirely if the acceptable value is different from oras push. There is no benefit to keep this flag if it only has one acceptable value.

[sajayantony]

Removing an experimental feature or changes to these should be considered as non-breaking. My understanding is that the image-spec flag for 1.1 was definitely preview or experimental.

[qweeah]

Removing an experimental feature or changes to these should be considered as non-breaking. My understanding is that the image-spec flag for 1.1 was definitely preview or experimental.

1. For oras v1.0.0, if user run below command, the test.artifact.type will be put into config.mediaType:

oras push localhost:5000/test:artifact --artifact-type test.artifact.type

  ...
  "config": {
    "mediaType": "test.artifact.type",
    "digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
    "size": 2
  },
  ...

2. As is suggested by the Guidelines for Artifact Usage in OCI image spec 1.1.0-rc4, the preferred manifest produced by below command should use artifactType and empty config descriptor:

oras push localhost:5000/test:artifact --artifact-type test.artifact.type

  ...
  "artifactType": "test.artifact.type",
  "config": {
    "mediaType": "application/vnd.oci.empty.v1+json",
    "digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
    "size": 2
  },
  ...

@sajayantony Please notice that --image-spec is not involved in the command call. So the question turns into: to align with OCI image spec 1.1.0-rc4, we need change schema of generated manifest if --artifact-type flag is provided in oras push, is it a breaking change and can we do that?

Unfortunately we didn't mark --artifact-type as preview or experimental in ORAS v1.0.0 release & that's why @shizhMSFT think the schema change is breaking.