Skip to content

Commit a9ba582

Browse files
authored
Merge pull request #3602 from camilamacedo86/doc-rescaffold
📖 supplement doc over alpha generate command
2 parents de247ec + 803ae01 commit a9ba582

File tree

3 files changed

+49
-4
lines changed

3 files changed

+49
-4
lines changed

docs/book/src/SUMMARY.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -74,6 +74,8 @@
7474
- [Migration by updating the files](migration/manually_migration_guide_gov3_to_gov4.md)
7575
- [Single Group to Multi-Group](./migration/multi-group.md)
7676

77+
- [Project Upgrade Assistant](./reference/rescaffold.md)
78+
7779
---
7880

7981
- [Reference](./reference/reference.md)

docs/book/src/migration/migration_guide_gov3_to_gov4.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,16 @@ The recommended way to migrate a `go/v3` project is to create a new `go/v4` proj
1010
copy over the API and the reconciliation code. The conversion will end up with a
1111
project that looks like a native go/v4 project layout (latest version).
1212

13+
<aside class="note warning">
14+
<h1>Your Upgrade Assistant: The `alpha generate` command</h1>
15+
16+
To upgrade your project you might want to use the command `kubebuilder alpha generate [OPTIONS]`.
17+
This command will re-scaffold the project using the current Kubebuilder version.
18+
You can run `kubebuilder alpha generate --plugins=go/v4` to regenerate your project using `go/v4`
19+
based in your [PROJECT][project-file] file config.
20+
21+
</aside>
22+
1323
However, in some cases, it's possible to do an in-place upgrade (i.e. reuse the go/v3 project layout, upgrading
1424
the PROJECT file, and scaffolds manually). For further information see [Migration from go/v3 to go/v4 by updating the files manually][manually-upgrade]
1525

@@ -148,3 +158,4 @@ fine.
148158
[controller-runtime]: https://github.com/kubernetes-sigs/controller-runtime/releases
149159
[multi-group]: multi-group.md
150160
[manually-upgrade]: manually_migration_guide_gov3_to_gov4.md
161+
[project-file]: ../reference/project-config.md

docs/book/src/reference/rescaffold.md

Lines changed: 36 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,30 @@
1-
# Rescaffold Command
1+
# Project Upgrade Assistant
22

33
## Overview
44

5-
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.
5+
Please note that all input utilized via the Kubebuilder tool is tracked in the PROJECT file ([example][example]).
6+
This file is responsible for storing essential information, representing various facets of the Project such as its layout,
7+
plugins, APIs, and more. ([More info][more-info]).
8+
9+
With the release of new plugin versions/layouts or even a new Kubebuilder CLI version with scaffold changes,
10+
an easy way to upgrade your project is by re-scaffolding. This process allows users to employ tools like IDEs to compare
11+
changes, enabling them to overlay their code implementation on the new scaffold or integrate these changes into their existing projects.
612

713
## When to use it ?
814

9-
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.
15+
This command is useful when you want to upgrade an existing project to the latest version of the Kubebuilder project layout.
16+
It makes it easier for the users to migrate their operator projects to the new scaffolding.
1017

1118
## How to use it ?
1219

20+
**To upgrade the scaffold of your project to use a new plugin version:**
21+
22+
```sh
23+
kubebuilder alpha generate --plugins="pluginkey/version"
24+
```
25+
26+
**To upgrade the scaffold of your project to get the latest changes:**
27+
1328
Currently, it supports two optional params, `input-dir` and `output-dir`.
1429

1530
`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`.
1833

1934
```sh
2035
kubebuilder alpha generate --input-dir=/path/to/existing/project --output-dir=/path/to/new/project
21-
```
36+
```
37+
38+
<aside class="note warning">
39+
<h1>Regarding `input-dir` and `output-dir`:</h1>
40+
41+
If neither `input-dir` nor `output-dir` are specified, the project will be regenerated in the current directory.
42+
This approach facilitates comparison between your current local branch and the version stored upstream (e.g., GitHub main branch).
43+
This way, you can easily overlay your project's code changes atop the new scaffold.
44+
45+
</aside>
46+
47+
## Further Resources:
48+
49+
- Check out [video to show how it works](https://youtu.be/7997RIbx8kw?si=ODYMud5lLycz7osp)
50+
- See the [desing proposal documentation](../../../../designs/helper_to_upgrade_projects_by_rescaffolding.md)
51+
52+
[example]: ./../../../../testdata/project-v4-with-deploy-image/PROJECT
53+
[more-info]: ./../reference/project-config.md

0 commit comments

Comments
 (0)