improve and apply suggestions

designs/helper_to_upgrade_projects_by_rescaffolding.md

@@ -1,11 +1,11 @@
 | Authors                            | Creation Date | Status      | Extra |
 |------------------------------------|---------------|-------------|---|
-| @camilamacedo86,@Kavinjsir,@varshaprasad96 | Feb, 2023     | Implementeble | - |
+| @camilamacedo86,@Kavinjsir,@varshaprasad96 | Feb, 2023     | Implementable | - |
 
 Experimental Helper to upgrade projects by re-scaffolding
 ===================
 
-This proposal amis to provide a new alpha command with a helper which
+This proposal aims to provide a new alpha command with a helper which
 would be able to re-scaffold the project from the scratch based on
 the [PROJECT config][project-config].
 
@@ -18,6 +18,36 @@ current version of KubeBuilder binary available.
 kubebuilder alpha generate [OPTIONS]
 ```
 
+### Workflows
+
+Following some examples of the workflows
+
+**To update the project with minor changes provided**
+
+See that for each KubeBuilder release the plugins versions used to scaffold
+the projects might have bug fixes and new incremental features added to the
+templates which will result in changes to the files that are generated by
+the tool for new projects.
+
+In this case, you used previously the tool to generate the project
+and now would like to update your project with the latest changes
+provided for the same plugin version. Therefore, you will need to:
+
+- Download and install KubeBuilder binary ( latest / upper release )
+- You will run the command in the root directory of your project: `kubebuilder alpha generate`
+- Then, the command will remove the content of your local directory and re-scaffold the project from the scratch
+- It will allow you to compare your local branch with the remote branch of your project to re-add the code on top OR
+if you do not use the flag `--no-backup` then you can compare the local directory with the copy of your project 
+copied to the path `.backup/project-name/` before the re-scaffold be done.
+- Therefore, you can run make all and test the final result. You will have after all your project updated.
+
+**To update the project with major changes provided**
+
+In this case, you are looking for to migrate the project from, for example,
+`go/v3` to `go/v4`. The steps are very similar to the above ones. However,
+in this case you need to inform the plugin that you want to use to do the scaffold
+from scratch `kubebuilder alpha generate --plugins=go/v4`.
+
 ## Open Questions
 
 N/A
@@ -44,18 +74,18 @@ make less painful this process. Examples:
 ### Goals
 
 - Help users upgrade their project with the latest changes
-- Help users to re-scaffold the projects from the scratch based on what was done previously with the tool
+- Help users to re-scaffold projects from scratch based on what was done previously with the tool
 - Make less painful the process to upgrade
 
 ### Non-Goals
 
 - Change the default layout or how the KubeBuilder CLI works
 - Deal with customizations or deviations from the proposed layout
-- Be able to perform the project upgrade to the latest changes without human bean interactions
+- Be able to perform the project upgrade to the latest changes without human interactions
 - Deal and support external plugins
 - Provides support to [declarative](https://book.kubebuilder.io/plugins/declarative-v1.html) plugin
   since it is desired and planned to decouple this solution and donate this plugin to its own authors [More info](https://github.com/kubernetes-sigs/kubebuilder/issues/3186)
-- Provide support old version prior we have the Project config (Kubebuilder < 3x) and the go/v2 layout which exist to ensure  a backwards compatibility with legacy layout provide by Kubebuilder 2x
+- Provide support to older version before having the Project config (Kubebuilder < 3x) and the go/v2 layout which exists to ensure  a backwards compatibility with legacy layout provided by Kubebuilder 2x
 
 ## Proposal
 
@@ -66,25 +96,32 @@ in the example section above, see:
 kubebuilder alpha generate \
     --from=<path of the project file> 
     --to=<path where the project should be re-scaffold> 
-    --backup=<path-where the current version of the project should be copied as backup>
+    --no-backup
+    --backup-path=<path-where the current version of the project should be copied as backup>
     --plugins=<chain of plugins key that can be used to create the layout with init sub-command>
-```
 
 Where:
 
-- from: [Optional] If not informed then, the command would check it in the current directory
-- to: [Optional] If not informed then, it should be the current repository
-- backup: [Optional] If not informed then, the backup by copying the project to a new directory would not be made
+- from: [Optional] If not informed then, by default it is the current directory (project directory). If the `PROJECT` file does not exist then it will fail.
+- to: [Optional] If not informed then, it should be the current repository.
+- no-backup: [Optional] If not informed then, the current directory should be copied to the path `.backup/project-name` 
+- backup: [Optional] If not informed then, the backup will be copied to the the path `.backup/project-name` 
 - plugins:  [Optional] If not informed then, it is the same plugin chain available in the layout field
+- binary: [Optional] If not infomed then, the command will use KubeBuilder binary installed globaly. 
 
 This command would mainly perform the following operations:
 
 - 1. Check the flags
 - 2. If the backup flag be used, then check if is a valid path and make a backup of the current project
-- 3. Ensure that the output path is clean
+- 3. Copy the whole current directory to `.backup/project-name`
+- 4. Ensure that the output path is clean. By default it is the current directory project where the project was scaffolded previously and it should be cleaned up before to do the re-scaffold. 
+Only the content under `.backup/project-name` should be kept.
 - 4. Read the [PROJECT config][project-config]
 - 5. Re-run all commands using the KubeBuilder binary to recreate the project in the output directory
 
+Note that the backup created in the current directory must be prefixed with `.`. Otherwise the tool
+will not able to perform the scaffold to create a new project from the scratch.
+
 ### User Stories
 
 **As an Operator author:**
@@ -123,16 +160,16 @@ _, err := t.Run(cmd)
 
 **Hard to keep the command maintained**
 
-I risk to consider would be we identify that would be hard to keep this command maintained
+A risk to consider is that it would be hard to keep this command maintained
 because we need to develop specific code operations for each plugin. The mitigation for
 this problem could be developing a design more generic that could work with all plugins.
 
 However, initially a more generic design implementation does not appear to be achievable and
 would be considered out of the scope of this proposal (no goal). It should to be considered
 as a second phase of this implementation.
 
-Therefore, the current achievable mitigation in place is that KubeBuilder has a policy of
-does not provide official support and distributed many plugins within for the same reasons.
+Therefore, the current achievable mitigation in place is that KubeBuilder's  policy of not providing official 
+support of maintaining and distributing many plugins.
 
 ### Proof of Concept
 
@@ -144,8 +181,7 @@ be checked in this [pull request](https://github.com/kubernetes-sigs/kubebuilder
 ## Drawbacks
 
 - If the value that feature provides does not pay off the effort to keep it
-  maintained then we would need to drawback.
-- If a better suggestion solution to address the need be proposed.
+  maintained, then we would need to deprecate and remove the feature in the long term.
 
 ## Alternatives
 
@@ -163,4 +199,10 @@ To upgrade from go/v3 to go/v4 we know exactly what are the changes in the layou
 then, we could automate these specific operations as well. However, this first idea is harder yet
 to be addressed and maintained.
 
+## Future Vision
+
+We could use it to do cool future features such as creating a GitHub action which would push-pull requests against the project repositories to help users be updated with, for example, minor changes. By using this command, we might able to git clone the project and to do a new scaffold and then use some [git strategy merge](https://www.geeksforgeeks.org/merge-strategies-in-git/) to result in a PR to purpose the required changes.
+
+We probably need to store the CLI tool tag release used to do the scaffold to persuade this idea. So that we can know if the project requires or not updates.
+
 [project-config]: https://book.kubebuilder.io/reference/project-config.html