Merge pull request #136578 from yongruilin/grandtour-codegen-doc

docs: Add comprehensive overview of Kubernetes Code Generator

staging/src/k8s.io/code-generator/docs/DEVELOPMENT.md

@@ -0,0 +1,122 @@
+# Developing Kubernetes Code Generators
+
+## Context
+
+The `k8s.io/code-generator` repository contains a collection of code generators for Kubernetes-style API types. These generators are essential for building Kubernetes controllers, custom resource definitions (CRDs), and aggregated API servers. They automate the creation of boilerplate code required to interact with the Kubernetes API machinery, ensuring consistency and reducing manual toil.
+
+## Background & History
+
+This repository is synced from the main Kubernetes repository (`kubernetes/kubernetes`). Changes are typically made in the upstream `staging/src/k8s.io/code-generator` directory within `kubernetes/kubernetes` and then published here.
+
+Historically, writing Kubernetes controllers involved writing significant amounts of boilerplate code for watching resources, maintaining local caches, and implementing client logic. The code generators were developed to mechanize this process, relying on Go struct tags (comment annotations) to drive the generation logic.
+
+## Technical Architecture
+
+The generators are built on top of `k8s.io/gengo`, a framework for generating code parsing Go files. The general flow is:
+
+1.  **Parsing:** The tools parse Go source files containing API type definitions (structs).
+2.  **Tag Extraction:** They look for specific comment tags (e.g., `// +genclient`, `// +k8s:deepcopy-gen=true`) to identify which types require code generation and how they should be processed.
+3.  **Generation:** Based on the tags and types, the tools generate Go code (and sometimes other formats like Protobuf IDL) using templates.
+
+### Key Concepts
+
+*   **Input:** Go packages containing API type definitions (typically in `pkg/apis/<group>/<version>`).
+*   **Tags:** Magic comments that control generation.
+*   **Output:** Generated Go files, often named `zz_generated.<generator>.go` or placed in specific subdirectories like `clientset`, `informers`, and `listers`.
+
+## Internal Mechanics & Development
+
+Based on maintainer insights (including notes from 2025/03/27), here are common patterns and strategies used when working with or developing these generators.
+
+### Debugging Strategy
+Debugging generators against a full codebase can be noisy. A common practice is to create a small, isolated test case:
+*   **Isolation:** Use a package name like `_hack` (prefixed with an underscore so it's ignored by default Go processes).
+*   **Targeted Execution:** Invoke the generator specifically against this package to step through logic in a debugger without processing every API group.
+
+### Two-Phase Execution
+Most generators follow a two-phase architecture:
+1.  **Discovery:** Recursively traversing the type tree to build a graph of types and fields.
+    *   **Root Types:** The tool scans packages for "root types" (entry points) based on specific tags (e.g., in `doc.go`) or the presence of `TypeMeta`.
+    *   **Graph Building:** It builds a graph of "Type Nodes" (the type itself) and "Child Nodes" (fields/instances).
+    *   **Early Filtering:** Unsupported cases are filtered out early during discovery. Examples include:
+        *   Pointers to pointers (`**T`)
+        *   Slices of pointers (`[]*T`)
+        *   Non-exported fields
+2.  **Generation (Emit):** Iterating over the discovered graph to produce Go code.
+
+### The "Call Frame" Pattern
+You will often see generated code wrapped in anonymous functions. This pattern is used to:
+*   **Simplify Scoping:** It allows the variable for the object at each recursive level to always be called `obj`, rather than tracking long chains like `obj.Spec.Template.Spec`.
+*   **Easy Short-Circuiting:** It enables early returns (e.g., if an optional field is nil) without complex nested `if/else` logic in the main function body.
+
+## The Generators
+
+The repository contains several specific generators, each located in `cmd/`:
+
+### 1. `client-gen`
+Generates typed clientsets for API groups.
+*   **Input:** API types tagged with `// +genclient`.
+*   **Output:** A `clientset` Go package providing easy-to-use methods for CRUD operations on resources.
+
+### 2. `lister-gen`
+Generates "Listers" for API resources.
+*   **Purpose:** Listers provide a read-only interface to access data from a local cache (Informer), avoiding expensive API server calls.
+
+### 3. `informer-gen`
+Generates "Informers" for API resources.
+*   **Purpose:** Informers watch the API server for changes and update a local cache (Store). They connect the Client to the Lister and allow registering event handlers.
+
+### 4. `deepcopy-gen`
+Generates `DeepCopy` methods for API types.
+*   **Purpose:** Kubernetes API objects are often passed by pointer. `DeepCopy` ensures that modifying an object in one part of the code (e.g., a cache) doesn't affect others.
+
+### 5. `defaulter-gen`
+Generates defaulting functions based on `// +default` tags.
+
+### 6. `conversion-gen`
+Generates conversion functions between different API versions (e.g., `v1` to `v1beta1`). Essential for the API server's internal hub model.
+
+### 7. `applyconfiguration-gen`
+Generates types for Server-Side Apply patches, allowing fields to be explicitly omitted.
+
+### 8. `register-gen`
+Generates registration code to make types known to the Kubernetes runtime Scheme.
+
+### 9. `go-to-protobuf`
+Generates Protobuf IDL and marshaling code for efficient communication.
+
+### 10. `prerelease-lifecycle-gen`
+Generates code that tracks API introduction, deprecation, and removal versions.
+
+### 11. `validation-gen`
+Generates validation logic based on struct tags.
+*   **Context:** Detailed walk-throughs have highlighted this tool to assist with upcoming "Ratcheting" features (checking if a field changed between versions).
+*   **Root Types:** Processes types identified as roots (often having `TypeMeta`).
+*   **Plugin Architecture:** Uses a plugin system for tag validators. Some tags are "late tags" that depend on shared state from previous tags (e.g., `listMap` validation).
+*   **Strict Rules:** Enforces patterns like requiring pointers for `optional` fields.
+
+## Usage
+
+The recommended way to invoke these generators is using the wrapper script `kube_codegen.sh` located in the root of this repository. This script orchestrates the execution of the individual generators with standard conventions.
+
+Example:
+
+```bash
+source "${CODEGEN_PKG}/kube_codegen.sh"
+
+kube::codegen::gen_helpers \
+    --boilerplate "${SCRIPT_ROOT}/hack/boilerplate.go.txt" \
+    "${SCRIPT_ROOT}/apis"
+
+kube::codegen::gen_client \
+    --with-watch \
+    --with-applyconfig \
+    --output-dir "${SCRIPT_ROOT}/pkg/client" \
+    --output-pkg "github.com/example/project/pkg/client" \
+    --boilerplate "${SCRIPT_ROOT}/hack/boilerplate.go.txt" \
+    "${SCRIPT_ROOT}/apis"
+```
+
+## Contributing
+
+Please refer to [CONTRIBUTING.md](../CONTRIBUTING.md) for guidelines on how to contribute. Remember that changes should generally be made in the `kubernetes/kubernetes` repository and not directly here.