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

Merge pull request #998 from thockin/master 

Automatic merge from submit-queue

Update the docs around alpha fields & deprecating

Fix some wording.

Remove the demand for validation to fail.  It also says to clearthose
fields, which more closely models non-existent fields.

Change the tombstone (proposed - nobody is using this yet, obviously).
This format matches what gengo uses for other tags.
This commit is contained in:
Kubernetes Submit Queue 2017-08-30 11:28:11 -07:00 committed by GitHub
parent e10705b768 fcbf6f8145
commit c194cce207
1 changed files with 13 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
contributors/devel/api_changes.md
View File

@ -852,7 +852,7 @@ The preferred approach adds an alpha field to the existing object, and ensures i
* ensure the field is [optional](api-conventions.md#optional-vs-required) * ensure the field is [optional](api-conventions.md#optional-vs-required)
* add the `omitempty` struct tag * add the `omitempty` struct tag
* add the `// +optional` comment tag * add the `// +optional` comment tag
* ensure the field is entirely absent from API responses when empty (if it is a struct type, it must be a pointer) * ensure the field is entirely absent from API responses when empty (optional fields should be pointers, anyway)
* include details about the alpha-level in the field description * include details about the alpha-level in the field description
```go ```go
@ -885,14 +885,14 @@ One possible place to do this is in the REST storage strategy's PrepareForCreate
newFrobber := obj.(*api.Frobber) newFrobber := obj.(*api.Frobber)
oldFrobber := old.(*api.Frobber) oldFrobber := old.(*api.Frobber)
if !utilfeature.DefaultFeatureGate.Enabled(features.DynamicKubeletConfig) { if !utilfeature.DefaultFeatureGate.Enabled(features.Frobber2D) {
newFrobber.Spec.ConfigSource = nil newFrobber.Width = nil
oldFrobber.Spec.ConfigSource = nil oldFrobber.Width = nil
} }
} }
``` ```
4. In validation, ensure the alpha field is not set if the feature gate is disabled: 4. In validation, ensure the alpha field is not set if the feature gate is disabled (covers cases we might miss in the above):
```go ```go
func ValidateFrobber(f *api.Frobber, fldPath *field.Path) field.ErrorList { func ValidateFrobber(f *api.Frobber, fldPath *field.Path) field.ErrorList {
@ -906,11 +906,14 @@ One possible place to do this is in the REST storage strategy's PrepareForCreate
} }
``` ```
In future versions: Eventually, the API machinery will handle a lot of these things automatically from
declarative inputs.
* if the feature progresses to beta or stable status, the feature gate can simply be enabled by default. In future Kubernetes versions:
* if the feature progresses to beta or stable status, the feature gate can be removed or be enabled by default.
* if the schema of the alpha field must change in an incompatible way, a new field name must be used. * if the schema of the alpha field must change in an incompatible way, a new field name must be used.
* if the feature is abandoned, or a different field name is selected, the field should be removed from the go struct, with a tombstone comment ensuring the field name and protobuf tag are not reused: * if the feature is abandoned, or the field name is changed, the field should be removed from the go struct, with a tombstone comment ensuring the field name and protobuf tag are not reused:
```go ```go
// API v6. // API v6.
@ -920,9 +923,7 @@ In future versions:
// param ... // param ...
Param string `json:"param" protobuf:"bytes,2,opt,name=param"` Param string `json:"param" protobuf:"bytes,2,opt,name=param"`
// removed alpha-level field 'width' // +k8s:deprecated=width,protobuf=3
// the field name 'width' and protobuf tag '3' may not be reused.
// Width *int32 `json:"width,omitempty" protobuf:"varint,3,opt,name=width"`
} }
``` ```