fix: add image spec option back to attach for expanded compatibility (o…

…ras-project#1224)

cmd/oras/internal/option/spec.go

@@ -27,6 +27,9 @@ import (
 const (
 	ImageSpecV1_1 = "v1.1"
 	ImageSpecV1_0 = "v1.0"
+
+	// Release candidate versions are for expanded compatibility during spec development
+	ImageSpecV1_1_RC2 = "v1.1.0-rc2"
 )
 
 const (
@@ -46,6 +49,8 @@ func (is *ImageSpec) Set(value string) error {
 	switch value {
 	case ImageSpecV1_1:
 		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:

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,10 @@ 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 version when building the manifest (default v1.1):
+  oras attach --artifact-type doc/example --image-spec v1.1.0 localhost:5000/hello:v1 hi.txt      # default
+  oras attach --artifact-type doc/example --image-spec v1.1.0-rc2 localhost:5000/hello:v1 hi.txt  # release candidate testing
+
 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 +154,9 @@ 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)
+		return oras.PackManifest(ctx, store, opts.PackVersion, opts.artifactType, packOpts)
 	}
 
 	copy := func(root ocispec.Descriptor) error {

docs/proposals/compatibility-mode.md

@@ -16,12 +16,14 @@ 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-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.
+
+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.
 
 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 +64,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.