kubernetes
/
community
mirror of https://github.com/kubernetes/community.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #2411 from janetkuo/api-default-rules 

Document rules and best practices of default values
This commit is contained in:
k8s-ci-robot 2018-08-23 10:55:31 -07:00 committed by GitHub
parent c8b0e69fa7 dd4ae8273f
commit 8663fff7dd
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 21 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
contributors/devel/api_changes.md
View File

@ -102,7 +102,7 @@ An API change is considered forward and backward-compatible if it:
* adds new functionality that is not required for correct behavior (e.g., * adds new functionality that is not required for correct behavior (e.g.,
does not add a new required field) does not add a new required field)
* does not change existing semantics, including: * does not change existing semantics, including:
* default values *and behavior* * the semantic meaning of default values *and behavior*
* interpretation of existing API types, fields, and values * interpretation of existing API types, fields, and values
* which fields are required and which are not * which fields are required and which are not
* mutable fields do not become immutable * mutable fields do not become immutable
@ -296,6 +296,16 @@ was added.
release, and do not make it the storage version. The latter is necessary so that a rollback of the release, and do not make it the storage version. The latter is necessary so that a rollback of the
apiserver doesn't render resources in etcd undecodable after rollback. apiserver doesn't render resources in etcd undecodable after rollback.
* Any field with a default value in one API version must have *non-nil default
values* in all API versions. If a default value is added to a field in one API
version, and the field didn't have a default value in previous API versions,
it is required to add a default value semantically equivalent to an unset
value to the field in previous API versions, to preserve the semantic
meaning of the value being unset. This includes:
* a new optional field with a default value is introduced in a new API version
* an old optional field without a default value (i.e. can be nil) has a
default value in a new API version
## Incompatible API changes ## Incompatible API changes
There are times when this might be OK, but mostly we want changes that meet this There are times when this might be OK, but mostly we want changes that meet this
@ -365,9 +375,15 @@ being required otherwise.
### Edit defaults.go ### Edit defaults.go
If your change includes new fields for which you will need default values, you If your change includes new fields for which you will need default values, you
need to add cases to `pkg/apis/<group>/<version>/defaults.go` need to add cases to `pkg/apis/<group>/<version>/defaults.go`.
*Note:* In the past the core v1 API **Note:** When adding default values to new fields, you *must* also add default
values in all API versions, instead of leaving new fields unset (e.g. `nil`) in
old API versions. This is required because defaulting happens whenever a
serialized version is read (see [#66135]). When possible, pick meaningful values
as sentinels for unset values.
In the past the core v1 API
was special. Its `defaults.go` used to live at `pkg/api/v1/defaults.go`. was special. Its `defaults.go` used to live at `pkg/api/v1/defaults.go`.
If you see code referencing that path, you can be sure its outdated. Now the core v1 api lives at If you see code referencing that path, you can be sure its outdated. Now the core v1 api lives at
`pkg/apis/core/v1/defaults.go` which follows the above convention. `pkg/apis/core/v1/defaults.go` which follows the above convention.
@ -383,6 +399,8 @@ pick a default.
Don't forget to run the tests! Don't forget to run the tests!
[#66135]: https://github.com/kubernetes/kubernetes/issues/66135
### Edit conversion.go ### Edit conversion.go
Given that you have not yet changed the internal structs, this might feel Given that you have not yet changed the internal structs, this might feel