Merge pull request #769 from MHBauer/update-codegen-docs

Create code-generation subsection

1 files changed, 55 insertions, 3 deletions

diff --git a/contributors/devel/api_changes.md b/contributors/devel/api_changes.md
index 63aa0fae..17b41a18 100755
--- a/contributors/devel/api_changes.md
+++ b/contributors/devel/api_changes.md
@@ -462,8 +462,37 @@ generator to create it from scratch.
 Unsurprisingly, adding manually written conversion also requires you to add
 tests to `pkg/api/<version>/conversion_test.go`.
 
-
-## Generate protobuf objects
+## Generate Code 
+
+When any `types.go` change is made, the generated code must be updated
+by running the generators. There are many small generators that
+run. They have some dependencies on each other so they must be run in
+a certain order.
+
+Approximately:
+ - `defaulter-gen`
+ - `deepcopy-gen`
+ - `conversion-gen`
+ - `client-gen`
+ - `lister-gen` which depends upon the output of `client-gen`.
+ - `informer-gen` which depends upon the output of `lister-gen` and `client-gen`.
+ - `openapi-gen`
+ - `codecgen` for fast json serialization with a codec.
+
+
+Many of the generators are based on
+[`gengo`](https://github.com/kubernetes/gengo) and share common
+flags. The `--verify-only` flag will check the existing files on disk
+and fail if they are not what would have been generated.
+
+The generators that create go code have a `--go-header-file` flag
+which should be a file that contains the header that should be
+included. This header is the copyright that should be present at the
+top of the generated file and should be checked with the
+[`repo-infra/verify/verify-boilerplane.sh`](https://github.com/kubernetes/repo-infra/blob/master/verify/verify-boilerplate.sh)
+script at a later stage of the build.
+
+### Generate protobuf objects
 
 For any core API object, we also need to generate the Protobuf IDL and marshallers.
 That generation is done with
@@ -479,7 +508,30 @@ use our own equivalents for JSON serialization. The `pkg/api/serialization_test.
 will verify that your protobuf serialization preserves all fields - be sure to
 run it several times to ensure there are no incompletely calculated fields.
 
-## Edit json (un)marshaling code
+### Generate Clientset
+
+See [this document](generating-clientset.md) specific to generating client sets.
+
+### Generate Listers
+
+`lister-gen` is a tool to generate listers for a client. It requires a
+client generated by `client-gen`.
+
+`lister-gen` requires the `// +genclient=true` annotation on each
+exported type in both the unversioned base `types.go` as well as each
+specifically versioned `types.go`.
+
+`lister-gen` requires the `// +groupName=` annotation on the `doc.go` in
+both the unversioned base directory as well as in each specifically
+versioned directory. The annotation does not have to have any specific
+content, but it does have to exist.
+
+### Generate Informers
+
+`informer-gen` generates the very useful Informers which watch API
+resources for changes. It requires a client generated by `client-gen`.
+
+### Edit json (un)marshaling code
 
 We are auto-generating code for marshaling and unmarshaling json representation
 of api objects - this is to improve the overall system performance.