Merge pull request #5415 from yuwenma/unify-api

docs: unify api, mapper and fuzzer

Author: google-oss-prow[bot]

docs/ai/unify-api-mapper-fuzzer.md

@@ -0,0 +1,111 @@
+# How to Unify API Mappers and Fuzzers for Existing Resources
+
+This guide provides a step-by-step process for refactoring and unifying the API, mapper, and fuzzer for existing resources. The goal is to leverage the auto-generation tools as much as possible, reduce manual code, and ensure consistency across different API versions.
+
+## 1. Start with `generate.sh`
+
+The unification process begins with the `generate.sh` script located in the `apis/<service>/<version>` directory (e.g., `apis/dataproc/v1alpha1/`). This script is the source of truth for the auto-generation process.
+
+### Verify and Correct `generate.sh`
+
+1.  **Check for Existence**: Ensure a `generate.sh` script exists for each version of the service you are unifying (e.g., `v1alpha1`, `v1beta1`). If it doesn't exist, create one using a known good example like `apis/bigquerybiglake/v1alpha1/generate.sh` as a template.
+
+2.  **Verify Resource List**: Open the `generate.sh` script and check the `--resource` flags in the `go run . generate-types` command. This list should accurately reflect all the resources defined within that API version directory. Add or remove `--resource` flags as necessary.
+
+3.  **Check Output Directory**: Ensure the final `go run ... goimports` command is writing to the correct controller directory, which should be `pkg/controller/direct/<service>/`.
+
+A corrected `generate.sh` for a `v1alpha1` service might look like this:
+
+```bash
+#!/bin/bash
+# ... (license header)
+set -o errexit
+set -o nounset
+set -o pipefail
+
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+cd ${REPO_ROOT}/dev/tools/controllerbuilder
+
+go run . generate-types \
+    --service google.cloud.myservice.v1 \
+    --api-version "myservice.cnrm.cloud.google.com/v1alpha1" \
+    --resource MyResourceOne:ResourceOne \
+    --resource MyResourceTwo:ResourceTwo
+
+go run . generate-mapper \
+    --service google.cloud.myservice.v1 \
+    --api-version "myservice.cnrm.cloud.google.com/v1alpha1"
+
+cd ${REPO_ROOT}
+dev/tasks/generate-crds
+
+go run -mod=readonly golang.org/x/tools/cmd/goimports@latest -w pkg/controller/direct/myservice/
+```
+
+## 2. Rely on Auto-Generated Mappers
+
+The primary goal of unification is to remove as much manual mapping logic as possible and rely on the code generated by `generate-mapper`.
+
+1.  **Run `generate.sh`**: Execute the script for each API version you are unifying. This will create or update the `types.mapper.go` file in the controller directory (`pkg/controller/direct/<service>/`).
+
+2.  **Identify Manual Mappers**: Look for manually written mapper functions in files like `<resource>_mapper.go`. These are the functions you want to replace.
+
+3.  **Replace with Generated Functions**: Update your controller and fuzzer code to call the new, auto-generated functions from `types.mapper.go` instead of the old manual ones.
+
+4.  **Delete Old Code**: Once all references to the manual mapper functions have been removed, you can delete the `<resource>_mapper.go` file or remove the now-unused functions from it.
+
+## 3. Handling Multi-Version Services
+
+When a service has multiple API versions (e.g., `v1alpha1` and `v1beta1`), the mapper needs to handle potential differences in the resource schemas.
+
+### Use the `--multiversion` Flag
+
+For the newer version of the API (e.g., `v1beta1`), add the `--multiversion` flag to the `generate-mapper` command in its `generate.sh` script.
+
+Example for `apis/myservice/v1beta1/generate.sh`:
+```bash
+# ...
+go run . generate-mapper \
+    --multiversion \
+    --service google.cloud.myservice.v1 \
+    --api-version "myservice.cnrm.cloud.google.com/v1beta1"
+# ...
+```
+
+When this flag is used, the generator will create version-specific mapping functions to avoid conflicts. The function names will have the version injected into their name, for example:
+*   `MyResourceSpec_v1beta1_ToProto(...)`
+*   `MyResourceSpec_v1alpha1_FromProto(...)`
+
+**Note**: If the `--multiversion` flag is *not* used (typically for services with only one version), the generated function names will **not** have a version in them (e.g., `MyResourceSpec_ToProto(...)`).
+
+## 4. Update Fuzzer and Controller Code
+
+After re-generating the mappers, you must update your fuzzer and controller files to use the correct function names.
+
+1.  **Ensure Fuzzer File Exists**: Ensure each CRD being unified has a corresponding `_fuzzer.go` file. If one does not exist, create it by copying from a similar resource and adapting it.
+
+2.  **Update `*_fuzzer.go`**: Go to `pkg/controller/direct/<service>/<resource>_fuzzer.go` and update the `fuzztesting.NewKRMTypedFuzzer` call to use the new generated function names.
+
+    *   If you used `--multiversion`, the names will be version-specific.
+    *   If you did not use `--multiversion`, the names will be generic.
+
+    **Example with `--multiversion`:**
+    ```go
+    // For the v1beta1 fuzzer
+    f := fuzztesting.NewKRMTypedFuzzer(&pb.MyResource{},
+        MyResourceSpec_v1beta1_FromProto, MyResourceSpec_v1beta1_ToProto,
+        MyResourceObservedState_v1beta1_FromProto, MyResourceObservedState_v1beta1_ToProto,
+    )
+    ```
+
+    **Example without `--multiversion`:**
+    ```go
+    f := fuzztesting.NewKRMTypedFuzzer(&pb.MyResource{},
+        MyResourceSpec_FromProto, MyResourceSpec_ToProto,
+        MyResourceObservedState_FromProto, MyResourceObservedState_ToProto,
+    )
+    ```
+
+3.  **Update `*_controller.go`**: Search for any remaining usages of the old function names in your controller logic (`pkg/controller/direct/<service>/<resource>_controller.go`) and update them to point to the new generated functions.
+
+By following these steps, you can systematically unify the API definitions, mappers, and fuzzers for existing resources, leading to a more maintainable and consistent codebase.