From 4589c835eeabed221f6118db7eb69a769f529496 Mon Sep 17 00:00:00 2001 From: Patrick Zheng Date: Fri, 28 Apr 2023 01:21:50 +0800 Subject: [PATCH] chore: update the examples of sign and verify (#650) When NOTATION_EXPERIMENTAL variable is not set, experimental examples will be hidden. Resolves #645. Signed-off-by: Patrick Zheng --- .../internal}/experimental/experimental.go | 10 +++++++--- cmd/notation/list.go | 4 ++-- cmd/notation/sign.go | 19 +++++++++++-------- cmd/notation/verify.go | 18 ++++++++++-------- 4 files changed, 30 insertions(+), 21 deletions(-) rename {internal => cmd/notation/internal}/experimental/experimental.go (82%) diff --git a/internal/experimental/experimental.go b/cmd/notation/internal/experimental/experimental.go similarity index 82% rename from internal/experimental/experimental.go rename to cmd/notation/internal/experimental/experimental.go index 1c31c6159..e0ee8c1ba 100644 --- a/internal/experimental/experimental.go +++ b/cmd/notation/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 index e06a087fe..70791e915 100644 --- 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 index f92177758..46b9fb252 100644 --- 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] ", - 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 /@ - +` + experimentalExamples := ` Example - [Experimental] Sign an OCI artifact referenced in an OCI layout notation sign --oci-layout "@" @@ -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 /@ -`, +` + + command := &cobra.Command{ + Use: "sign [flags] ", + 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 index bc1061b8d..db6cd07eb 100644 --- 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 /: - +` + 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 /@ --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 /: --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 }