diff --git a/contributors/devel/api_changes.md b/contributors/devel/api_changes.md index 63aa0faee..17b41a18e 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//conversion_test.go`. +## Generate Code -## Generate protobuf objects +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.