From 7711b8f84067ff04fe4dc5dc0213c76bb8e9d14a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Juan-Luis=20de=20Sousa-Valadas=20Casta=C3=B1o?=
 <jvaladas@mirantis.com>
Date: Wed, 10 May 2023 16:01:48 +0200
Subject: [PATCH] doc: Fix multigroup migration guide for v4
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Varsha <varshaprasad96@gmail.com>
Co-authored-by: Camila Macedo <7708031+camilamacedo86@users.noreply.github.com>
Signed-off-by: Juan-Luis de Sousa-Valadas Castaño <jvaladas@mirantis.com>
---
 docs/book/src/migration/multi-group.md | 108 ++++++++++++++-----------
 1 file changed, 63 insertions(+), 45 deletions(-)

diff --git a/docs/book/src/migration/multi-group.md b/docs/book/src/migration/multi-group.md
index fd6a15266c..6fcd1cd4aa 100644
--- a/docs/book/src/migration/multi-group.md
+++ b/docs/book/src/migration/multi-group.md
@@ -4,32 +4,32 @@
 
 <h1>Note</h1>
 
-Multi-group scaffolding support was not present in the initial version of
-the Kubebuilder v2 scaffolding (as of Kubebuilder v2.0.0).
+While Kubebuilder will not scaffold out a project structure compatible
+with multiple API groups in the same repository by default, it's possible
+to modify the default project structure to support it.
 
-To change the layout of your project to support Multi-Group run the command
-`kubebuilder edit --multigroup=true`. Once you switch to a multi-group layout, the new Kinds
-will be generated in the new layout but additional manual work is needed 
-to move the old API groups to the new layout.
+Note that the process mainly is to ensure that your  API(s) and controller(s) will be moved under new directories with their respective group name.
 
 </aside>
 
-While Kubebuilder v2 will not scaffold out a project structure compatible
-with multiple API groups in the same repository by default, it's possible
-to modify the default project structure to support it.
-
 Let's migrate the [CronJob example][cronjob-tutorial].
 
 <aside class="note warning">
-<h1>Using go/v4</h1>
+<h1>Instructions vary per project layout</h1>
+
+You can verify the version by looking at the PROJECT file. The currently default and
+recommended version is go/v4.
 
-If you create your project using go/v4 plugin (you can verify it by looking at the PROJECT file )
-then, all steps are the same but you need to keep in mind that the api and controllers directory
-path is now under the `pkg` directory instead. So, you need ensure that you update the
-paths accordingly.
+The layout go/v3 is **deprecated**, if you are using go/v3 it is recommended that you migrate to
+go/v4, however this documentation is still valid. [Migration from go/v3 to go/v4][migration-guide].
 
 </aside>
 
+To change the layout of your project to support Multi-Group run the command
+`kubebuilder edit --multigroup=true`. Once you switch to a multi-group layout, the new Kinds
+will be generated in the new layout but additional manual work is needed
+to move the old API groups to the new layout.
+
 Generally, we use the prefix for the API group as the directory name. We
 can check `api/v1/groupversion_info.go` to find that out:
 
@@ -38,58 +38,75 @@ can check `api/v1/groupversion_info.go` to find that out:
 package v1
 ```
 
-Then, we'll rename `api` to `apis` to be more clear, and we'll move our
-existing APIs into a new subdirectory, "batch":
+Then, we'll rename move our existing APIs into a new subdirectory, "batch":
 
 ```bash
-mkdir apis/batch
-mv api/* apis/batch
-# After ensuring that all was moved successfully remove the old directory `api/`
-rm -rf api/ 
+mkdir api/batch
+mv api/* api/batch
 ```
 
-
-After moving the APIs to a new directory, the same needs to be applied to the controllers:
+After moving the APIs to a new directory, the same needs to be applied to the controllers. For go/v4:
 
 ```bash
-mkdir controllers/batch
-mv controllers/* controllers/batch/
+mkdir internal/controller/batch
+mv internal/controller/* internal/controller/batch/
 ```
 
+<aside class="note">
+<h1>If you are using the deprecated layout go/v3</h1>
+Then, your layout has not the internal directory. So, you will move the controller(s) under a directory with the name of the API group which it is responsible for manage.
+```bash
+mkdir controller/batch
+mv controller/* controller/batch/
+```
 
-
-Next, we'll need to update all the references to the old package name. 
-For CronJob, that'll be `main.go` and `controllers/batch/cronjob_controller.go`. 
+Next, we'll need to update all the references to the old package name.
+For CronJob, the paths to be replaced would be `main.go` and `controllers/batch/cronjob_controller.go` to their respective locations in the new project structure.
 
 If you've added additional files to your project, you'll need to track down
 imports there as well.
 
-Finally, we'll run the command which enable the multi-group layout in the project:
+Finally, fix the PROJECT file manually, the command `kubebuilder edit --multigroup=true`
+sets our project to multigroup, but it doesn't fix the path of the existing APIs.
+For each resource we need to modify the path.
 
-```
-kubebuilder edit --multigroup=true
-```
+For instance, for a file:
 
-When the command `kubebuilder edit --multigroup=true` is executed it will add a new line 
-to `PROJECT` that marks this a multi-group project:
-                                                      
 ```yaml
-version: "2"
+# Code generated by tool. DO NOT EDIT.
+# This file is used to track the info used to scaffold your project
+# and allow the plugins properly work.
+# More info: https://book.kubebuilder.io/reference/project-config.html
 domain: tutorial.kubebuilder.io
-repo: tutorial.kubebuilder.io/project
+layout:
+- go.kubebuilder.io/v4
 multigroup: true
+projectName: test
+repo: tutorial.kubebuilder.io/project
+resources:
+- api:
+    crdVersion: v1
+    namespaced: true
+  controller: true
+  domain: tutorial.kubebuilder.io
+  group: batch
+  kind: CronJob
+  path: tutorial.kubebuilder.io/project/api/v1beta1
+  version: v1beta1
+version: "3"
 ```
 
-Note that this option indicates to Kubebuilder that this is a multi-group project. 
+Replace `path: tutorial.kubebuilder.io/project/api/v1beta1` for
+`path: tutorial.kubebuilder.io/project/api/batch/v1beta1`
+
+In this process, if the project is not new and has previous implemented APIs they would still need to be modified as needed.
+Notice that with the `multi-group` project the Kind API's files are created under `api/<group>/<version>` instead of `api/<version>`.
+Also, note that the controllers will be created under `internal/controller/<group>` instead of `internal/controller`.
 
-In this way, if the project is not new and has previous APIs already implemented will be in the previous structure. 
-Notice that with the `multi-group` project the Kind API's files are
-created under `apis/<group>/<version>` instead of `api/<version>`. 
-Also, note that the controllers will be created under `controllers/<group>` instead of `controllers`. 
-That is the reason why we moved the previously generated APIs with the provided scripts in the previous steps. 
-Remember to update the references afterwards.
+That is the reason why we moved the previously generated APIs to their respective locations in the new structure.
+Remember to update the references in imports accordingly.
 
-For envtest to install CRDs correctly into the test environment, the relative path to the CRD directory needs to be updated accordingly in each `controllers/<group>/suite_test.go` file. We need to add additional `".."` to our CRD directory relative path as shown below.
+For envtest to install CRDs correctly into the test environment, the relative path to the CRD directory needs to be updated accordingly in each `internal/controller/<group>/suite_test.go` file. We need to add additional `".."` to our CRD directory relative path as shown below.
 
 ```go
     By("bootstrapping test environment")
@@ -104,3 +121,4 @@ single-group projects).
 
 [multi-group-issue]: https://github.com/kubernetes-sigs/kubebuilder/issues/923 "Kubebuilder Issue #923"
 [cronjob-tutorial]: /cronjob-tutorial/cronjob-tutorial.md "Tutorial: Building CronJob"
+[migration-guide]: /migration/migration_guide_gov3_to_gov4.md "Migration from go/v3 to go/v4"