From a9a9c6ba7856394caf106cfab6a4539c3aa82bd0 Mon Sep 17 00:00:00 2001 From: Camila Macedo Date: Sat, 11 Feb 2023 11:22:11 +0000 Subject: [PATCH] :book: design doc with proposal to re-scaffold projects from scratch --- ...er_to_upgrade_projects_by_rescaffolding.md | 154 ++++++++++++++++++ 1 file changed, 154 insertions(+) create mode 100644 designs/helper_to_upgrade_projects_by_rescaffolding.md diff --git a/designs/helper_to_upgrade_projects_by_rescaffolding.md b/designs/helper_to_upgrade_projects_by_rescaffolding.md new file mode 100644 index 00000000000..3b00cf31f24 --- /dev/null +++ b/designs/helper_to_upgrade_projects_by_rescaffolding.md @@ -0,0 +1,154 @@ +| Authors | Creation Date | Status | Extra | +|------------------------------------|---------------|-------------|---| +| @camilamacedo86,@Kavinjsir,@varshaprasad96 | Feb, 2023 | Implementeble | - | + +Experimental Helper to upgrade projects by re-scaffolding +=================== + +This proposal amis 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]. + +## Example + +By running a command like following users would be able to re-scaffold the whole project from the scratch using the +current version of KubeBuilder binary available. + +```shell +kubebuilder alpha generate [OPTIONS] +``` + +## Open Questions + +N/A + +## Summary + +The [PROJECT config][project-config] tracks all configuration and inputs used to create the +project with the CLI. Therefore, a command could be able to read this information and re-run +the same commands with the same data used previously to re-generate the project. + +## Motivation + +The recommended straightforward steps to upgrade the projects are re-scaffold all from scract using the upper +version/plugin and then, re-add all code source on top again. Therefore, this command would help users in +order to minimize the required effort by automating which shows technically possible of this process. + +The main motivation of this proposal is to provide a helper for upgrades and +make less painful this process. Examples: + +- See the discussion [How to regenerate scaffolding?](https://github.com/kubernetes-sigs/kubebuilder/discussions/2864) +- From [slack channel By Paul Laffitte](https://kubernetes.slack.com/archives/CAR30FCJZ/p1675166014762669) + +### 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 +- 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 +- 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) + +## Proposal + +The proposed solution to achieve this goal is to create an alpha command as described +in the example section above, see: + +```shell +kubebuilder alpha generate \ + --from-project-file= + --to= + --backup= + --init-plugins= +``` + +Where: + +- project-file: If not informed then, the command would check it in the current directory +- output: If not informed then, it should be the current repository +- backup: if not informed then, it would be the current path -1 level with the name backup +- init-plugins: if not informed then, it is the same plugin chain available in the layout field + +This command would mainly perform the following operations: + +- 1. Make a backup of the current project +- 2. Ensure that the output path is clean +- 3. Read the [PROJECT config][project-config] +- 4. Re-run all commands using the KubeBuilder binary to recreate the project in the output directory + +### User Stories + +- As a developer I can regenerate my project from the scratch based on all commands that I used the tool to build + my project previously, so that I can easily upgrade my current project to new CLI/plugin versions and get the + latest changes, bug fixes and features +- As a developer I can regenerate my project from the scratch based on all commands that I used the tool to build + my project previously but informing a new init plugin chain, so that I could upgrade my current project to new + layout versions and experiment alpha ones. +- As a KubeBuilder maintainer, I can leverage on this helper to encourage its users to migrate to upper versions more often, making it easier to maintain the project. + +### Implementation Details/Notes/Constraints + +Note that in the [e2e tests](https://github.com/kubernetes-sigs/kubebuilder/tree/master/test/e2e) the binary is used to do the scaffolds. +Also, very similar to the implementation that exist in the integration test KubeBuilder has +a code implementation to re-generate the samples used in the docs and add customizations on top, +for further information check the [hack/docs](https://github.com/kubernetes-sigs/kubebuilder/tree/master/hack/docs). + +This subcommand could have a similar implementation that could be used by the tests and this plugin. +Note that to run the commands using the binaries we are mainly using the following golang implementation: + +```go +cmd := exec.Command(t.BinaryName, Options) +_, err := t.Run(cmd) +``` + +### Risks and Mitigations + +**Hard to keep the command maintained** + +I risk to consider would be we identify that 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. + +### Proof of Concept + +All input data is tracked. Also, as described above we have examples of code implementation +that uses the binary to scaffold the projects. Therefore, the goal of this project seems +very reasonable and achievable. An initial work to try to address this requirement can +be checked in this [pull request](https://github.com/kubernetes-sigs/kubebuilder/pull/3022) + +## 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. + +## Alternatives + +N/A + +## Implementation History + +The idea of automate the re-scaffold of the project is what motivates +us track all input data in to the [project config][project-config] +in the past. We also tracked the [issue](https://github.com/kubernetes-sigs/kubebuilder/issues/2068) +based on discussion that we have to indeed try to add further +specific implementations to do operations per major bumps. For example: + +To upgrade from go/v3 to go/v4 we know exactly what are the changes in the layout +then, we could automate these specific operations as well. However, this first idea is harder yet +to be addressed and maintained. + +[project-config]: https://book.kubebuilder.io/reference/project-config.html \ No newline at end of file