Merge pull request #3602 from camilamacedo86/doc-rescaffold

📖 supplement doc over alpha generate command

docs/book/src/SUMMARY.md

@@ -74,6 +74,8 @@
       - [Migration by updating the files](migration/manually_migration_guide_gov3_to_gov4.md)
   - [Single Group to Multi-Group](./migration/multi-group.md)
 
+- [Project Upgrade Assistant](./reference/rescaffold.md)
+
 ---
 
 - [Reference](./reference/reference.md)

docs/book/src/migration/migration_guide_gov3_to_gov4.md

@@ -10,6 +10,16 @@ The recommended way to migrate a `go/v3` project is to create a new `go/v4` proj
 copy over the API and the reconciliation code. The conversion will end up with a
 project that looks like a native go/v4 project layout (latest version).
 
+<aside class="note warning">
+<h1>Your Upgrade Assistant: The `alpha generate` command</h1>
+
+To upgrade your project you might want to use the command `kubebuilder alpha generate [OPTIONS]`.
+This command will re-scaffold the project using the current Kubebuilder version. 
+You can run `kubebuilder alpha generate --plugins=go/v4` to regenerate your project using `go/v4` 
+based in your [PROJECT][project-file] file config. 
+
+</aside>
+
 However, in some cases, it's possible to do an in-place upgrade (i.e. reuse the go/v3 project layout, upgrading
 the PROJECT file, and scaffolds manually). For further information see [Migration from go/v3 to go/v4 by updating the files manually][manually-upgrade]
 
@@ -148,3 +158,4 @@ fine.
 [controller-runtime]: https://github.com/kubernetes-sigs/controller-runtime/releases
 [multi-group]: multi-group.md
 [manually-upgrade]: manually_migration_guide_gov3_to_gov4.md
+[project-file]: ../reference/project-config.md

docs/book/src/reference/rescaffold.md

@@ -1,15 +1,30 @@
-# Rescaffold Command
+# Project Upgrade Assistant
 
 ## Overview
 
-The Kubebuilder CLI provides a new experimental helper `alpha generate` command to re-scaffold an existing project from the scratch using the current version of KubeBuilder binary available based on PROJECT config file. 
+Please note that all input utilized via the Kubebuilder tool is tracked in the PROJECT file ([example][example]). 
+This file is responsible for storing essential information, representing various facets of the Project such as its layout, 
+plugins, APIs, and more. ([More info][more-info]).
+
+With the release of new plugin versions/layouts or even a new Kubebuilder CLI version with scaffold changes, 
+an easy way to upgrade your project is by re-scaffolding. This process allows users to employ tools like IDEs to compare 
+changes, enabling them to overlay their code implementation on the new scaffold or integrate these changes into their existing projects.
 
 ## When to use it ?
 
-This command is useful when you want to upgrade an existing project to the latest version of the Kubebuilder project layout. It makes it easier for the users to migrate their operator projects to the new scaffolding.
+This command is useful when you want to upgrade an existing project to the latest version of the Kubebuilder project layout. 
+It makes it easier for the users to migrate their operator projects to the new scaffolding.
 
 ## How to use it ?
 
+**To upgrade the scaffold of your project to use a new plugin version:**
+
+```sh
+kubebuilder alpha generate --plugins="pluginkey/version"
+```
+
+**To upgrade the scaffold of your project to get the latest changes:**
+
 Currently, it supports two optional params, `input-dir` and `output-dir`. 
 
 `input-dir` is the path to the existing project that you want to re-scaffold. Default is the current working directory.
@@ -18,4 +33,21 @@ Currently, it supports two optional params, `input-dir` and `output-dir`.
 
 ```sh
 kubebuilder alpha generate --input-dir=/path/to/existing/project --output-dir=/path/to/new/project
-```
+```
+
+<aside class="note warning">
+<h1>Regarding `input-dir` and `output-dir`:</h1>
+
+If neither `input-dir` nor `output-dir` are specified, the project will be regenerated in the current directory. 
+This approach facilitates comparison between your current local branch and the version stored upstream (e.g., GitHub main branch). 
+This way, you can easily overlay your project's code changes atop the new scaffold.
+
+</aside>
+
+## Further Resources:
+
+- Check out [video to show how it works](https://youtu.be/7997RIbx8kw?si=ODYMud5lLycz7osp)
+- See the [desing proposal documentation](../../../../designs/helper_to_upgrade_projects_by_rescaffolding.md)
+
+[example]: ./../../../../testdata/project-v4-with-deploy-image/PROJECT
+[more-info]: ./../reference/project-config.md