diff options
| author | Daniel Smith <dbsmith@google.com> | 2015-09-09 16:01:08 -0700 |
|---|---|---|
| committer | Daniel Smith <dbsmith@google.com> | 2015-09-11 16:06:10 -0700 |
| commit | acb2ce01b3f5000553d4cc407efcd046cb5c46de (patch) | |
| tree | 950cc6ca86de69851a6ca0705e7e0eb7dd5c9bba /api_changes.md | |
| parent | 2e6e7c4cf92416c9554e43f9c92df60ee9dde101 (diff) | |
Fix tooling for apis/experimental's new home
* fix package name
* add a script to auto-gofmt everything, useful after grep/sed incantations
* update conversion/deep copy generation
* doc update
Diffstat (limited to 'api_changes.md')
| -rw-r--r-- | api_changes.md | 27 |
1 files changed, 22 insertions, 5 deletions
diff --git a/api_changes.md b/api_changes.md index 45f0dd4c..e0a65fe0 100644 --- a/api_changes.md +++ b/api_changes.md @@ -38,7 +38,7 @@ with a number of existing API types and with the [API conventions](api-conventions.md). If creating a new API type/resource, we also recommend that you first send a PR containing just a proposal for the new API types, and that you initially target -the experimental API (pkg/expapi). +the experimental API (pkg/apis/experimental). The Kubernetes API has two major components - the internal structures and the versioned APIs. The versioned APIs are intended to be stable, while the @@ -399,10 +399,10 @@ The conversion code resides with each versioned API. There are two files: functions - `pkg/api/<version>/conversion_generated.go` containing auto-generated conversion functions - - `pkg/expapi/<version>/conversion.go` containing manually written conversion - functions - - `pkg/expapi/<version>/conversion_generated.go` containing auto-generated + - `pkg/apis/experimental/<version>/conversion.go` containing manually written conversion functions + - `pkg/apis/experimental/<version>/conversion_generated.go` containing + auto-generated conversion functions Since auto-generated conversion functions are using manually written ones, those manually written should be named with a defined convention, i.e. a function @@ -437,7 +437,7 @@ of your versioned api objects. The deep copy code resides with each versioned API: - `pkg/api/<version>/deep_copy_generated.go` containing auto-generated copy functions - - `pkg/expapi/<version>/deep_copy_generated.go` containing auto-generated copy functions + - `pkg/apis/experimental/<version>/deep_copy_generated.go` containing auto-generated copy functions To regenerate them: - run @@ -446,6 +446,23 @@ To regenerate them: hack/update-generated-deep-copies.sh ``` +## Making a new API Group + +This section is under construction, as we make the tooling completely generic. + +At the moment, you'll have to make a new directory under pkg/apis/; copy the +directory structure from pkg/apis/experimental. Add the new group/version to all +of the hack/{verify,update}-generated-{deep-copy,conversions,swagger}.sh files +in the appropriate places--it should just require adding your new group/version +to a bash array. You will also need to make sure your new types are imported by +the generation commands (cmd/gendeepcopy/ & cmd/genconversion). These +instructions may not be complete and will be updated as we gain experience. + +Adding API groups outside of the pkg/apis/ directory is not currently supported, +but is clearly desirable. The deep copy & conversion generators need to work by +parsing go files instead of by reflection; then they will be easy to point at +arbitrary directories: see issue [#13775](http://issue.k8s.io/13775). + ## Update the fuzzer Part of our testing regimen for APIs is to "fuzz" (fill with random values) API |