Add deprecation policy (kubernetes#1856)

docs/deprecation-policy.md

@@ -0,0 +1,186 @@
+---
+assignees:
+- bgrant0607
+- lavalamp
+- thockin
+
+---
+
+# Kubernetes Deprecation Policy
+
+Kubernetes is a large system with many components and many contributors.  As
+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,
+or even an entire feature. To avoid breaking existing users, Kubernetes follows
+a deprecation policy for aspects of the system that are slated to be removed.
+
+This document details the deprecation policy for various facets of the system.
+
+## Deprecating parts of the API
+
+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
+actually a set of APIs, called “API groups”, and each API group is
+independently versioned.  [API versions](http://kubernetes.io/docs/api/) fall
+into 3 main tracks, each of which has different policies for deprecation:
+
+| Example  | Track                            |
+|----------|----------------------------------|
+| v1       | GA (generally available, stable) |
+| v1beta1  | Beta (pre-release)               |
+| v1alpha1 | Alpha (experimental)             |
+
+A given release of Kubernetes can support any number of API groups and any
+number of versions of each.
+
+The following rules govern the deprecation of elements of the API.  This
+includes:
+
+   * REST resources (aka API objects)
+   * Fields of REST resources
+   * Enumerated or constant values
+   * Component config structures
+
+These rules are enforced between official releases, not between
+arbitrary commits to master or release branches.
+
+**Rule #1: API elements may only be removed by incrementing the version of the
+API group.**
+
+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
+changed, regardless of track.
+
+Note: For historical reasons, there are 2 “monolithic” API groups - “core” (no
+group name) and “extensions”.  Resources will incrementally be moved from these
+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
+release without information loss, with the exception of whole REST resources
+that do not exist in some versions.**
+
+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
+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
+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.
+
+**Rule #3: An API version in a given track may not be deprecated until a new
+API version at least as stable is released.**
+
+GA API versions can replace GA API versions as well as beta and alpha API
+version.  Beta API versions *may not* replace GA API versions.
+
+**Rule #4: Other than the most recent API version in each track, older API
+versions must be supported after their announced deprecation for a duration of
+no less than:**
+   * **GA: 1 year or 2 releases (whichever is longer)**
+   * **Beta: 3 months or 1 release (whichever is longer)**
+   * **Alpha: 0 releases**
+
+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
+approximately 3 months (4 per year).  The following table describes which API
+versions are supported in a series of subsequent releases.
+
+| Release | API versions | Notes |
+|---------|--------------|-------|
+| X       | v1           |       |
+| X+1     | v1, v2alpha1 |       |
+| X+2     | v1, v2alpha2 | * v2alpha1 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+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+7     | v1, v2               | |
+| X+8     | v1, v2               | |
+| X+9     | v2                   | * v1 is removed, “action required” relnote |
+
+### REST resources (aka API objects)
+
+Consider a hypothetical REST resource named Widget, which was present in API v1
+in the above timeline, and which needs to be deprecated.  We
+[document](http://kubernetes.io/docs/deprecated/) and
+[announce](https://groups.google.com/forum/#!forum/kubernetes-announce) the
+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
+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
+behavior get removed.
+
+### Fields of REST resources
+
+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
+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
+deprecated might be named “deprecatedMagnitude” in API v2.  When v1 is
+eventually removed, the deprecated field can be removed from v2.
+
+### Enumerated or constant values
+
+As with whole REST resources and fields thereof, a constant value which was
+supported in API v1 must exist and function until API v1 is removed.
+
+### Component config structures
+
+Component configs are versioned and managed just like REST resources.
+
+### Future work
+
+Over time, Kubernetes will introduce more fine-grained API versions, at which
+point these rules will be adjusted as needed.
+
+## Deprecating a flag or CLI
+
+The Kubernetes system is comprised of several different programs cooperating.
+Sometimes, a Kubernetes release might remove flags or CLI commands
+(collectively “CLI elements”) in these programs.  The individual 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
+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
+not versioned in the same way as the REST API, the rules for deprecation are as
+follows:
+
+**Rule #5a: CLI elements of user-facing components (e.g. kubectl) must function
+after their announced deprecation for no less than:**
+   * **GA: 1 year or 2 releases (whichever is longer)**
+   * **Beta: 3 months or 1 release (whichever is longer)**
+   * **Alpha: 0 releases**
+
+**Rule #5b: CLI elements of admin-facing components (e.g. kubelet) must function
+after their announced deprecation for no less than:**
+   * **GA: 6 months or 1 release (whichever is longer)**
+   * **Beta: 3 months or 1 release (whichever is longer)**
+   * **Alpha: 0 releases**
+
+**Rule #6: Deprecated CLI elements must emit warnings (optionally disableable)
+when used.**
+
+## Deprecating a 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
+rules for deprecation are as follows:
+
+**Rule #7: Deprecated behaviors must function for no less than 1 year after their
+announced deprecation.**
+
+This does not imply that all changes to the system are governed by this policy.
+This applies only to significant, user-visible behaviors which impact the
+correctness of applications running on Kubernetes or that impact the
+administration of Kubernetes clusters, and which are being removed entirely.
+
+## Exceptions
+
+No policy can cover every possible situation.  This policy is a living
+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
+serious impediment.  Such situations should be discussed with SIGs and project
+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
+possible, never breaks users. Exceptions will always be announced in all
+relevant release notes.