chore: update the examples of sign and verify (notaryproject#650)

When NOTATION_EXPERIMENTAL variable is not set, experimental examples will be hidden. Resolves notaryproject#645. Signed-off-by: Patrick Zheng <[email protected]>
patrickzheng200 · Apr 27, 2023 · 4589c83 · 4589c83
1 parent 2e56dd4
commit 4589c83
Show file tree

Hide file tree

Showing 4 changed files with 30 additions and 21 deletions.
diff --git a/internal/experimental/experimental.go → ...ion/internal/experimental/experimental.go b/internal/experimental/experimental.go → ...ion/internal/experimental/experimental.go
@@ -13,7 +13,7 @@ const (
 	enabled = "1"
 )
 
-// IsDisabled determines whether an experimental feature is disabled.
+// IsDisabled determines whether experimental features are disabled.
 func IsDisabled() bool {
 	return os.Getenv(envName) != enabled
 }
@@ -62,12 +62,16 @@ func warn() error {
 	return err
 }
 
-// HideFlags hide experimental flags when NOTATION_EXPERIMENTAL is disabled.
-func HideFlags(cmd *cobra.Command, flags ...string) {
+// HideFlags hides experimental flags when NOTATION_EXPERIMENTAL is disabled
+// and updates the command's long message accordingly when NOTATION_EXPERIMENTAL
+// is enabled.
+func HideFlags(cmd *cobra.Command, experimentalExamples string, flags []string) {
 	if IsDisabled() {
 		flagsSet := cmd.Flags()
 		for _, flag := range flags {
 			flagsSet.MarkHidden(flag)
 		}
+	} else if experimentalExamples != "" {
+		cmd.Long += experimentalExamples
 	}
 }
diff --git a/cmd/notation/list.go b/cmd/notation/list.go
@@ -6,8 +6,8 @@ import (
 	"fmt"
 
 	notationregistry "github.com/notaryproject/notation-go/registry"
+	"github.com/notaryproject/notation/cmd/notation/internal/experimental"
 	"github.com/notaryproject/notation/internal/cmd"
-	"github.com/notaryproject/notation/internal/experimental"
 	"github.com/opencontainers/go-digest"
 	ocispec "github.com/opencontainers/image-spec/specs-go/v1"
 	"github.com/spf13/cobra"
@@ -52,7 +52,7 @@ func listCommand(opts *listOpts) *cobra.Command {
 	opts.LoggingFlagOpts.ApplyFlags(cmd.Flags())
 	opts.SecureFlagOpts.ApplyFlags(cmd.Flags())
 	cmd.Flags().BoolVar(&opts.ociLayout, "oci-layout", false, "[Experimental] list signatures stored in OCI image layout")
-	experimental.HideFlags(cmd, "oci-layout")
+	experimental.HideFlags(cmd, "", []string{"oci-layout"})
 	return cmd
 }
 

diff --git a/cmd/notation/sign.go b/cmd/notation/sign.go
@@ -10,9 +10,9 @@ import (
 
 	"github.com/notaryproject/notation-go"
 	notationregistry "github.com/notaryproject/notation-go/registry"
+	"github.com/notaryproject/notation/cmd/notation/internal/experimental"
 	"github.com/notaryproject/notation/internal/cmd"
 	"github.com/notaryproject/notation/internal/envelope"
-	"github.com/notaryproject/notation/internal/experimental"
 	"github.com/notaryproject/notation/internal/slices"
 	ocispec "github.com/opencontainers/image-spec/specs-go/v1"
 	"github.com/spf13/cobra"
@@ -46,10 +46,7 @@ func signCommand(opts *signOpts) *cobra.Command {
 			inputType: inputTypeRegistry, // remote registry by default
 		}
 	}
-	command := &cobra.Command{
-		Use:   "sign [flags] <reference>",
-		Short: "Sign artifacts",
-		Long: `Sign artifacts
+	longMessage := `Sign artifacts
 
 Note: a signing key must be specified. This can be done temporarily by specifying a key ID, or a new key can be configured using the command "notation key add"
 
@@ -70,7 +67,8 @@ Example - Sign an OCI artifact identified by a tag (Notation will resolve tag to
 
 Example - Sign an OCI artifact stored in a registry and specify the signature expiry duration, for example 24 hours
   notation sign --expiry 24h <registry>/<repository>@<digest>
-
+`
+	experimentalExamples := `
 Example - [Experimental] Sign an OCI artifact referenced in an OCI layout
   notation sign --oci-layout "<oci_layout_path>@<digest>"
 
@@ -79,7 +77,12 @@ Example - [Experimental] Sign an OCI artifact identified by a tag and referenced
 
 Example - [Experimental] Sign an OCI artifact and use OCI artifact manifest to store the signature:
   notation sign --signature-manifest artifact <registry>/<repository>@<digest>
-`,
+`
+
+	command := &cobra.Command{
+		Use:   "sign [flags] <reference>",
+		Short: "Sign artifacts",
+		Long:  longMessage,
 		Args: func(cmd *cobra.Command, args []string) error {
 			if len(args) == 0 {
 				return errors.New("missing reference")
@@ -109,7 +112,7 @@ Example - [Experimental] Sign an OCI artifact and use OCI artifact manifest to s
 	command.Flags().StringVar(&opts.signatureManifest, "signature-manifest", signatureManifestImage, "[Experimental] manifest type for signature. options: \"image\", \"artifact\"")
 	cmd.SetPflagUserMetadata(command.Flags(), &opts.userMetadata, cmd.PflagUserMetadataSignUsage)
 	command.Flags().BoolVar(&opts.ociLayout, "oci-layout", false, "[Experimental] sign the artifact stored as OCI image layout")
-	experimental.HideFlags(command, "signature-manifest", "oci-layout")
+	experimental.HideFlags(command, experimentalExamples, []string{"signature-manifest", "oci-layout"})
 	return command
 }
 

diff --git a/cmd/notation/verify.go b/cmd/notation/verify.go
@@ -10,8 +10,8 @@ import (
 	"github.com/notaryproject/notation-go"
 	"github.com/notaryproject/notation-go/verifier"
 	"github.com/notaryproject/notation-go/verifier/trustpolicy"
+	"github.com/notaryproject/notation/cmd/notation/internal/experimental"
 	"github.com/notaryproject/notation/internal/cmd"
-	"github.com/notaryproject/notation/internal/experimental"
 	"github.com/notaryproject/notation/internal/ioutil"
 	ocispec "github.com/opencontainers/image-spec/specs-go/v1"
 
@@ -37,10 +37,7 @@ func verifyCommand(opts *verifyOpts) *cobra.Command {
 			inputType: inputTypeRegistry, // remote registry by default
 		}
 	}
-	command := &cobra.Command{
-		Use:   "verify [reference]",
-		Short: "Verify OCI artifacts",
-		Long: `Verify OCI artifacts
+	longMessage := `Verify OCI artifacts
 
 Prerequisite: added a certificate into trust store and created a trust policy.
 
@@ -49,13 +46,18 @@ Example - Verify a signature on an OCI artifact identified by a digest:
 
 Example - Verify a signature on an OCI artifact identified by a tag  (Notation will resolve tag to digest):
   notation verify <registry>/<repository>:<tag>
-
+`
+	experimentalExamples := `
 Example - [Experimental] Verify a signature on an OCI artifact referenced in an OCI layout using trust policy statement specified by scope.
   notation verify --oci-layout <registry>/<repository>@<digest> --scope <trust_policy_scope>
 
 Example - [Experimental] Verify a signature on an OCI artifact identified by a tag and referenced in an OCI layout using trust policy statement specified by scope.
   notation verify --oci-layout <registry>/<repository>:<tag> --scope <trust_policy_scope>
-`,
+`
+	command := &cobra.Command{
+		Use:   "verify [reference]",
+		Short: "Verify OCI artifacts",
+		Long:  longMessage,
 		Args: func(cmd *cobra.Command, args []string) error {
 			if len(args) == 0 {
 				return errors.New("missing reference")
@@ -80,7 +82,7 @@ Example - [Experimental] Verify a signature on an OCI artifact identified by a t
 	command.Flags().BoolVar(&opts.ociLayout, "oci-layout", false, "[Experimental] verify the artifact stored as OCI image layout")
 	command.Flags().StringVar(&opts.trustPolicyScope, "scope", "", "[Experimental] set trust policy scope for artifact verification, required and can only be used when flag \"--oci-layout\" is set")
 	command.MarkFlagsRequiredTogether("oci-layout", "scope")
-	experimental.HideFlags(command, "oci-layout", "scope")
+	experimental.HideFlags(command, experimentalExamples, []string{"oci-layout", "scope"})
 	return command
 }