✨ (API, CLI, go/v4) Add cliVersion field to the PROJECT file configuration to store the CLI binary version used to scaffold projects. (#4621)

Add cliVersion field to PROJECT file

This commit adds a new field to the PROJECT file: cliVersion.

Additionally, it updates the documentation in the Project Configuration Reference
to include the new cliVersion field.

It also updates the PROJECT file scaffolded in the docs and in testdata.

Author: vitorfloriano

cmd/cmd.go

@@ -55,6 +55,7 @@ func Run() {
 	c, err := cli.New(
 		cli.WithCommandName("kubebuilder"),
 		cli.WithVersion(versionString()),
+		cli.WithCliVersion(GetKubebuilderVersion()),
 		cli.WithPlugins(
 			golangv4.Plugin{},
 			gov4Bundle,

cmd/version.go

@@ -45,7 +45,7 @@ type version struct {
 	GoArch             string `json:"goArch"`
 }
 
-// versionString returns the CLI version
+// versionString returns the Full CLI version
 func versionString() string {
 	if kubeBuilderVersion == unknown {
 		if info, ok := debug.ReadBuildInfo(); ok && info.Main.Version != "" {
@@ -62,3 +62,13 @@ func versionString() string {
 		goarch,
 	})
 }
+
+// GetKubebuilderVersion returns only the CLI version string
+func GetKubebuilderVersion() string {
+	if kubeBuilderVersion == unknown {
+		if info, ok := debug.ReadBuildInfo(); ok && info.Main.Version != "" {
+			kubeBuilderVersion = info.Main.Version
+		}
+	}
+	return kubeBuilderVersion
+}

docs/book/src/cronjob-tutorial/testdata/project/PROJECT

@@ -2,6 +2,7 @@
 # This file is used to track the info used to scaffold your project
 # and allow the plugins properly work.
 # More info: https://book.kubebuilder.io/reference/project-config.html
+cliVersion: (devel)
 domain: tutorial.kubebuilder.io
 layout:
 - go.kubebuilder.io/v4

docs/book/src/getting-started/testdata/project/PROJECT

@@ -2,6 +2,7 @@
 # This file is used to track the info used to scaffold your project
 # and allow the plugins properly work.
 # More info: https://book.kubebuilder.io/reference/project-config.html
+cliVersion: (devel)
 domain: example.com
 layout:
 - go.kubebuilder.io/v4

docs/book/src/multiversion-tutorial/testdata/project/PROJECT

@@ -2,6 +2,7 @@
 # This file is used to track the info used to scaffold your project
 # and allow the plugins properly work.
 # More info: https://book.kubebuilder.io/reference/project-config.html
+cliVersion: (devel)
 domain: tutorial.kubebuilder.io
 layout:
 - go.kubebuilder.io/v4

docs/book/src/reference/project-config.md

@@ -14,6 +14,7 @@ Following is an example of a PROJECT config file which is the result of a projec
 # and allow the plugins properly work.
 # More info: https://book.kubebuilder.io/reference/project-config.html
 domain: testproject.org
+cliVersion: v4.6.0
 layout:
   - go.kubebuilder.io/v4
 plugins:
@@ -81,6 +82,7 @@ The `PROJECT` version `3` layout looks like:
 
 ```yaml
 domain: testproject.org
+cliVersion: v4.6.0
 layout:
   - go.kubebuilder.io/v4
 plugins:
@@ -132,6 +134,7 @@ Now let's check its layout fields definition:
 
 | Field                               | Description                                                                                                                                                                                                                                                                     |
 |-------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `cliVersion`                | Used to record the specific CLI version used during project scaffolding with `init`. Helps identifying the version of the tooling employed, aiding in troubleshooting and ensuring compatibility with updates.                                           |
 | `layout`                            | Defines the global plugins, e.g. a project `init` with `--plugins="go/v4,deploy-image/v1-alpha"` means that any sub-command used will always call its implementation for both plugins in a chain.                                                                               |
 | `domain`                            | Store the domain of the project. This information can be provided by the user when the project is generate with the `init` sub-command and the `domain` flag.                                                                                                                   |
 | `plugins`                           | Defines the plugins used to do custom scaffolding, e.g. to use the optional `deploy-image/v1-alpha` plugin to do scaffolding for just a specific api via the command `kubebuider create api [options] --plugins=deploy-image/v1-alpha`.                                         |

pkg/cli/cli.go

@@ -47,8 +47,10 @@ type CLI struct { //nolint:maligned
 
 	// Root command name. It is injected downstream to provide correct help, usage, examples and errors.
 	commandName string
-	// CLI version string.
+	// Full CLI version string.
 	version string
+	// CLI version string (just the CLI version number, no extra information).
+	cliVersion string
 	// CLI root's command description.
 	description string
 	// Plugins registered in the CLI.

pkg/cli/cmd_helpers.go

@@ -128,6 +128,7 @@ func (c *CLI) applySubcommandHooks(
 		errorMessage:   errorMessage,
 		projectVersion: c.projectVersion,
 		pluginChain:    pluginChain,
+		cliVersion:     c.cliVersion,
 	}
 	cmd.PreRunE = factory.preRunEFunc(options, createConfig)
 	cmd.RunE = factory.runEFunc()
@@ -189,6 +190,8 @@ type executionHooksFactory struct {
 	projectVersion config.Version
 	// pluginChain is the plugin chain configured for this project.
 	pluginChain []string
+	// cliVersion is the version of the CLI.
+	cliVersion string
 }
 
 func (factory *executionHooksFactory) forEach(cb func(subcommand plugin.Subcommand) error, errorMessage string) error {
@@ -244,6 +247,11 @@ func (factory *executionHooksFactory) preRunEFunc(
 		}
 		cfg := factory.store.Config()
 
+		// Set the CLI version if creating a new project configuration.
+		if createConfig {
+			_ = cfg.SetCliVersion(factory.cliVersion)
+		}
+
 		// Set the pluginChain field.
 		if len(factory.pluginChain) != 0 {
 			_ = cfg.SetPluginChain(factory.pluginChain)

pkg/cli/options.go

@@ -57,6 +57,14 @@ func WithVersion(version string) Option {
 	}
 }
 
+// WithCliVersion is an Option that defines only the version string of the CLI (no extra info).
+func WithCliVersion(version string) Option {
+	return func(c *CLI) error {
+		c.cliVersion = version
+		return nil
+	}
+}
+
 // WithDescription is an Option that sets the CLI's root description.
 func WithDescription(description string) Option {
 	return func(c *CLI) error {

pkg/config/interface.go

@@ -27,6 +27,12 @@ type Config interface {
 	// GetVersion returns the current project version.
 	GetVersion() Version
 
+	// GetCliVersion returns the CLI binary version that was used to scaffold or initialize the project.
+	GetCliVersion() string
+
+	// SetCliVersion sets the binary version used to initialize the project.
+	SetCliVersion(version string) error
+
 	/* String fields */
 
 	// GetDomain returns the project domain.

pkg/config/v3/config.go

@@ -61,6 +61,7 @@ type Cfg struct {
 	Domain      string      `json:"domain,omitempty"`
 	Repository  string      `json:"repo,omitempty"`
 	Name        string      `json:"projectName,omitempty"`
+	CliVersion  string      `json:"cliVersion,omitempty"`
 	PluginChain stringSlice `json:"layout,omitempty"`
 
 	// Boolean fields
@@ -93,6 +94,17 @@ func (c Cfg) GetVersion() config.Version {
 	return c.Version
 }
 
+// GetCliVersion implements config.Config
+func (c Cfg) GetCliVersion() string {
+	return c.CliVersion
+}
+
+// SetCliVersion implements config.Config
+func (c *Cfg) SetCliVersion(version string) error {
+	c.CliVersion = version
+	return nil
+}
+
 // GetDomain implements config.Config
 func (c Cfg) GetDomain() string {
 	return c.Domain

testdata/project-v4-multigroup/PROJECT

@@ -2,6 +2,7 @@
 # This file is used to track the info used to scaffold your project
 # and allow the plugins properly work.
 # More info: https://book.kubebuilder.io/reference/project-config.html
+cliVersion: (devel)
 domain: testproject.org
 layout:
 - go.kubebuilder.io/v4

testdata/project-v4-with-plugins/PROJECT

@@ -2,6 +2,7 @@
 # This file is used to track the info used to scaffold your project
 # and allow the plugins properly work.
 # More info: https://book.kubebuilder.io/reference/project-config.html
+cliVersion: (devel)
 domain: testproject.org
 layout:
 - go.kubebuilder.io/v4

testdata/project-v4/PROJECT

@@ -2,6 +2,7 @@
 # This file is used to track the info used to scaffold your project
 # and allow the plugins properly work.
 # More info: https://book.kubebuilder.io/reference/project-config.html
+cliVersion: (devel)
 domain: testproject.org
 layout:
 - go.kubebuilder.io/v4