doc: add feature marks to cmd description and log (oras-project#865)

Signed-off-by: Billy Zha <jinzha1@microsoft.com>

cmd/oras/blob/cmd.go

@@ -22,7 +22,7 @@ import (
 func Cmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "blob [command]",
-		Short: "[Preview] Blob operations",
+		Short: "Blob operations",
 	}
 
 	cmd.AddCommand(

cmd/oras/blob/delete.go

@@ -40,10 +40,8 @@ func deleteCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:     "delete [flags] <name>@<digest>",
 		Aliases: []string{"remove", "rm"},
-		Short:   "[Preview] Delete a blob from a remote registry",
-		Long: `[Preview] Delete a blob from a remote registry
-
-** This command is in preview and under development. **
+		Short:   "Delete a blob from a remote registry",
+		Long: `Delete a blob from a remote registry
 
 Example - Delete a blob:
   oras blob delete localhost:5000/hello@sha256:9a201d228ebd966211f7d1131be19f152be428bd373a92071c71d8deaf83b3e5

cmd/oras/blob/fetch.go

@@ -44,10 +44,8 @@ func fetchCmd() *cobra.Command {
 	var opts fetchBlobOptions
 	cmd := &cobra.Command{
 		Use:   "fetch [flags] {--output <file> | --descriptor} <name>@<digest>",
-		Short: "[Preview] Fetch a blob from a remote registry",
-		Long: `[Preview] Fetch a blob from a remote registry
-
-** This command is in preview and under development. **
+		Short: "Fetch a blob from a remote registry",
+		Long: `Fetch a blob from a remote registry
 
 Example - Fetch a blob from registry and save it to a local file:
   oras blob fetch --output blob.tar.gz localhost:5000/hello@sha256:9a201d228ebd966211f7d1131be19f152be428bd373a92071c71d8deaf83b3e5

cmd/oras/blob/push.go

@@ -42,10 +42,8 @@ func pushCmd() *cobra.Command {
 	var opts pushBlobOptions
 	cmd := &cobra.Command{
 		Use:   "push [flags] <name>[@digest] <file>",
-		Short: "[Preview] Push a blob to a remote registry",
-		Long: `[Preview] Push a blob to a remote registry
-
-** This command is in preview and under development. **
+		Short: "Push a blob to a remote registry",
+		Long: `Push a blob to a remote registry
 
 Example - Push blob 'hi.txt' to a registry:
   oras blob push localhost:5000/hello hi.txt

cmd/oras/cp.go

@@ -45,10 +45,8 @@ func copyCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:     "cp [flags] <from>{:<tag>|@<digest>} <to>[:<tag>[,<tag>][...]]",
 		Aliases: []string{"copy"},
-		Short:   "[Preview] Copy artifacts from one target to another",
-		Long: `[Preview] Copy artifacts from one target to another
-
-** This command is in preview and under development. **
+		Short:   "Copy artifacts from one target to another",
+		Long: `Copy artifacts from one target to another
 
 Example - Copy an artifact between registries:
   oras cp localhost:5000/net-monitor:v1 localhost:6000/net-monitor-copy:v1
@@ -90,7 +88,7 @@ Example - Copy an artifact with multiple tags with concurrency tuned:
 			return runCopy(opts)
 		},
 	}
-	cmd.Flags().BoolVarP(&opts.recursive, "recursive", "r", false, "recursively copy the artifact and its referrer artifacts")
+	cmd.Flags().BoolVarP(&opts.recursive, "recursive", "r", false, "[Preview] recursively copy the artifact and its referrer artifacts")
 	cmd.Flags().IntVarP(&opts.concurrency, "concurrency", "", 3, "concurrency level")
 	opts.EnableDistributionSpecFlag()
 	option.ApplyFlags(&opts, cmd.Flags())

cmd/oras/internal/option/spec.go

@@ -46,7 +46,7 @@ func (opts *ImageSpec) Parse() error {
 
 // ApplyFlags applies flags to a command flag set.
 func (opts *ImageSpec) ApplyFlags(fs *pflag.FlagSet) {
-	fs.StringVar(&opts.specFlag, "image-spec", "v1.1-image", "specify manifest type for building artifact. options: v1.1-image, v1.1-artifact")
+	fs.StringVar(&opts.specFlag, "image-spec", "v1.1-image", "[Experimental] specify manifest type for building artifact. options: v1.1-image, v1.1-artifact")
 }
 
 // distributionSpec option struct.
@@ -79,5 +79,5 @@ func (opts *distributionSpec) Parse() error {
 // ApplyFlagsWithPrefix applies flags to a command flag set with a prefix string.
 func (opts *distributionSpec) ApplyFlagsWithPrefix(fs *pflag.FlagSet, prefix, description string) {
 	flagPrefix, notePrefix := applyPrefix(prefix, description)
-	fs.StringVar(&opts.specFlag, flagPrefix+"distribution-spec", "", "set OCI distribution spec version and API option for "+notePrefix+"target. options: v1.1-referrers-api, v1.1-referrers-tag")
+	fs.StringVar(&opts.specFlag, flagPrefix+"distribution-spec", "", "[Preview] set OCI distribution spec version and API option for "+notePrefix+"target. options: v1.1-referrers-api, v1.1-referrers-tag")
 }

cmd/oras/internal/option/target.go

@@ -72,7 +72,7 @@ func (opts *Target) AnnotatedReference() string {
 // the full form is not implemented until a new type comes in.
 func (opts *Target) applyFlagsWithPrefix(fs *pflag.FlagSet, prefix, description string) {
 	flagPrefix, notePrefix := applyPrefix(prefix, description)
-	fs.BoolVarP(&opts.isOCILayout, flagPrefix+"oci-layout", "", false, "Set "+notePrefix+"target as an OCI image layout.")
+	fs.BoolVarP(&opts.isOCILayout, flagPrefix+"oci-layout", "", false, "set "+notePrefix+"target as an OCI image layout")
 }
 
 // ApplyFlagsWithPrefix applies flags to a command flag set with a prefix string.

cmd/oras/main.go

@@ -21,7 +21,7 @@ import (
 	"github.com/spf13/cobra"
 	"oras.land/oras/cmd/oras/blob"
 	"oras.land/oras/cmd/oras/manifest"
-	"oras.land/oras/cmd/oras/repository"
+	repository "oras.land/oras/cmd/oras/repo"
 	"oras.land/oras/cmd/oras/tag"
 )
 

cmd/oras/manifest/cmd.go

@@ -22,7 +22,7 @@ import (
 func Cmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "manifest [command]",
-		Short: "[Preview] Manifest operations",
+		Short: "Manifest operations",
 	}
 
 	cmd.AddCommand(

cmd/oras/manifest/delete.go

@@ -41,10 +41,8 @@ func deleteCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:     "delete [flags] <name>{:<tag>|@<digest>}",
 		Aliases: []string{"remove", "rm"},
-		Short:   "[Preview] Delete a manifest from remote registry",
-		Long: `[Preview] Delete a manifest from remote registry
-
-** This command is in preview and under development. **
+		Short:   "Delete a manifest from remote registry",
+		Long: `Delete a manifest from remote registry
 
 Example - Delete a manifest tagged with 'v1' from repository 'localhost:5000/hello':
   oras manifest delete localhost:5000/hello:v1

cmd/oras/manifest/fetch.go

@@ -44,10 +44,8 @@ func fetchCmd() *cobra.Command {
 	var opts fetchOptions
 	cmd := &cobra.Command{
 		Use:   "fetch [flags] <name>{:<tag>|@<digest>}",
-		Short: "[Preview] Fetch manifest of the target artifact",
-		Long: `[Preview] Fetch manifest of the target artifact
-
-** This command is in preview and under development. **
+		Short: "Fetch manifest of the target artifact",
+		Long: `Fetch manifest of the target artifact
 
 Example - Fetch raw manifest from a registry:
   oras manifest fetch localhost:5000/hello:v1

cmd/oras/manifest/fetch_config.go

@@ -46,10 +46,8 @@ func fetchConfigCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:     "fetch-config [flags] <name>{:<tag>|@<digest>}",
 		Aliases: []string{"get-config"},
-		Short:   "[Preview] Fetch the config of a manifest from a remote registry",
-		Long: `[Preview] Fetch the config of a manifest from a remote registry
-
-** This command is in preview and under development. **
+		Short:   "Fetch the config of a manifest from a remote registry",
+		Long: `Fetch the config of a manifest from a remote registry
 
 Example - Fetch the config:
   oras manifest fetch-config localhost:5000/hello:v1

cmd/oras/manifest/push.go

@@ -49,10 +49,8 @@ func pushCmd() *cobra.Command {
 	var opts pushOptions
 	cmd := &cobra.Command{
 		Use:   "push [flags] <name>[:<tag>[,<tag>][...]|@<digest>] <file>",
-		Short: "[Preview] Push a manifest to remote registry",
-		Long: `[Preview] Push a manifest to remote registry
-
-** This command is in preview and under development. **
+		Short: "Push a manifest to remote registry",
+		Long: `Push a manifest to remote registry
 
 Example - Push a manifest to repository 'localhost:5000/hello' and tag with 'v1':
   oras manifest push localhost:5000/hello:v1 manifest.json

cmd/oras/pull.go

@@ -93,7 +93,7 @@ Example - Pull artifact files from an OCI layout archive 'layout.tar':
 
 	cmd.Flags().BoolVarP(&opts.KeepOldFiles, "keep-old-files", "k", false, "do not replace existing files when pulling, treat them as errors")
 	cmd.Flags().BoolVarP(&opts.PathTraversal, "allow-path-traversal", "T", false, "allow storing files out of the output directory")
-	cmd.Flags().BoolVarP(&opts.IncludeSubject, "include-subject", "", false, "recursively pull the subject of artifacts")
+	cmd.Flags().BoolVarP(&opts.IncludeSubject, "include-subject", "", false, "[Preview] recursively pull the subject of artifacts")
 	cmd.Flags().StringVarP(&opts.Output, "output", "o", ".", "output directory")
 	cmd.Flags().StringVarP(&opts.ManifestConfigRef, "config", "", "", "output manifest config file")
 	cmd.Flags().IntVarP(&opts.concurrency, "concurrency", "", 3, "concurrency level")

cmd/oras/repository/cmd.go → cmd/oras/repo/cmd.go

@@ -20,7 +20,7 @@ import (
 func Cmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:     "repo [command]",
-		Short:   "[Preview] Repository operations",
+		Short:   "Repository operations",
 		Aliases: []string{"repository"},
 	}
 

cmd/oras/repository/ls.go → cmd/oras/repo/ls.go

@@ -36,10 +36,8 @@ func listCmd() *cobra.Command {
 	var opts repositoryOptions
 	cmd := &cobra.Command{
 		Use:   "ls [flags] <registry>",
-		Short: "[Preview] List the repositories under the registry",
-		Long: `[Preview] List the repositories under the registry
-
-** This command is in preview and under development. **
+		Short: "List the repositories under the registry",
+		Long: `List the repositories under the registry
 
 Example - List the repositories under the registry:
   oras repo ls localhost:5000

cmd/oras/repository/tags.go → cmd/oras/repo/tags.go

@@ -36,10 +36,8 @@ func showTagsCmd() *cobra.Command {
 	var opts showTagsOptions
 	cmd := &cobra.Command{
 		Use:   "tags [flags] <name>",
-		Short: "[Preview] Show tags of the target repository",
-		Long: `[Preview] Show tags of the target repository
-
-** This command is in preview and under development. **
+		Short: "Show tags of the target repository",
+		Long: `Show tags of the target repository
 
 Example - Show tags of the target repository:
   oras repo tags localhost:5000/hello
@@ -73,7 +71,7 @@ Example - Show tags associated with a digest:
 		},
 	}
 	cmd.Flags().StringVar(&opts.last, "last", "", "start after the tag specified by `last`")
-	cmd.Flags().BoolVar(&opts.excludeDigestTag, "exclude-digest-tags", false, "exclude all digest-like tags such as 'sha256-aaaa...'")
+	cmd.Flags().BoolVar(&opts.excludeDigestTag, "exclude-digest-tags", false, "[Preview] exclude all digest-like tags such as 'sha256-aaaa...'")
 	option.ApplyFlags(&opts, cmd.Flags())
 	return cmd
 }
@@ -96,7 +94,7 @@ func showTags(opts showTagsOptions) error {
 			}
 			filter = desc.Digest.String()
 		}
-		logger.Infof("[Preview] Querying tags associated to %s, it may take a while.\n", filter)
+		logger.Infof("[Experimental] querying tags associated to %s, it may take a while...\n", filter)
 	}
 	return finder.Tags(ctx, opts.last, func(tags []string) error {
 		for _, tag := range tags {

cmd/oras/tag/tag.go

@@ -36,10 +36,8 @@ func TagCmd() *cobra.Command {
 	var opts tagOptions
 	cmd := &cobra.Command{
 		Use:   "tag [flags] <name>{:<tag>|@<digest>} <new_tag> [...]",
-		Short: "[Preview] Tag a manifest in the remote registry",
-		Long: `[Preview] Tag a manifest in the remote registry
-
-** This command is in preview and under development. **
+		Short: "Tag a manifest in the remote registry",
+		Long: `Tag a manifest in the remote registry
 
 Example - Tag the manifest 'v1.0.1' in 'localhost:5000/hello' to 'v1.0.2':
   oras tag localhost:5000/hello:v1.0.1 v1.0.2

test/e2e/internal/testdata/feature/feature.go

@@ -0,0 +1,30 @@
+/*
+Copyright The ORAS Authors.
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package feature
+
+var (
+	Preview = struct {
+		Mark        string
+		Description string
+	}{
+		Mark:        "[Preview]",
+		Description: "** This command is in preview and under development. **",
+	}
+
+	Experimental = struct{ Mark string }{
+		Mark: "[Experimental]",
+	}
+)

test/e2e/suite/command/attach.go

@@ -19,10 +19,14 @@ import (
 	"encoding/json"
 	"fmt"
 	"path/filepath"
+	"regexp"
 
 	. "github.com/onsi/ginkgo/v2"
+	"github.com/onsi/gomega"
 	. "github.com/onsi/gomega"
+	"github.com/onsi/gomega/gbytes"
 	ocispec "github.com/opencontainers/image-spec/specs-go/v1"
+	"oras.land/oras/test/e2e/internal/testdata/feature"
 	"oras.land/oras/test/e2e/internal/testdata/foobar"
 	. "oras.land/oras/test/e2e/internal/utils"
 	"oras.land/oras/test/e2e/internal/utils/match"
@@ -37,7 +41,9 @@ var _ = Describe("ORAS beginners:", func() {
 		RunAndShowPreviewInHelp([]string{"attach"})
 
 		It("should show preview and help doc", func() {
-			ORAS("attach", "--help").MatchKeyWords("[Preview] Attach", PreviewDesc, ExampleDesc).Exec()
+			out := ORAS("attach", "--help").MatchKeyWords(feature.Preview.Mark+" Attach", feature.Preview.Description, ExampleDesc).Exec()
+			gomega.Expect(out).Should(gbytes.Say("--distribution-spec string\\s+%s", regexp.QuoteMeta(feature.Preview.Mark)))
+			gomega.Expect(out).Should(gbytes.Say("--image-spec string\\s+%s", regexp.QuoteMeta(feature.Experimental.Mark)))
 		})
 
 		It("should fail when no subject reference provided", func() {

test/e2e/suite/command/blob.go

@@ -36,10 +36,7 @@ const (
 var _ = Describe("ORAS beginners:", func() {
 	repoFmt := fmt.Sprintf("command/blob/%%s/%d/%%s", GinkgoRandomSeed())
 	When("running blob command", func() {
-		RunAndShowPreviewInHelp([]string{"blob"})
-
 		When("running `blob push`", func() {
-			RunAndShowPreviewInHelp([]string{"blob", "push"}, PreviewDesc, ExampleDesc)
 			It("should fail to read blob content and password from stdin at the same time", func() {
 				repo := fmt.Sprintf(repoFmt, "push", "password-stdin")
 				ORAS("blob", "push", RegistryRef(Host, repo, ""), "--password-stdin", "-").
@@ -90,11 +87,9 @@ var _ = Describe("ORAS beginners:", func() {
 		})
 
 		When("running `blob fetch`", func() {
-			RunAndShowPreviewInHelp([]string{"blob", "fetch"}, PreviewDesc, ExampleDesc)
-
 			It("should call sub-commands with aliases", func() {
 				ORAS("blob", "get", "--help").
-					MatchKeyWords("[Preview] Fetch", PreviewDesc, ExampleDesc).
+					MatchKeyWords(ExampleDesc).
 					Exec()
 			})
 			It("should have flag for prettifying JSON output", func() {
@@ -130,8 +125,6 @@ var _ = Describe("ORAS beginners:", func() {
 	})
 
 	When("running `blob delete`", func() {
-		RunAndShowPreviewInHelp([]string{"blob", "delete"}, PreviewDesc, ExampleDesc)
-
 		It("should fail if no blob reference is provided", func() {
 			dstRepo := fmt.Sprintf(repoFmt, "delete", "no-ref")
 			ORAS("cp", RegistryRef(Host, ImageRepo, foobar.Digest), RegistryRef(Host, dstRepo, foobar.Digest)).Exec()

test/e2e/suite/command/cp.go

@@ -18,12 +18,16 @@ package command
 import (
 	"encoding/json"
 	"fmt"
+	"regexp"
 	"strings"
 
 	. "github.com/onsi/ginkgo/v2"
+	"github.com/onsi/gomega"
 	. "github.com/onsi/gomega"
+	"github.com/onsi/gomega/gbytes"
 	ocispec "github.com/opencontainers/image-spec/specs-go/v1"
 	"oras.land/oras-go/v2"
+	"oras.land/oras/test/e2e/internal/testdata/feature"
 	"oras.land/oras/test/e2e/internal/testdata/foobar"
 	ma "oras.land/oras/test/e2e/internal/testdata/multi_arch"
 	. "oras.land/oras/test/e2e/internal/utils"
@@ -35,10 +39,11 @@ func cpTestRepo(text string) string {
 
 var _ = Describe("ORAS beginners:", func() {
 	When("running cp command", func() {
-		RunAndShowPreviewInHelp([]string{"copy"})
-
-		It("should show preview and help doc", func() {
-			ORAS("cp", "--help").MatchKeyWords("[Preview] Copy", PreviewDesc, ExampleDesc).Exec()
+		It("should show help doc with feature flags", func() {
+			out := ORAS("cp", "--help").MatchKeyWords("Copy", ExampleDesc).Exec()
+			gomega.Expect(out).Should(gbytes.Say("--from-distribution-spec string\\s+%s", regexp.QuoteMeta(feature.Preview.Mark)))
+			gomega.Expect(out).Should(gbytes.Say("-r, --recursive\\s+%s", regexp.QuoteMeta(feature.Preview.Mark)))
+			gomega.Expect(out).Should(gbytes.Say("--to-distribution-spec string\\s+%s", regexp.QuoteMeta(feature.Preview.Mark)))
 		})
 
 		It("should fail when no reference provided", func() {

test/e2e/suite/command/discover.go

@@ -17,12 +17,16 @@ package command
 
 import (
 	"encoding/json"
+	"regexp"
 	"strings"
 
 	. "github.com/onsi/ginkgo/v2"
+	"github.com/onsi/gomega"
 	. "github.com/onsi/gomega"
+	"github.com/onsi/gomega/gbytes"
 	ocispec "github.com/opencontainers/image-spec/specs-go/v1"
 	"gopkg.in/yaml.v2"
+	"oras.land/oras/test/e2e/internal/testdata/feature"
 	"oras.land/oras/test/e2e/internal/testdata/foobar"
 	"oras.land/oras/test/e2e/internal/testdata/multi_arch"
 	. "oras.land/oras/test/e2e/internal/utils"
@@ -48,7 +52,8 @@ var _ = Describe("ORAS beginners:", func() {
 		RunAndShowPreviewInHelp([]string{"discover"})
 
 		It("should show preview and help doc", func() {
-			ORAS("discover", "--help").MatchKeyWords("[Preview] Discover", PreviewDesc, ExampleDesc).Exec()
+			out := ORAS("discover", "--help").MatchKeyWords(feature.Preview.Mark+" Discover", feature.Preview.Description, ExampleDesc).Exec()
+			gomega.Expect(out).Should(gbytes.Say("--distribution-spec string\\s+%s", regexp.QuoteMeta(feature.Preview.Mark)))
 		})
 
 		It("should fail when no subject reference provided", func() {