make --image-ref-template alpha (and include simple framework for alp…

…ha flags and usage)

Signed-off-by: Joe Lanford <[email protected]>

cmd/opm/alpha/cmd.go

@@ -9,13 +9,16 @@ import (
 	"github.com/operator-framework/operator-registry/cmd/opm/alpha/template"
 )
 
-func NewCmd() *cobra.Command {
+func NewCmd(showAlphaHelp bool) *cobra.Command {
 	runCmd := &cobra.Command{
-		Hidden: true,
-		Use:    "alpha",
-		Short:  "Run an alpha subcommand",
-		Args:   cobra.NoArgs,
-		Run:    func(_ *cobra.Command, _ []string) {}, // adding an empty function here to preserve non-zero exit status for misstated subcommands/flags for the command hierarchy
+		Use:   "alpha",
+		Short: "Run an alpha subcommand",
+		Args:  cobra.NoArgs,
+		Run:   func(_ *cobra.Command, _ []string) {}, // adding an empty function here to preserve non-zero exit status for misstated subcommands/flags for the command hierarchy
+	}
+
+	if !showAlphaHelp {
+		runCmd.Hidden = true
 	}
 
 	runCmd.AddCommand(

cmd/opm/index/add.go

@@ -41,7 +41,7 @@ var (
 	`)
 )
 
-func addIndexAddCmd(parent *cobra.Command) {
+func addIndexAddCmd(parent *cobra.Command, showAlphaHelp bool) {
 	indexCmd := &cobra.Command{
 		Use:   "add",
 		Short: "Add operator bundles to an index.",
@@ -78,8 +78,10 @@ func addIndexAddCmd(parent *cobra.Command) {
 		logrus.Panic(err.Error())
 	}
 	indexCmd.Flags().Bool("enable-alpha", false, "enable unsupported alpha features of the OPM CLI")
-	if err := indexCmd.Flags().MarkHidden("enable-alpha"); err != nil {
-		logrus.Panic(err.Error())
+	if !showAlphaHelp {
+		if err := indexCmd.Flags().MarkHidden("enable-alpha"); err != nil {
+			logrus.Panic(err.Error())
+		}
 	}
 	if err := indexCmd.Flags().MarkHidden("debug"); err != nil {
 		logrus.Panic(err.Error())

cmd/opm/index/cmd.go

@@ -8,7 +8,7 @@ import (
 )
 
 // AddCommand adds the index subcommand to the given parent command.
-func AddCommand(parent *cobra.Command) {
+func AddCommand(parent *cobra.Command, showAlphaHelp bool) {
 	cmd := &cobra.Command{
 		Use:   "index",
 		Short: "generate operator index container images",
@@ -34,7 +34,7 @@ func AddCommand(parent *cobra.Command) {
 	parent.AddCommand(cmd)
 
 	cmd.AddCommand(newIndexDeleteCmd())
-	addIndexAddCmd(cmd)
+	addIndexAddCmd(cmd, showAlphaHelp)
 	cmd.AddCommand(newIndexExportCmd())
 	cmd.AddCommand(newIndexPruneCmd())
 	cmd.AddCommand(newIndexDeprecateTruncateCmd())

cmd/opm/main.go

@@ -10,7 +10,8 @@ import (
 )
 
 func main() {
-	cmd := root.NewCmd()
+	showAlphaHelp := os.Getenv("HELP_ALPHA") == "true"
+	cmd := root.NewCmd(showAlphaHelp)
 	if err := cmd.Execute(); err != nil {
 		agg, ok := err.(utilerrors.Aggregate)
 		if !ok {

cmd/opm/registry/add.go

@@ -14,7 +14,7 @@ import (
 	"github.com/operator-framework/operator-registry/pkg/sqlite"
 )
 
-func newRegistryAddCmd() *cobra.Command {
+func newRegistryAddCmd(showAlphaHelp bool) *cobra.Command {
 	rootCmd := &cobra.Command{
 		Use:   "add",
 		Short: "add operator bundle to operator registry DB",
@@ -48,8 +48,10 @@ func newRegistryAddCmd() *cobra.Command {
 		logrus.Panic(err.Error())
 	}
 	rootCmd.Flags().Bool("enable-alpha", false, "enable unsupported alpha features of the OPM CLI")
-	if err := rootCmd.Flags().MarkHidden("enable-alpha"); err != nil {
-		logrus.Panic(err.Error())
+	if !showAlphaHelp {
+		if err := rootCmd.Flags().MarkHidden("enable-alpha"); err != nil {
+			logrus.Panic(err.Error())
+		}
 	}
 	if err := rootCmd.Flags().MarkDeprecated("skip-tls", "use --use-http and --skip-tls-verify instead"); err != nil {
 		logrus.Panic(err.Error())

cmd/opm/registry/cmd.go

@@ -8,7 +8,7 @@ import (
 )
 
 // NewOpmRegistryCmd returns the appregistry-server command
-func NewOpmRegistryCmd() *cobra.Command {
+func NewOpmRegistryCmd(showAlphaHelp bool) *cobra.Command {
 	rootCmd := &cobra.Command{
 		Use:   "registry",
 		Short: "interact with operator-registry database",
@@ -28,7 +28,7 @@ func NewOpmRegistryCmd() *cobra.Command {
 	}
 
 	rootCmd.AddCommand(newRegistryServeCmd())
-	rootCmd.AddCommand(newRegistryAddCmd())
+	rootCmd.AddCommand(newRegistryAddCmd(showAlphaHelp))
 	rootCmd.AddCommand(newRegistryRmCmd())
 	rootCmd.AddCommand(newRegistryPruneCmd())
 	rootCmd.AddCommand(newRegistryPruneStrandedCmd())

cmd/opm/render/cmd.go

@@ -15,7 +15,7 @@ import (
 	"github.com/operator-framework/operator-registry/pkg/sqlite"
 )
 
-func NewCmd() *cobra.Command {
+func NewCmd(showAlphaHelp bool) *cobra.Command {
 	var (
 		render           action.Render
 		output           string
@@ -27,17 +27,7 @@ func NewCmd() *cobra.Command {
 		Long: `Generate a stream of file-based catalog objects to stdout from the provided
 catalog images, file-based catalog directories, bundle images, and sqlite
 database files.
-
-If rendering sources that do not carry bundle image reference information
-(e.g. bundle directories), the --image-ref-template flag can be used to
-generate image references for the rendered file-based catalog objects.
-This is useful when generating a catalog with image references prior to
-those images actually existing. Available template variables are:
-  - {{.Package}} : the package name the bundle belongs to
-  - {{.Name}}    : the name of the bundle (for registry+v1 bundles, this is the CSV name)
-  - {{.Version}} : the version of the bundle
-
-` + sqlite.DeprecationMessage,
+`,
 		Args: cobra.MinimumNArgs(1),
 		Run: func(cmd *cobra.Command, args []string) {
 			render.Refs = args
@@ -85,7 +75,23 @@ those images actually existing. Available template variables are:
 	}
 	cmd.Flags().StringVarP(&output, "output", "o", "json", "Output format of the streamed file-based catalog objects (json|yaml)")
 	cmd.Flags().BoolVar(&render.Migrate, "migrate", false, "Perform migrations on the rendered FBC")
-	cmd.Flags().StringVar(&imageRefTemplate, "image-ref-template", "", "When bundle image reference information is unavailable, populate it with this template")
+
+	// Alpha flags
+	cmd.Flags().StringVar(&imageRefTemplate, "alpha-image-ref-template", "", "When bundle image reference information is unavailable, populate it with this template")
+
+	if showAlphaHelp {
+		cmd.Long += `
+If rendering sources that do not carry bundle image reference information
+(e.g. bundle directories), the --alpha-image-ref-template flag can be used to
+generate image references for the rendered file-based catalog objects.
+This is useful when generating a catalog with image references prior to
+those images actually existing. Available template variables are:
+  - {{.Package}} : the package name the bundle belongs to
+  - {{.Name}}    : the name of the bundle (for registry+v1 bundles, this is the CSV name)
+  - {{.Version}} : the version of the bundle
+`
+	}
+	cmd.Long += "\n" + sqlite.DeprecationMessage
 	return cmd
 }
 

cmd/opm/root/cmd.go

@@ -1,8 +1,12 @@
 package root
 
 import (
+	"fmt"
+	"strings"
+
 	"github.com/sirupsen/logrus"
 	"github.com/spf13/cobra"
+	"github.com/spf13/pflag"
 
 	"github.com/operator-framework/operator-registry/cmd/opm/alpha"
 	"github.com/operator-framework/operator-registry/cmd/opm/generate"
@@ -16,11 +20,13 @@ import (
 	"github.com/operator-framework/operator-registry/cmd/opm/version"
 )
 
-func NewCmd() *cobra.Command {
+func NewCmd(showAlphaHelp bool) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "opm",
 		Short: "operator package manager",
-		Long:  "CLI to interact with operator-registry and build indexes of operator content",
+		Long: `CLI to interact with operator-registry and build indexes of operator content.
+
+To view help related to alpha features, set HELP_ALPHA=true in the environment.`,
 		PreRunE: func(cmd *cobra.Command, _ []string) error {
 			if debug, _ := cmd.Flags().GetBool("debug"); debug {
 				logrus.SetLevel(logrus.DebugLevel)
@@ -38,14 +44,31 @@ func NewCmd() *cobra.Command {
 		logrus.Panic(err.Error())
 	}
 
-	cmd.AddCommand(registry.NewOpmRegistryCmd(), alpha.NewCmd(), initcmd.NewCmd(), migrate.NewCmd(), serve.NewCmd(), render.NewCmd(), validate.NewCmd(), generate.NewCmd())
-	index.AddCommand(cmd)
+	cmd.AddCommand(registry.NewOpmRegistryCmd(showAlphaHelp), alpha.NewCmd(showAlphaHelp), initcmd.NewCmd(), migrate.NewCmd(), serve.NewCmd(), render.NewCmd(showAlphaHelp), validate.NewCmd(), generate.NewCmd())
+	index.AddCommand(cmd, showAlphaHelp)
 	version.AddCommand(cmd)
 
 	cmd.Flags().Bool("debug", false, "enable debug logging")
 	if err := cmd.Flags().MarkHidden("debug"); err != nil {
 		logrus.Panic(err.Error())
 	}
 
+	// Mark all alpha flags as hidden and prepend their usage with an alpha warning
+	configureAlphaFlags(cmd, !showAlphaHelp)
+
 	return cmd
 }
+
+func configureAlphaFlags(cmd *cobra.Command, hideFlags bool) {
+	cmd.Flags().VisitAll(func(f *pflag.Flag) {
+		if strings.HasPrefix(f.Name, "alpha-") {
+			if hideFlags {
+				f.Hidden = true
+			}
+			f.Usage = fmt.Sprintf("(ALPHA: This flag will be removed or renamed in a future release, potentially without notice) %s", f.Usage)
+		}
+	})
+	for _, subCmd := range cmd.Commands() {
+		configureAlphaFlags(subCmd, hideFlags)
+	}
+}

test/e2e/e2e_suite_test.go

@@ -55,7 +55,7 @@ var _ = BeforeSuite(func() {
 
 	deprovision = ctx.MustProvision(ctx.Ctx())
 
-	opm = opmroot.NewCmd() // Creating multiple instances would cause flag registration conflicts
+	opm = opmroot.NewCmd(false) // Creating multiple instances would cause flag registration conflicts
 })
 
 func configureRegistry() {