Skip to content

Commit

Permalink
Update api-conventions.md
Browse files Browse the repository at this point in the history
Moved compatibility gotchas to api_changes.md
  • Loading branch information
bgrant0607 authored Mar 23, 2017
1 parent 64c17b1 commit de51cfa
Showing 1 changed file with 0 additions and 16 deletions.
16 changes: 0 additions & 16 deletions contributors/devel/api-conventions.md
Original file line number Diff line number Diff line change
Expand Up @@ -1463,22 +1463,6 @@ be less than 256", "must be greater than or equal to 0". Do not use words
like "larger than", "bigger than", "more than", "higher than", etc.
* When specifying numeric ranges, use inclusive ranges when possible.

## Backward compatibility gotchas

* A single feature/property cannot be represented using multiple spec fields in the same API version
simultaneously. Only one field can be populated in any resource at a time, and the client
needs to be able to specify which field they expect to use (typically via API version),
on both mutation and read. Old clients must continue to function properly while only manipulating
the old field. New clients must be able to function properly while only manipulating the new
field.
* Changing any validation rules always has the potential of breaking some client, since it changes the
assumptions about part of the API, similar to adding new enum values. Validation rules on spec fields can
neither be relaxed nor strengthened. Strengthening cannot be permitted because any requests that previously
worked must continue to work. Weakening validation has the potential to break other consumers and generators
of the API resource. Status fields whose writers are under our control (e.g., written by non-pluggable
controllers), may potentially tighten validation, since that would cause a subset of previously valid
values to be observable by clients.

<!-- BEGIN MUNGE: GENERATED_ANALYTICS -->
[![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/devel/api-conventions.md?pixel)]()
<!-- END MUNGE: GENERATED_ANALYTICS -->

0 comments on commit de51cfa

Please sign in to comment.