feat: make feature gate infrastructure optional

This change improves the UX by making feature gate infrastructure opt-in rather than always generated.

Key changes:
- Added --with-feature-gates flag to init and create api commands
- Made feature gate scaffolding conditional based on flag or auto-detection
- Updated main.go template to conditionally include feature gate code
- Added auto-detection for existing feature gate infrastructure
- Created FeatureGateScaffolder interface for proper type handling

The infrastructure is now only generated when:
1. Explicitly requested via --with-feature-gates flag, or
2. Auto-detected when existing feature gate infrastructure is found

This addresses PR feedback suggesting that feature gate infrastructure
should be optional to improve user experience.

Author: wazery

pkg/plugins/golang/v4/api.go

@@ -50,11 +50,17 @@ type createAPISubcommand struct {
 	resourceFlag   *pflag.Flag
 	controllerFlag *pflag.Flag
 
+	// featureGateFlag holds the flag for feature gates
+	featureGateFlag *pflag.Flag
+
 	// force indicates that the resource should be created even if it already exists
 	force bool
 
 	// runMake indicates whether to run make or not after scaffolding APIs
 	runMake bool
+
+	// withFeatureGates indicates whether to include feature gate support
+	withFeatureGates bool
 }
 
 func (p *createAPISubcommand) UpdateMetadata(cliMeta plugin.CLIMetadata, subcmdMeta *plugin.SubcommandMetadata) {
@@ -96,6 +102,10 @@ func (p *createAPISubcommand) BindFlags(fs *pflag.FlagSet) {
 	fs.BoolVar(&p.force, "force", false,
 		"attempt to create resource even if it already exists")
 
+	fs.BoolVar(&p.withFeatureGates, "with-feature-gates", false,
+		"if specified, include feature gate support in scaffolded files")
+	p.featureGateFlag = fs.Lookup("with-feature-gates")
+
 	p.options = &goPlugin.Options{}
 
 	fs.StringVar(&p.options.Plural, "plural", "", "resource irregular plural form")
@@ -147,6 +157,13 @@ func (p *createAPISubcommand) InjectResource(res *resource.Resource) error {
 
 	p.options.UpdateResource(p.resource, p.config)
 
+	// Auto-detect feature gates if not explicitly set and infrastructure exists
+	if !p.featureGateFlag.Changed {
+		if _, err := os.Stat("internal/featuregates/featuregates.go"); err == nil {
+			p.withFeatureGates = true
+		}
+	}
+
 	if err := p.resource.Validate(); err != nil {
 		return fmt.Errorf("error validating resource: %w", err)
 	}
@@ -180,6 +197,11 @@ func (p *createAPISubcommand) PreScaffold(machinery.Filesystem) error {
 func (p *createAPISubcommand) Scaffold(fs machinery.Filesystem) error {
 	scaffolder := scaffolds.NewAPIScaffolder(p.config, *p.resource, p.force)
 	scaffolder.InjectFS(fs)
+
+	// Set feature gates flag if the scaffolder supports it
+	if fgScaffolder, ok := scaffolder.(scaffolds.FeatureGateScaffolder); ok {
+		fgScaffolder.SetWithFeatureGates(p.withFeatureGates)
+	}
 	if err := scaffolder.Scaffold(); err != nil {
 		return fmt.Errorf("error scaffolding API: %w", err)
 	}

pkg/plugins/golang/v4/init.go

@@ -57,6 +57,7 @@ type initSubcommand struct {
 	// flags
 	fetchDeps          bool
 	skipGoVersionCheck bool
+	withFeatureGates   bool
 }
 
 func (p *initSubcommand) UpdateMetadata(cliMeta plugin.CLIMetadata, subcmdMeta *plugin.SubcommandMetadata) {
@@ -84,6 +85,10 @@ func (p *initSubcommand) BindFlags(fs *pflag.FlagSet) {
 	// dependency args
 	fs.BoolVar(&p.fetchDeps, "fetch-deps", true, "ensure dependencies are downloaded")
 
+	// feature gate args
+	fs.BoolVar(&p.withFeatureGates, "with-feature-gates", false,
+		"if specified, scaffold feature gate infrastructure for experimental functionality")
+
 	// boilerplate args
 	fs.StringVar(&p.license, "license", "apache2",
 		"license to use to boilerplate, may be one of 'apache2', 'none'")
@@ -128,6 +133,10 @@ func (p *initSubcommand) PreScaffold(machinery.Filesystem) error {
 func (p *initSubcommand) Scaffold(fs machinery.Filesystem) error {
 	scaffolder := scaffolds.NewInitScaffolder(p.config, p.license, p.owner, p.commandName)
 	scaffolder.InjectFS(fs)
+	// Set feature gates flag if the scaffolder supports it
+	if fgScaffolder, ok := scaffolder.(scaffolds.FeatureGateScaffolder); ok {
+		fgScaffolder.SetWithFeatureGates(p.withFeatureGates)
+	}
 	if err := scaffolder.Scaffold(); err != nil {
 		return fmt.Errorf("error scaffolding init plugin: %w", err)
 	}

pkg/plugins/golang/v4/scaffolds/api.go

@@ -48,6 +48,9 @@ type apiScaffolder struct {
 
 	// force indicates whether to scaffold controller files even if it exists or not
 	force bool
+
+	// withFeatureGates indicates whether to include feature gate support
+	withFeatureGates bool
 }
 
 // NewAPIScaffolder returns a new Scaffolder for API/controller creation operations
@@ -64,6 +67,11 @@ func (s *apiScaffolder) InjectFS(fs machinery.Filesystem) {
 	s.fs = fs
 }
 
+// SetWithFeatureGates sets whether to include feature gate support
+func (s *apiScaffolder) SetWithFeatureGates(withFeatureGates bool) {
+	s.withFeatureGates = withFeatureGates
+}
+
 // Scaffold implements cmdutil.Scaffolder
 func (s *apiScaffolder) Scaffold() error {
 	slog.Info("Writing scaffold for you to edit...")
@@ -98,6 +106,14 @@ func (s *apiScaffolder) Scaffold() error {
 		return fmt.Errorf("error updating resource: %w", err)
 	}
 
+	// Check if feature gates infrastructure already exists
+	existingFeatureGatesFile := filepath.Join("internal", "featuregates", "featuregates.go")
+	if _, err := os.Stat(existingFeatureGatesFile); err == nil {
+		// Feature gates infrastructure already exists, enable support
+		s.withFeatureGates = true
+		slog.Debug("Detected existing feature gates infrastructure, enabling support")
+	}
+
 	// If using --force, discover existing feature gates before overwriting files
 	var existingGates []string
 	if s.force && doAPI {
@@ -108,7 +124,7 @@ func (s *apiScaffolder) Scaffold() error {
 		if err := scaffold.Execute(
 			&api.Types{
 				Force:                     s.force,
-				IncludeFeatureGateExample: false, // Don't include by default - keep it simple
+				IncludeFeatureGateExample: s.withFeatureGates,
 			},
 			&api.Group{},
 		); err != nil {
@@ -155,12 +171,15 @@ func (s *apiScaffolder) Scaffold() error {
 		availableGates = newGates
 	}
 
-	// Generate feature gates file
-	featureGatesTemplate := &cmd.FeatureGates{}
-	featureGatesTemplate.AvailableGates = availableGates
-	featureGatesTemplate.IfExistsAction = machinery.OverwriteFile
-	if err := scaffold.Execute(featureGatesTemplate); err != nil {
-		return fmt.Errorf("error scaffolding feature gates: %w", err)
+	// Only generate feature gates infrastructure if requested or if gates were discovered
+	if s.withFeatureGates || len(availableGates) > 0 {
+		// Generate feature gates file
+		featureGatesTemplate := &cmd.FeatureGates{}
+		featureGatesTemplate.AvailableGates = availableGates
+		featureGatesTemplate.IfExistsAction = machinery.OverwriteFile
+		if err := scaffold.Execute(featureGatesTemplate); err != nil {
+			return fmt.Errorf("error scaffolding feature gates: %w", err)
+		}
 	}
 
 	if err := scaffold.Execute(

pkg/plugins/golang/v4/scaffolds/init.go

@@ -53,11 +53,12 @@ var _ plugins.Scaffolder = &initScaffolder{}
 var kustomizeVersion string
 
 type initScaffolder struct {
-	config          config.Config
-	boilerplatePath string
-	license         string
-	owner           string
-	commandName     string
+	config           config.Config
+	boilerplatePath  string
+	license          string
+	owner            string
+	commandName      string
+	withFeatureGates bool
 
 	// fs is the filesystem that will be used by the scaffolder
 	fs machinery.Filesystem
@@ -79,6 +80,11 @@ func (s *initScaffolder) InjectFS(fs machinery.Filesystem) {
 	s.fs = fs
 }
 
+// SetWithFeatureGates sets whether to scaffold feature gate infrastructure
+func (s *initScaffolder) SetWithFeatureGates(withFeatureGates bool) {
+	s.withFeatureGates = withFeatureGates
+}
+
 // getControllerRuntimeReleaseBranch converts the ControllerRuntime semantic versioning string to a
 // release branch string. Example input: "v0.17.0" -> Output: "release-0.17"
 func getControllerRuntimeReleaseBranch() string {
@@ -155,11 +161,12 @@ func (s *initScaffolder) Scaffold() error {
 		}
 	}
 
-	err := scaffold.Execute(
+	// Build the list of templates to scaffold
+	scaffoldFiles := []machinery.Builder{
 		&cmd.Main{
 			ControllerRuntimeVersion: ControllerRuntimeVersion,
+			WithFeatureGates:         s.withFeatureGates,
 		},
-		&cmd.FeatureGates{AvailableGates: []string{}},
 		&templates.GoMod{
 			ControllerRuntimeVersion: ControllerRuntimeVersion,
 		},
@@ -178,7 +185,6 @@ func (s *initScaffolder) Scaffold() error {
 		&templates.Readme{CommandName: s.commandName},
 		&templates.Golangci{},
 		&e2e.Test{},
-		&e2e.WebhookTestUpdater{WireWebhook: false},
 		&e2e.SuiteTest{},
 		&github.E2eTestCi{},
 		&github.TestCi{},
@@ -188,7 +194,14 @@ func (s *initScaffolder) Scaffold() error {
 		&utils.Utils{},
 		&templates.DevContainer{},
 		&templates.DevContainerPostInstallScript{},
-	)
+	}
+
+	// Only add feature gates template if requested
+	if s.withFeatureGates {
+		scaffoldFiles = append(scaffoldFiles, &cmd.FeatureGates{AvailableGates: []string{}})
+	}
+
+	err := scaffold.Execute(scaffoldFiles...)
 	if err != nil {
 		return fmt.Errorf("failed to execute init scaffold: %w", err)
 	}

pkg/plugins/golang/v4/scaffolds/interfaces.go

@@ -0,0 +1,6 @@
+package scaffolds
+
+// FeatureGateScaffolder interface for scaffolders that support feature gates
+type FeatureGateScaffolder interface {
+	SetWithFeatureGates(bool)
+}

pkg/plugins/golang/v4/scaffolds/internal/templates/cmd/main.go

@@ -35,6 +35,7 @@ type Main struct {
 	machinery.RepositoryMixin
 
 	ControllerRuntimeVersion string
+	WithFeatureGates         bool
 }
 
 // SetTemplateDefaults implements machinery.Template
@@ -248,8 +249,10 @@ import (
 	"sigs.k8s.io/controller-runtime/pkg/metrics/filters"
 	"sigs.k8s.io/controller-runtime/pkg/webhook"
 	metricsserver "sigs.k8s.io/controller-runtime/pkg/metrics/server"
+	{{- if .WithFeatureGates }}
 	
 	featuregates "{{ .Repo }}/internal/featuregates"
+	{{- end }}
 	%s
 )
 
@@ -273,7 +276,9 @@ func main() {
 	var probeAddr string
 	var secureMetrics bool
 	var enableHTTP2 bool
+	{{- if .WithFeatureGates }}
 	var featureGates string
+	{{- end }}
 	var tlsOpts []func(*tls.Config)
 	flag.StringVar(&metricsAddr, "metrics-bind-address", "0", "The address the metrics endpoint binds to. " +
 		"Use :8443 for HTTPS or :8080 for HTTP, or leave as 0 to disable the metrics service.")
@@ -292,15 +297,18 @@ func main() {
 	flag.StringVar(&metricsCertKey, "metrics-cert-key", "tls.key", "The name of the metrics server key file.")
 	flag.BoolVar(&enableHTTP2, "enable-http2", false,
 		"If set, HTTP/2 will be enabled for the metrics and webhook servers")
+	{{- if .WithFeatureGates }}
 	flag.StringVar(&featureGates, "feature-gates", "", "A set of key=value pairs that describe feature gates for alpha/experimental features. " +
 		"Example: --feature-gates \"gate1=true,gate2=false\". " +
 		"Options are: "+featuregates.GetFeatureGatesHelpText())
+	{{- end }}
 	opts := zap.Options{
 		Development: true,
 	}
 	opts.BindFlags(flag.CommandLine)
 	flag.Parse()
 
+	{{- if .WithFeatureGates }}
 	// Parse feature gates
 	parsedFeatureGates, err := featuregates.ParseFeatureGates(featureGates)
 	if err != nil {
@@ -313,6 +321,7 @@ func main() {
 		setupLog.Error(err, "invalid feature gates")
 		os.Exit(1)
 	}
+	{{- end }}
 
 	ctrl.SetLogger(zap.New(zap.UseFlagOptions(&opts)))