refactor: deprecate table format (#1656)

Signed-off-by: Xiaoxuan Wang <[email protected]>
Co-authored-by: Xiaoxuan Wang <[email protected]>
Co-authored-by: Terry Howe <[email protected]>

Author: 3 people

cmd/oras/internal/option/format.go

@@ -56,9 +56,10 @@ var (
 		Usage:     "Print output using the given Go template",
 		HasParams: true,
 	}
+	// the table format is deprecated
 	FormatTypeTable = &FormatType{
 		Name:  "table",
-		Usage: "Get direct referrers and output in table format",
+		Usage: "[Deprecated] Get direct referrers and output in table format",
 	}
 	FormatTypeTree = &FormatType{
 		Name:  "tree",
@@ -98,7 +99,11 @@ func (opts *Format) ApplyFlags(fs *pflag.FlagSet) {
 }
 
 // Parse parses the input format flag.
-func (opts *Format) Parse(_ *cobra.Command) error {
+func (opts *Format) Parse(cmd *cobra.Command) error {
+	// print deprecation message for table format
+	if opts.FormatFlag == FormatTypeTable.Name {
+		fmt.Fprint(cmd.ErrOrStderr(), "Format \"table\" is deprecated and will be removed in a future release.\n")
+	}
 	if err := opts.parseFlag(); err != nil {
 		return err
 	}

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

@@ -16,6 +16,7 @@ limitations under the License.
 package feature
 
 const DeprecationMessageVerboseFlag = "Flag --verbose has been deprecated, and will be removed in a future release."
+const DeprecationMessageTableFormat = "Format \"table\" is deprecated and will be removed in a future release.\n"
 
 var (
 	Preview = struct {

test/e2e/suite/command/discover.go

@@ -56,10 +56,14 @@ var _ = Describe("ORAS beginners:", func() {
 			gomega.Expect(out).Should(gbytes.Say("--distribution-spec string\\s+%s", regexp.QuoteMeta(feature.Preview.Mark)))
 		})
 
-		It("should show text as default format type in help doc", func() {
+		It("should show tree as default format type in help doc", func() {
 			MatchDefaultFlagValue("format", "tree", "discover")
 		})
 
+		It("should show deprecation message when using table format", func() {
+			ORAS("discover", RegistryRef(ZOTHost, ImageRepo, foobar.Tag), "--format", "table").MatchErrKeyWords(feature.DeprecationMessageTableFormat).Exec()
+		})
+
 		It("should fail when no subject reference provided", func() {
 			ORAS("discover").ExpectFailure().MatchErrKeyWords("Error:").Exec()
 		})
@@ -192,7 +196,7 @@ var _ = Describe("1.1 registry users:", func() {
 	})
 	When("running discover command with table output", func() {
 		format := "table"
-		It("should all referrers of a subject with deprecation hint", func() {
+		It("should show all referrers of a subject with deprecation hint", func() {
 			referrers := []ocispec.Descriptor{foobar.SBOMImageReferrer, foobar.SBOMImageReferrer}
 			ORAS("discover", subjectRef, "-o", format).
 				MatchErrKeyWords(feature.Deprecated.Mark).
@@ -204,7 +208,7 @@ var _ = Describe("1.1 registry users:", func() {
 			err := ORAS("discover", subjectRef, "--format", format).
 				MatchKeyWords(append(discoverKeyWords(false, referrers...), foobar.Digest)...).
 				Exec().Err
-			Expect(err).NotTo(gbytes.Say(feature.Deprecated.Mark))
+			Expect(err).To(gbytes.Say(feature.Deprecated.Mark))
 		})
 	})
 	When("running discover command with go-template output", func() {