✨ (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 <[email protected]>

Author: camilamacedo86

docs/book/src/reference/commands/alpha_update.md

@@ -2,25 +2,12 @@
 
 ## Overview
 
-`kubebuilder alpha update` upgrades your project’s scaffold to a newer scaffold version.
+`kubebuilder alpha update` upgrades your project’s scaffold to a newer Kubebuilder release using a **3-way Git merge**. It rebuilds clean scaffolds for the old and new versions, merges your current code into the new scaffold, and gives you a reviewable output branch.
+It takes care of the heavy lifting so you can focus on reviewing and resolving conflicts,
+not re-applying your code.
 
-It uses a **3-way merge** so you do less manual work. The command creates these branches:
-
-- **Ancestor**: clean scaffold from the **old** version
-- **Original**: your current project (from your base branch)
-- **Upgrade**: clean scaffold from the **new** version
-- **Merge**: result of merging **Original** into **Upgrade** (this is where conflicts appear)
-
-You can review and test the merge result before applying it to your main branch.
-Optionally, use **`--squash`** to put the merge result into **one commit** on a stable output branch (great for PRs).
-
-<aside class="note warning">
-<h1>Creates branches and deletes files</h1>
-
-This command creates branches like `tmp-kb-update-*` and removes files during the process.
-Make sure your work is committed before you run it.
-
-</aside>
+By default, the final result is **squashed into a single commit** on a dedicated output branch.
+If you prefer to keep the full history (no squash), use `--show-commits`.
 
 ## When to Use It
 
@@ -33,26 +20,45 @@ Use this command when you:
 
 ## How It Works
 
-1. **Detect versions**
-   Reads `--from-version` (or the `PROJECT` file) and `--to-version` (or uses the latest).
-
-2. **Create branches & re-scaffold**
-   - `tmp-ancestor-*`: clean scaffold from **from-version**
-   - `tmp-original-*`: snapshot of your **from-branch** (e.g., `main`)
-   - `tmp-upgrade-*`: clean scaffold from **to-version**
-
-3. **3-way merge**
-   Creates `tmp-merge-*` from **Upgrade** and merges **Original** into it.
-   Runs `make manifests generate fmt vet lint-fix` to normalise outputs.
-   Runs `make manifests generate fmt vet lint-fix` to normalize outputs.
-
-4. **(Optional) Squash**
-   With `--squash`, copies the merge result to a stable output branch and commits **once**:
-   - Default output branch: `kubebuilder-alpha-update-to-<to-version>`
-   - Or set your own with `--output-branch`
-     If there are conflicts, the single commit will include conflict markers.
-
-## How to Use It
+You tell the tool the **new version**, and which branch has your project.
+It rebuilds both scaffolds, merges your code into the new one with a **3-way merge**,
+and gives you an output branch you can review and merge safely.
+You decide if you want one clean commit, the full history, or an auto-push to remote.
+
+### Step 1: Detect versions
+- It looks at your `PROJECT` file or the flags you pass.
+- Decides which **old version** you are coming from by reading the `cliVersion` field in the `PROJECT` file (if available).
+- Figures out which **new version** you want (defaults to the latest release).
+- Chooses which branch has your current code (defaults to `main`).
+
+### Step 2: Create scaffolds
+The command creates three temporary branches:
+- **Ancestor**: a clean project scaffold from the **old version**.
+- **Original**: a snapshot of your **current code**.
+- **Upgrade**: a clean scaffold from the **new version**.
+
+### Step 3: Do a 3-way merge
+- Merges **Original** (your code) into **Upgrade** (the new scaffold) using Git’s **3-way merge**.
+- This keeps your customizations while pulling in upstream changes.
+- If conflicts happen:
+    - **Default** → stop and let you resolve them manually.
+    - **With `--force`** → continue and commit even with conflict markers. **(ideal for automation)**
+- Runs `make manifests generate fmt vet lint-fix` to tidy things up.
+
+### Step 4: Write the output branch
+- By default, everything is **squashed into one commit** on a safe output branch:
+  `kubebuilder-update-from-<from-version>-to-<to-version>`.
+- You can change the behavior:
+    - `--show-commits`: keep the full history.
+    - `--preserve-path`: in squash mode, restore specific files (like CI configs) from your base branch.
+    - `--output-branch`: pick a custom branch name.
+    - `--push`: push the result to `origin` automatically.
+
+### Step 5: Cleanup
+- Once the output branch is ready, all the temporary working branches are deleted.
+- You are left with one clean branch you can test, review, and merge back into your main branch.
+
+## How to Use It (commands)
 
 Run from your project root:
 
@@ -64,38 +70,43 @@ Pin versions and base branch:
 
 ```shell
 kubebuilder alpha update \
-  --from-version v4.5.2 \
-  --to-version   v4.6.0 \
-  --from-branch  main
+--from-version v4.5.2 \
+--to-version   v4.6.0 \
+--from-branch  main
 ```
 Automation-friendly (proceed even with conflicts):
 
 ```shell
 kubebuilder alpha update --force
 ```
 
-Create a **single squashed commit** on a stable PR branch:
+Keep full history instead of squashing:
+```
+kubebuilder alpha update --from-version v4.5.0 --to-version v4.7.0 --force --show-commits
+```
+
+Default squash but **preserve** CI/workflows from the base branch:
 
 ```shell
-kubebuilder alpha update --force --squash
+kubebuilder alpha update --force \
+--preserve-path .github/workflows \
+--preserve-path docs
 ```
 
-Squash while **preserving** paths from your base branch (keep CI/workflows, docs, etc.):
+Use a custom output branch name:
 
 ```shell
-kubebuilder alpha update --force --squash \
-  --preserve-path .github/workflows \
-  --preserve-path docs
+kubebuilder alpha update --force \
+--output-branch upgrade/kb-to-v4.7.0
 ```
 
-Use a **custom output branch** name:
+Run update and push the result to origin:
 
 ```shell
-kubebuilder alpha update --force --squash \
-  -output-branch upgrade/kb-to-v4.7.0
+kubebuilder alpha update --from-version v4.6.0 --to-version v4.7.0 --force --push
 ```
 
-## Merge Conflicts with `--force`
+## Handling Conflicts (`--force` vs default)
 
 When you use `--force`, Git finishes the merge even if there are conflicts.
 The commit will include markers like:
@@ -105,15 +116,35 @@ The commit will include markers like:
 Your changes
 =======
 Incoming changes
->>>>>>> tmp-original-…
+>>>>>>> (original)
 ```
 
-- **Without `--force`**: the command stops on `tmp-merge-*` and prints guidance; no commit is created.
-- **With `--force`**: the merge is committed (on `tmp-merge-*`, or on the output branch if using `--squash`) and contains the markers.
+This allows you to run the command in CI or cron jobs without manual intervention.
+
+- Without `--force`: the command stops on the merge branch and prints guidance; no commit is created.
+- With `--force`: the merge is committed (merge or output branch) and contains the markers.
+
+After you fix conflicts, always run:
+
+```shell
+make manifests generate fmt vet lint-fix
+# or
+make all
+```
 
-## Commit message used in `--squash` mode
+## Flags
 
-> [kubebuilder-automated-update]: update scaffold from <from> to <to>; (squashed 3-way merge)
+| Flag              | Description                                                                                                                                                 |
+|-------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `--from-version`  | Kubebuilder release to update **from** (e.g., `v4.6.0`). If unset, read from the `PROJECT` file when possible.                                              |
+| `--to-version`    | Kubebuilder release to update **to** (e.g., `v4.7.0`). If unset, defaults to the latest available release.                                                  |
+| `--from-branch`   | Git branch that holds your current project code. Defaults to `main`.                                                                                        |
+| `--force`         | Continue even if merge conflicts happen. Conflicted files are committed with conflict markers (CI/cron friendly).                                           |
+| `--show-commits`  | Keep full history (do not squash). **Not compatible** with `--preserve-path`.                                                                               |
+| `--preserve-path` | Repeatable. **Squash mode only.** After copying the merge tree to the output branch, restore these paths from the base branch (e.g., `.github/workflows`).  |
+| `--output-branch` | Name of the output branch. Default: `kubebuilder-update-from-<from-version>-to-<to-version>`.                                                               |
+| `--push`          | Push the output branch to the `origin` remote after the update completes.                                                                                   |
+| `-h, --help`      | Show help for this command.                                                                                                                                 |
 
 <aside class="note warning">
 <h1>You might need to upgrade your project first</h1>
@@ -133,51 +164,19 @@ We use that value to pick the correct CLI for re-scaffolding.
 
 </aside>
 
-<aside class="note warning">
-You must resolve these conflicts before merging into `main` (or your base branch).
-<strong>After resolving conflicts, always run:</strong>
-
-```shell
-make manifests generate fmt vet lint-fix
-# or
-make all
-```
-
-</aside>
-
-## Flags
+## Demonstration
 
-| Flag              | Description                                                                                                                                |
-|-------------------|--------------------------------------------------------------------------------------------------------------------------------------------|
-| `--from-version`  | Kubebuilder version your project was created with. If unset, taken from the `PROJECT` file. |
-| `--to-version`    | Version to upgrade to. Defaults to the latest release.                                                                                     |
-| `--from-branch`   | Git branch that has your current project code. Defaults to `main`.                                                                          |
-| `--force`         | Continue even if merge conflicts happen. Conflicted files are committed with conflict markers (useful for CI/cron).                         |
-| `--squash`        | Write the merge result as **one commit** on a stable output branch.                                                                         |
-| `--preserve-path` | Repeatable. With `--squash`, restore these paths from the base branch (e.g., `--preserve-path .github/workflows`).                          |
-| `--output-branch` | Branch name to use for the squashed commit (default: `kubebuilder-alpha-update-to-<to-version>`).                                          |
-| `-h, --help`      | Show help for this command.                                                                                                                |
+<iframe width="560" height="315" src="https://www.youtube.com/embed/J8zonID__8k?si=WC-FXOHX0mCjph71" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
 
 <aside class="note">
-<h1>CLI Version Tracking</h1>
-
-Projects created with **Kubebuilder v4.6.0+** include `cliVersion` in the `PROJECT` file.
-We use that value to pick the correct CLI for re-scaffolding.
+<h1>About this demo</h1>
 
-If your project was created with an older version,
-you can set `--from-version` to the version you used.
-
-However, this command uses `kubebuilder alpha generate` under the hood.
-We tested projects created with <strong>v4.5.0+</strong>.
-If yours is older, first run `kubebuilder alpha generate` once to modernize the scaffold.
-After that, you can use `kubebuilder alpha update` for future upgrades.
+This video was recorded with Kubebuilder release `v7.0.1`.
+Since then, the command has been improved,
+so the current behavior may differ slightly from what is shown in the demo.
 
 </aside>
 
-## Demonstration
-
-<iframe width="560" height="315" src="https://www.youtube.com/embed/J8zonID__8k?si=WC-FXOHX0mCjph71" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
-
 ## Further Resources
 
 - WIP: Design proposal for update automation — https://github.com/kubernetes-sigs/kubebuilder/pull/4302

pkg/cli/alpha/generate_test.go

@@ -16,19 +16,10 @@ limitations under the License.
 package alpha
 
 import (
-	"testing"
-
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 )
 
-// Figuring out ways to test run these tests similar to existing.
-// Currently unable to run without this on VSCode. Will remove once done
-func TestCommand(t *testing.T) {
-	RegisterFailHandler(Fail)
-	RunSpecs(t, "alpha")
-}
-
 var _ = Describe("NewScaffoldCommand", func() {
 	When("NewScaffoldCommand", func() {
 		It("Testing the NewScaffoldCommand", func() {

pkg/cli/alpha/internal/update/helpers/download.go

@@ -0,0 +1,113 @@
+/*
+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 helpers
+
+import (
+	"context"
+	"fmt"
+	"io"
+	log "log/slog"
+	"net/http"
+	"os"
+	"path/filepath"
+	"runtime"
+	"time"
+
+	"github.com/spf13/afero"
+)
+
+const KubebuilderReleaseURL = "https://github.com/kubernetes-sigs/kubebuilder/releases/download/%s/kubebuilder_%s_%s"
+
+func BuildReleaseURL(version string) string {
+	return fmt.Sprintf(KubebuilderReleaseURL, version, runtime.GOOS, runtime.GOARCH)
+}
+
+// DownloadReleaseVersionWith downloads the specified released version from GitHub releases and saves it
+// to a temporary directory with executable permissions.
+// Returns the temporary directory path containing the binary.
+func DownloadReleaseVersionWith(version string) (string, error) {
+	url := BuildReleaseURL(version)
+
+	// Create temp directory
+	fs := afero.NewOsFs()
+	tempDir, err := afero.TempDir(fs, "", "kubebuilder"+version+"-")
+	if err != nil {
+		return "", fmt.Errorf("failed to create temporary directory: %w", err)
+	}
+
+	// Ensure cleanup on any error after this point
+	cleanupOnErr := func() {
+		if rmErr := os.RemoveAll(tempDir); rmErr != nil {
+			log.Error("failed to remove temporary directory", "dir", tempDir, "error", rmErr)
+		}
+	}
+
+	binaryPath := filepath.Join(tempDir, "kubebuilder")
+	f, err := fs.Create(binaryPath)
+	if err != nil {
+		cleanupOnErr()
+		return "", fmt.Errorf("failed to create the binary file: %w", err)
+	}
+	defer func() {
+		if closeErr := f.Close(); closeErr != nil {
+			log.Error("failed to close the binary file", "error", closeErr)
+		}
+	}()
+
+	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
+	defer cancel()
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
+	if err != nil {
+		cleanupOnErr()
+		return "", fmt.Errorf("failed to build download request: %w", err)
+	}
+	req.Header.Set("User-Agent", "kubebuilder-updater/1.0 (+https://github.com/kubernetes-sigs/kubebuilder)")
+
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		cleanupOnErr()
+		return "", fmt.Errorf("failed to download the binary: %w", err)
+	}
+	defer func() {
+		if closeErr := resp.Body.Close(); closeErr != nil {
+			log.Error("failed to close HTTP response body", "error", closeErr)
+		}
+	}()
+
+	if resp.StatusCode != http.StatusOK {
+		cleanupOnErr()
+		return "", fmt.Errorf("failed to download the binary: HTTP %d", resp.StatusCode)
+	}
+
+	if _, err := io.Copy(f, resp.Body); err != nil {
+		cleanupOnErr()
+		return "", fmt.Errorf("failed to write the binary content to file: %w", err)
+	}
+
+	// Flush to disk before changing mode (best effort)
+	if syncErr := f.Sync(); syncErr != nil {
+		log.Warn("failed to sync binary to disk (continuing)", "error", syncErr)
+	}
+
+	if err := os.Chmod(binaryPath, 0o755); err != nil {
+		cleanupOnErr()
+		return "", fmt.Errorf("failed to make binary executable: %w", err)
+	}
+
+	return tempDir, nil
+}