whentimeslows/website
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Convert to pure ASCII (#2110)

Browse Source
This commit is contained in:
Tim Hockin
2017-01-03 00:28:28 -08:00
committed by GitHub
parent 6ebd94302d
commit 476fbee334
1 changed files with 29 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/deprecation-policy.md
+29 -29
View File
@@ -8,7 +8,7 @@ assignees:
# Kubernetes Deprecation Policy # Kubernetes Deprecation Policy
Kubernetes is a large system with many components and many contributors.  As Kubernetes is a large system with many components and many contributors. As
with any such software, the feature set naturally evolves over time, and with any such software, the feature set naturally evolves over time, and
sometimes a feature may need to be removed. This could include an API, a flag, sometimes a feature may need to be removed. This could include an API, a flag,
or even an entire feature. To avoid breaking existing users, Kubernetes follows or even an entire feature. To avoid breaking existing users, Kubernetes follows
@@ -20,7 +20,7 @@ This document details the deprecation policy for various facets of the system.
Since Kubernetes is an API-driven system, the API has evolved over time to Since Kubernetes is an API-driven system, the API has evolved over time to
reflect the evolving understanding of the problem space. The Kubernetes API is reflect the evolving understanding of the problem space. The Kubernetes API is
actually a set of APIs, called “API groups”, and each API group is actually a set of APIs, called "API groups", and each API group is
independently versioned. [API versions](http://kubernetes.io/docs/api/) fall independently versioned. [API versions](http://kubernetes.io/docs/api/) fall
into 3 main tracks, each of which has different policies for deprecation: into 3 main tracks, each of which has different policies for deprecation:
@@ -33,7 +33,7 @@ into 3 main tracks, each of which has different policies for deprecation:
A given release of Kubernetes can support any number of API groups and any A given release of Kubernetes can support any number of API groups and any
number of versions of each. number of versions of each.
The following rules govern the deprecation of elements of the API.  This The following rules govern the deprecation of elements of the API. This
includes: includes:
* REST resources (aka API objects) * REST resources (aka API objects)
@@ -51,8 +51,8 @@ Once an API element has been added to an API group at a particular version, it
can not be removed from that version or have its behavior significantly can not be removed from that version or have its behavior significantly
changed, regardless of track. changed, regardless of track.
Note: For historical reasons, there are 2 “monolithic” API groups - “core” (no Note: For historical reasons, there are 2 "monolithic" API groups - "core" (no
group name) and “extensions”.  Resources will incrementally be moved from these group name) and "extensions". Resources will incrementally be moved from these
legacy API groups into more domain-specific API groups. legacy API groups into more domain-specific API groups.
**Rule #2: API objects must be able to round-trip between API versions in a given **Rule #2: API objects must be able to round-trip between API versions in a given
@@ -61,7 +61,7 @@ that do not exist in some versions.**
For example, an object can be written as v1 and then read back as v2 and For example, an object can be written as v1 and then read back as v2 and
converted to v1, and the resulting v1 resource will be identical to the converted to v1, and the resulting v1 resource will be identical to the
original.  The representation in v2 might be different from v1, but the system original. The representation in v2 might be different from v1, but the system
knows how to convert between them in both directions. Additionally, any new knows how to convert between them in both directions. Additionally, any new
field added in v2 must be able to round-trip to v1 and back, which means v1 field added in v2 must be able to round-trip to v1 and back, which means v1
might have to add an equivalent field or represent it as an annotation. might have to add an equivalent field or represent it as an annotation.
@@ -79,43 +79,43 @@ no less than:**
* **Beta: 3 months or 1 release (whichever is longer)** * **Beta: 3 months or 1 release (whichever is longer)**
* **Alpha: 0 releases** * **Alpha: 0 releases**
This is best illustrated by example.  Imagine a Kubernetes release, version X, This is best illustrated by example. Imagine a Kubernetes release, version X,
which supports a particular API group.  A new Kubernetes release is made every which supports a particular API group. A new Kubernetes release is made every
approximately 3 months (4 per year).  The following table describes which API approximately 3 months (4 per year). The following table describes which API
versions are supported in a series of subsequent releases. versions are supported in a series of subsequent releases.
| Release | API versions | Notes | | Release | API versions | Notes |
|---------|--------------|-------| |---------|--------------|-------|
| X | v1 | | | X | v1 | |
| X+1 | v1, v2alpha1 | | | X+1 | v1, v2alpha1 | |
| X+2 | v1, v2alpha2 | * v2alpha1 is removed, “action required” relnote | | X+2 | v1, v2alpha2 | * v2alpha1 is removed, "action required" relnote |
| X+3 | v1, v2beta1 | * v2alpha2 is removed, “action required” relnote | | X+3 | v1, v2beta1 | * v2alpha2 is removed, "action required" relnote |
| X+4 | v1, v2beta1, v2beta2 | * v2beta1 is deprecated, “action required” relnote | | X+4 | v1, v2beta1, v2beta2 | * v2beta1 is deprecated, "action required" relnote |
| X+5 | v1, v2, v2beta2 | * v2beta1 is removed, “action required” relnote<br> * v2beta2 is deprecated, “action required” relnote<br> * v1 is deprecated, “action required” relnote | | X+5 | v1, v2, v2beta2 | * v2beta1 is removed, "action required" relnote<br> * v2beta2 is deprecated, "action required" relnote<br> * v1 is deprecated, "action required" relnote |
| X+6 | v1, v2 | * v2beta2 is removed, “action required” relnote | | X+6 | v1, v2 | * v2beta2 is removed, "action required" relnote |
| X+7 | v1, v2 | | | X+7 | v1, v2 | |
| X+8 | v1, v2 | | | X+8 | v1, v2 | |
| X+9 | v2 | * v1 is removed, “action required” relnote | | X+9 | v2 | * v1 is removed, "action required" relnote |
### REST resources (aka API objects) ### REST resources (aka API objects)
Consider a hypothetical REST resource named Widget, which was present in API v1 Consider a hypothetical REST resource named Widget, which was present in API v1
in the above timeline, and which needs to be deprecated.  We in the above timeline, and which needs to be deprecated. We
[document](http://kubernetes.io/docs/deprecated/) and [document](http://kubernetes.io/docs/deprecated/) and
[announce](https://groups.google.com/forum/#!forum/kubernetes-announce) the [announce](https://groups.google.com/forum/#!forum/kubernetes-announce) the
deprecation in sync with release X+1.  The Widget resource still exists in API deprecation in sync with release X+1. The Widget resource still exists in API
version v1 (deprecated) but not in v2alpha1.  The Widget resource continues to version v1 (deprecated) but not in v2alpha1. The Widget resource continues to
exist and function in releases up to and including X+8.  Only in release X+9, exist and function in releases up to and including X+8. Only in release X+9,
when API v1 has aged out, does the Widget resource cease to exist, and the when API v1 has aged out, does the Widget resource cease to exist, and the
behavior get removed. behavior get removed.
### Fields of REST resources ### Fields of REST resources
As with whole REST resources, an individual field which was present in API v1 As with whole REST resources, an individual field which was present in API v1
must exist and function until API v1 is removed.  Unlike whole resources, the must exist and function until API v1 is removed. Unlike whole resources, the
v2 APIs may choose a different representation for the field, as long as it can v2 APIs may choose a different representation for the field, as long as it can
be round-tripped.  For example a v1 field named “magnitude” which was be round-tripped. For example a v1 field named "magnitude" which was
deprecated might be named “deprecatedMagnitude” in API v2.  When v1 is deprecated might be named "deprecatedMagnitude" in API v2. When v1 is
eventually removed, the deprecated field can be removed from v2. eventually removed, the deprecated field can be removed from v2.
### Enumerated or constant values ### Enumerated or constant values
@@ -136,10 +136,10 @@ point these rules will be adjusted as needed.
The Kubernetes system is comprised of several different programs cooperating. The Kubernetes system is comprised of several different programs cooperating.
Sometimes, a Kubernetes release might remove flags or CLI commands Sometimes, a Kubernetes release might remove flags or CLI commands
(collectively “CLI elements”) in these programs.  The individual programs (collectively "CLI elements") in these programs. The individual programs
naturally sort into two main groups - user-facing and admin-facing programs, naturally sort into two main groups - user-facing and admin-facing programs,
which vary slightly in their deprecation policies.  Unless a flag is explicitly which vary slightly in their deprecation policies. Unless a flag is explicitly
prefixed or documented as “alpha” or “beta”, it is considered GA. prefixed or documented as "alpha" or "beta", it is considered GA.
CLI elements are effectively part of the API to the system, but since they are CLI elements are effectively part of the API to the system, but since they are
not versioned in the same way as the REST API, the rules for deprecation are as not versioned in the same way as the REST API, the rules for deprecation are as
@@ -163,7 +163,7 @@ when used.**
## Deprecating a feature or behavior ## Deprecating a feature or behavior
Occasionally a Kubernetes release needs to deprecate some feature or behavior Occasionally a Kubernetes release needs to deprecate some feature or behavior
of the system that is not controlled by the API or CLI.  In this case, the of the system that is not controlled by the API or CLI. In this case, the
rules for deprecation are as follows: rules for deprecation are as follows:
**Rule #7: Deprecated behaviors must function for no less than 1 year after their **Rule #7: Deprecated behaviors must function for no less than 1 year after their
@@ -176,10 +176,10 @@ administration of Kubernetes clusters, and which are being removed entirely.
## Exceptions ## Exceptions
No policy can cover every possible situation.  This policy is a living No policy can cover every possible situation. This policy is a living
document, and will evolve over time.  In practice, there will be situations document, and will evolve over time. In practice, there will be situations
that do not fit neatly into this policy, or for which this policy becomes a that do not fit neatly into this policy, or for which this policy becomes a
serious impediment.  Such situations should be discussed with SIGs and project serious impediment. Such situations should be discussed with SIGs and project
leaders to find the best solutions for those specific cases, always bearing in leaders to find the best solutions for those specific cases, always bearing in
mind that Kubernetes is committed to being a stable system that, as much as mind that Kubernetes is committed to being a stable system that, as much as
possible, never breaks users. Exceptions will always be announced in all possible, never breaks users. Exceptions will always be announced in all