fix: add image spec 1.1.0-rc2 option back to attach for expanded comp…

…atibility (oras-project#1224)

Signed-off-by: Jesse Butler <[email protected]>

cmd/oras/internal/option/spec.go

@@ -27,6 +27,10 @@ import (
 const (
 	ImageSpecV1_1 = "v1.1"
 	ImageSpecV1_0 = "v1.0"
+
+	// Explicit RC versions for expanded compatibility testing during spec development
+	ImageSpecV1_1_RC2 = "v1.1.0-rc2"
+	ImageSpecV1_1_RC4 = "v1.1.0-rc4"
 )
 
 const (
@@ -44,8 +48,10 @@ type ImageSpec struct {
 func (is *ImageSpec) Set(value string) error {
 	is.flag = value
 	switch value {
-	case ImageSpecV1_1:
+	case ImageSpecV1_1, ImageSpecV1_1_RC4:
 		is.PackVersion = oras.PackManifestVersion1_1_RC4
+	case ImageSpecV1_1_RC2:
+		is.PackVersion = oras.PackManifestVersion1_1_RC2
 	case ImageSpecV1_0:
 		is.PackVersion = oras.PackManifestVersion1_0
 	default:
@@ -67,6 +73,9 @@ func (is *ImageSpec) Options() string {
 	return strings.Join([]string{
 		ImageSpecV1_1,
 		ImageSpecV1_0,
+		// release candidates, to be removed when minor version is GA
+		ImageSpecV1_1_RC2,
+		ImageSpecV1_1_RC4,
 	}, ", ")
 }
 

cmd/oras/root/attach.go

@@ -37,6 +37,7 @@ import (
 type attachOptions struct {
 	option.Common
 	option.Packer
+	option.ImageSpec
 	option.Target
 
 	artifactType string
@@ -58,6 +59,9 @@ Example - Attach file 'hi.txt' with aritifact type 'doc/example' to manifest 'he
 Example - Push file "hi.txt" with the custom layer media type 'application/vnd.me.hi':
   oras attach --artifact-type doc/example localhost:5000/hello:v1 hi.txt:application/vnd.me.hi
 
+Example - Attach file "hi.txt" with specific image spec release candidate for testing during spec development (default v1.1):
+  oras attach --artifact-type doc/example --image-spec v1.1.0-rc2 localhost:5000/hello:v1 hi.txt 
+
 Example - Attach file "hi.txt" using a specific method for the Referrers API:
   oras attach --artifact-type doc/example --distribution-spec v1.1-referrers-api localhost:5000/hello:v1 hi.txt # via API
   oras attach --artifact-type doc/example --distribution-spec v1.1-referrers-tag localhost:5000/hello:v1 hi.txt # via tag scheme
@@ -149,8 +153,21 @@ func runAttach(ctx context.Context, opts attachOptions) error {
 		ManifestAnnotations: annotations[option.AnnotationManifest],
 		Layers:              descs,
 	}
+
 	pack := func() (ocispec.Descriptor, error) {
-		return oras.PackManifest(ctx, store, oras.PackManifestVersion1_1_RC4, opts.artifactType, packOpts)
+		switch opts.PackVersion {
+		case oras.PackManifestVersion1_0:
+			return ocispec.Descriptor{}, errors.New("image-spec v1.0 is not supported")
+		case oras.PackManifestVersion1_1_RC2:
+			return oras.Pack(ctx, store, opts.artifactType, packOpts.Layers, oras.PackOptions{
+				Subject:             packOpts.Subject,
+				ManifestAnnotations: packOpts.ManifestAnnotations,
+				PackImageManifest:   true,
+			})
+		default:
+			// default oras.PackManifestVersion1_1_RC4
+			return oras.PackManifest(ctx, store, opts.PackVersion, opts.artifactType, packOpts)
+		}
 	}
 
 	copy := func(root ocispec.Descriptor) error {

docs/proposals/compatibility-mode.md

@@ -16,12 +16,17 @@ This document elaborates on the major changes of ORAS CLI v1.1.0 proposed in [is
 
 Using the following flags in `oras push` and `oras attach` respectively with different variables to configure the manifest build and distribution behaviors. 
 
-- Using a flag `--image-spec` with `oras push`
+- Using a flag `--image-spec` with `oras push` and `oras attach` to configure image specification compatibility.
 - Using a flag `--distribution-spec` with `oras attach`, `oras cp`, and `oras manifest push` to configure compatibility with registry when pushing or copying an OCI image manifest. This flag is also applicable to `oras discover` for viewing and filtering the referrers.
 
 ### Build and push OCI image manifest using a flag `--image-spec`
 
-Use the flag `--image-spec <spec version>` in `oras push` to specify which version of the OCI Image-spec when building and pushing an OCI image manifest. It supports specifying the option `v1.0` or `v1.1` as the spec version. The option `v1.1` is the default behavior in `oras push` since ORAS CLI v1.1.0 so users don't need to manually specify this option.
+Use the flag `--image-spec <spec version>` in `oras push` and `oras attach` to specify which version of the OCI Image specification to use when building and pushing an OCI image manifest. Supported minor versions are `v1.1` (default) and `v1.0`. The v1.1 release candidate versions `v1.1.0-rc4` and `v1.1.0-rc2` are also supported.
+
+For `oras push`, `v1.0` or `v1.1` are supported spec version options. The `v1.0` option is not supported for `oras attach`. With ORAS CLI v1.1.0, `v1.1` is the default version for both commands so users don't need to manually specify this option.
+
+
+During OCI specification development, release candidate versions (e.g. `v1.1.0-rc4`) may also be included in the supported values for `--image-spec`. These are not stable, and likely to be removed when the version of the specification under test is GA. Note supported values may include deprecated RC versions to expand testing compatibility. 1.1.0 release candidate versions `v1.1.0-rc4` and `v1.1.0-rc2` are currently supported.
 
 If users want to build an OCI image manifest to a registry that compliant with OCI Spec v1.0, they can specify `--image-spec v1.0`. An OCI image manifest that conforms the OCI Image-spec v1.0.2 will be packed and uploaded. For example
 
@@ -62,4 +67,4 @@ oras attach localhost:5000/hello-world:v1 \
   sbom.json 
 ```
 
-Similarly, users can use `oras cp`, and `oras manifest push` with the flag `--distribution-spec` to configure compatibility with registry when pushing or copying an OCI image manifest, or use `oras discover` with the flag `--distribution-spec` for filtering the referrers in the view.
+Similarly, users can use `oras cp`, and `oras manifest push` with the flag `--distribution-spec` to configure compatibility with registry when pushing or copying an OCI image manifest, or use `oras discover` with the flag `--distribution-spec` for filtering the referrers in the view.