17032232178

Committed 18 Aug 2025 05:51AM UTC coverage: 70.938% (+0.07%) from 70.864%

Build # 17032232178

Build Type

push

github

Committed by

web-flow

Commit Message

✨ (alpha update): easier commits, safer defaults, more control (#5013)

chore: improve alpha update with clearer commits, safer defaults, and more control

- clearer commit messages (e.g. "(chore) scaffold from release vX.Y.Z")
- better error reporting with actionable context
- automatic cleanup of temporary branches
- predictable output always on the output branch
- simpler history by default (squash), with --show-commits for full history
- explicit push control (nothing pushed unless --push)
- refactored code for maintainability and updated docs

Assisted-by: ChatGPT (OpenAI)

Co-authored-by: Vitor Floriano <vitorfloriano@users.noreply.github.com>

Run Details

187 of 243 new or added lines in 5 files covered. (76.95%)

5 existing lines in 1 file now uncovered.

3017 of 4253 relevant lines covered (70.94%)

14.36 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

87.06

/pkg/cli/alpha/update.go

/*
Copyright 2025 The Kubernetes Authors.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/

package alpha

import (
        "fmt"
        "log"

        "github.com/spf13/cobra"

        "sigs.k8s.io/kubebuilder/v4/pkg/cli/alpha/internal/update"
)

// NewUpdateCommand creates and returns a new Cobra command for updating Kubebuilder projects.
func NewUpdateCommand() *cobra.Command {
        opts := update.Update{}
        updateCmd := &cobra.Command{
                Use:   "update",
                Short: "Update your project to a newer version (3-way merge; squash by default)",
                Long: `Upgrade your project scaffold using a 3-way merge while preserving your code.

The updater uses four temporary branches during the run:
  • ancestor : clean scaffold from the starting version (--from-version)
  • original : snapshot of your current project (--from-branch)
  • upgrade  : scaffold generated with the target version (--to-version)
  • merge    : result of merging original into upgrade (conflicts possible)

Output branch & history:
  • Default: SQUASH the merge result into ONE commit on:
        kubebuilder-update-from-<from-version>-to-<to-version>
  • --show-commits: keep full history (not compatible with --preserve-path).

Conflicts:
  • Default: stop on conflicts and leave the merge branch for manual resolution.
  • --force: commit with conflict markers so automation can proceed.

Other options:
  • --preserve-path: restore paths from base when squashing (e.g., CI configs).
  • --output-branch: override the output branch name.
  • --push: push the output branch to 'origin' after the update.

Defaults:
  • --from-version / --to-version: resolved from PROJECT and the latest release if unset.
  • --from-branch: defaults to 'main' if not specified.`,
                Example: `
  # Update from the version in PROJECT to the latest, stop on conflicts
  kubebuilder alpha update

  # Update from a specific version to latest
  kubebuilder alpha update --from-version v4.6.0

  # Update from v4.5.0 to v4.7.0 and keep conflict markers (automation-friendly)
  kubebuilder alpha update --from-version v4.5.0 --to-version v4.7.0 --force

  # Keep full commit history instead of squashing
  kubebuilder alpha update --from-version v4.5.0 --to-version v4.7.0 --force --show-commits

  # Squash while preserving CI workflows from base (e.g., main)
  kubebuilder alpha update --force --preserve-path .github/workflows

  # Show commits into a custom output branch name
  kubebuilder alpha update --force --show-commits --output-branch my-update-branch

  # Run update and push the output branch to origin (works with or without --show-commits)
  kubebuilder alpha update --from-version v4.6.0 --to-version v4.7.0 --force --push`,
                PreRunE: func(_ *cobra.Command, _ []string) error {
                        if opts.ShowCommits && len(opts.PreservePath) > 0 {
                                return fmt.Errorf("the --preserve-path flag is not supported with --show-commits")
                        }

                        if err := opts.Prepare(); err != nil {
                                return fmt.Errorf("failed to prepare update: %w", err)
                        }
                        return opts.Validate()
                },
                Run: func(_ *cobra.Command, _ []string) {
                        if err := opts.Update(); err != nil {
                                log.Fatalf("Update failed: %s", err)
                        }
                },
        }

        updateCmd.Flags().StringVar(&opts.FromVersion, "from-version", "",
                "binary release version to upgrade from. Should match the version used to init the project and be "+
                        "a valid release version, e.g., v4.6.0. If not set, it defaults to the version specified in the PROJECT file.")
        updateCmd.Flags().StringVar(&opts.ToVersion, "to-version", "",
                "binary release version to upgrade to. Should be a valid release version, e.g., v4.7.0. "+
                        "If not set, it defaults to the latest release version available in the project repository.")
        updateCmd.Flags().StringVar(&opts.FromBranch, "from-branch", "",
                "Git branch to use as current state of the project for the update.")
        updateCmd.Flags().BoolVar(&opts.Force, "force", false,
                "Force the update even if conflicts occur. Conflicted files will include conflict markers, and a "+
                        "commit will be created automatically. Ideal for automation (e.g., cronjobs, CI).")
        updateCmd.Flags().BoolVar(&opts.ShowCommits, "show-commits", false,
                "If set, the update will keep the full history instead of squashing into a single commit.")
        updateCmd.Flags().StringArrayVar(&opts.PreservePath, "preserve-path", nil,
                "Paths to preserve from the base branch when squashing (repeatable). Not supported with --show-commits. "+
                        "Example: --preserve-path .github/workflows")
        updateCmd.Flags().StringVar(&opts.OutputBranch, "output-branch", "",
                "Override the default output branch name (default: kubebuilder-update-from-<from-version>-to-<to-version>).")
        updateCmd.Flags().BoolVar(&opts.Push, "push", false,
                "Push the output branch to the remote repository after the update.")

        return updateCmd
}

1	/*
2	Copyright 2025 The Kubernetes Authors.
3
4	Licensed under the Apache License, Version 2.0 (the "License");
5	you may not use this file except in compliance with the License.
6	You may obtain a copy of the License at
7
8	http://www.apache.org/licenses/LICENSE-2.0
9
10	Unless required by applicable law or agreed to in writing, software
11	distributed under the License is distributed on an "AS IS" BASIS,
12	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13	See the License for the specific language governing permissions and
14	limitations under the License.
15	*/
16
17	package alpha
18
19	import (
20	"fmt"
21	"log"
22
23	"github.com/spf13/cobra"
24
25	"sigs.k8s.io/kubebuilder/v4/pkg/cli/alpha/internal/update"
26	)
27
28	// NewUpdateCommand creates and returns a new Cobra command for updating Kubebuilder projects.
29	func NewUpdateCommand() *cobra.Command {	2✔
30	opts := update.Update{}	2✔
31	updateCmd := &cobra.Command{	2✔
32	Use: "update",	2✔
33	Short: "Update your project to a newer version (3-way merge; squash by default)",	2✔
34	Long: `Upgrade your project scaffold using a 3-way merge while preserving your code.	2✔
35		2✔
36	The updater uses four temporary branches during the run:	2✔
37	• ancestor : clean scaffold from the starting version (--from-version)	2✔
38	• original : snapshot of your current project (--from-branch)	2✔
39	• upgrade : scaffold generated with the target version (--to-version)	2✔
40	• merge : result of merging original into upgrade (conflicts possible)	2✔
41		2✔
42	Output branch & history:	2✔
43	• Default: SQUASH the merge result into ONE commit on:	2✔
44	kubebuilder-update-from-<from-version>-to-<to-version>	2✔
45	• --show-commits: keep full history (not compatible with --preserve-path).	2✔
46		2✔
47	Conflicts:	2✔
48	• Default: stop on conflicts and leave the merge branch for manual resolution.	2✔
49	• --force: commit with conflict markers so automation can proceed.	2✔
50		2✔
51	Other options:	2✔
52	• --preserve-path: restore paths from base when squashing (e.g., CI configs).	2✔
53	• --output-branch: override the output branch name.	2✔
54	• --push: push the output branch to 'origin' after the update.	2✔
55		2✔
56	Defaults:	2✔
57	• --from-version / --to-version: resolved from PROJECT and the latest release if unset.	2✔
58	• --from-branch: defaults to 'main' if not specified.`,	2✔
59	Example: `	2✔
60	# Update from the version in PROJECT to the latest, stop on conflicts	2✔
61	kubebuilder alpha update	2✔
62		2✔
63	# Update from a specific version to latest	2✔
64	kubebuilder alpha update --from-version v4.6.0	2✔
65		2✔
66	# Update from v4.5.0 to v4.7.0 and keep conflict markers (automation-friendly)	2✔
67	kubebuilder alpha update --from-version v4.5.0 --to-version v4.7.0 --force	2✔
68		2✔
69	# Keep full commit history instead of squashing	2✔
70	kubebuilder alpha update --from-version v4.5.0 --to-version v4.7.0 --force --show-commits	2✔
71		2✔
72	# Squash while preserving CI workflows from base (e.g., main)	2✔
73	kubebuilder alpha update --force --preserve-path .github/workflows	2✔
74		2✔
75	# Show commits into a custom output branch name	2✔
76	kubebuilder alpha update --force --show-commits --output-branch my-update-branch	2✔
77		2✔
78	# Run update and push the output branch to origin (works with or without --show-commits)	2✔
79	kubebuilder alpha update --from-version v4.6.0 --to-version v4.7.0 --force --push`,	2✔
80	PreRunE: func(_ *cobra.Command, _ []string) error {	2✔
NEW 81	if opts.ShowCommits && len(opts.PreservePath) > 0 {	×
NEW 82	return fmt.Errorf("the --preserve-path flag is not supported with --show-commits")	×
NEW 83	}	×
84
NEW 85	if err := opts.Prepare(); err != nil {	×
86	return fmt.Errorf("failed to prepare update: %w", err)	×
87	}	×
88	return opts.Validate()	×
89	},
90	Run: func(_ *cobra.Command, _ []string) {	×
91	if err := opts.Update(); err != nil {	×
92	log.Fatalf("Update failed: %s", err)	×
93	}	×
94	},
95	}
96
97	updateCmd.Flags().StringVar(&opts.FromVersion, "from-version", "",	2✔
98	"binary release version to upgrade from. Should match the version used to init the project and be "+	2✔
99	"a valid release version, e.g., v4.6.0. If not set, it defaults to the version specified in the PROJECT file.")	2✔
100	updateCmd.Flags().StringVar(&opts.ToVersion, "to-version", "",	2✔
101	"binary release version to upgrade to. Should be a valid release version, e.g., v4.7.0. "+	2✔
102	"If not set, it defaults to the latest release version available in the project repository.")	2✔
103	updateCmd.Flags().StringVar(&opts.FromBranch, "from-branch", "",	2✔
104	"Git branch to use as current state of the project for the update.")	2✔
105	updateCmd.Flags().BoolVar(&opts.Force, "force", false,	2✔
106	"Force the update even if conflicts occur. Conflicted files will include conflict markers, and a "+	2✔
107	"commit will be created automatically. Ideal for automation (e.g., cronjobs, CI).")	2✔
108	updateCmd.Flags().BoolVar(&opts.ShowCommits, "show-commits", false,	2✔
109	"If set, the update will keep the full history instead of squashing into a single commit.")	2✔
110	updateCmd.Flags().StringArrayVar(&opts.PreservePath, "preserve-path", nil,	2✔
111	"Paths to preserve from the base branch when squashing (repeatable). Not supported with --show-commits. "+	2✔
112	"Example: --preserve-path .github/workflows")	2✔
113	updateCmd.Flags().StringVar(&opts.OutputBranch, "output-branch", "",	2✔
114	"Override the default output branch name (default: kubebuilder-update-from-<from-version>-to-<to-version>).")	2✔
115	updateCmd.Flags().BoolVar(&opts.Push, "push", false,	2✔
116	"Push the output branch to the remote repository after the update.")	2✔
117		2✔
118	return updateCmd	2✔
119	}

kubernetes-sigs / kubebuilder / 17032232178

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous