Add deprecation policy #1856

thockin · 2016-12-05T17:14:41Z

This proposed a written policy for deprecation within Kubernetes.

@bgrant0607 @lavalamp @matchstick @erictune @smarterclayton for review

@devin-donnelly I have no idea where to actually put this or where to link it into the tree. Thoughts?

This change is

thockin · 2016-12-05T17:16:13Z

docs/deprecation_policy.md

+
+Rule #3: Other than the “current” API version, 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)


From @lavalamp out-of-band: Given that we have many API groups, and they will be versioning at different rates, it's easy to imagine a situation where we're removing a major version from some group every release. If the purpose of this is to reduce the maintenance burden on users, what about a rule that's something like, "GA versions will only be removed during the latter half of the calendar year" or “GA versions will only be removed in odd-numbered releases”?

Hrm. We may not have to solve this before we actually hit the problem. Could be vaguer.

I don't understand your comment, @smarterclayton

thockin · 2016-12-05T17:17:09Z

docs/deprecation_policy.md

+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.


From @lavalamp out-of-band: Does it need to wait until v3? The text as written would work better in a world where we have fine-grained versions, I think...

Do we really to support all features or is this a side effect of the round tripping requirement?

We support the features until they are EOL.

When can features reach EOL?

thockin · 2016-12-05T17:19:57Z

docs/deprecation_policy.md

+### REST resources (aka API objects)
+
+Consider a hypothetical REST resource named Widget, which was present in API v1
+in the above timeline, and which we want to deprecate.  We [document](http://kubernetes.io/docs/deprecated/)


@devin-donnelly We need a place to host deprecation notices, and maybe a template for it. I can help with the template, if you can tell me where to put them and where to link them from.

So far we've been putting such notices in the release notes.

release notes seem like a good way to announce them, but I think we need a page that links to current deprecations, no?

smarterclayton · 2016-12-05T17:22:12Z

docs/deprecation_policy.md

+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


Would go further and describe "it must not change in behavior". Removal and change in behavior are equivalent.

will clarify. want this to be strong.

bgrant0607 · 2016-12-05T17:34:20Z

@thockin This is intended to be read by end users or contributors?

sarahnovotny · 2016-12-05T18:04:39Z

@bgrant0607, this was for end users per a convo this morning with @thockin

mtaufen · 2016-12-05T18:49:18Z

docs/deprecation_policy.md

+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.


So if I read this right it is impossible to remove a field that existed in v1 when you move to v2, unless you somehow couple that information somewhere else in the v2 object.

This is covered below (search for "deprecatedMagnitude").

bgrant0607 · 2016-12-05T18:55:25Z

@thockin Nit: Please don't use underscores in doc file names. When we move this file to its proper location it should also be renamed.

bgrant0607 · 2016-12-05T18:58:34Z

docs/deprecation_policy.md

+original.  The representation in v2 might be different from v1, but the system
+knows how to convert between them in both directions.
+
+Rule #3: Other than the “current” API version, older API versions must be


I'd clarify "current". Maybe: latest API version at least as mature as the ones it replaces

bgrant0607 · 2016-12-05T19:16:45Z

docs/deprecation_policy.md

+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.
+
+### Future work


If we think these rules should apply identically to versioned configuration, we should add a subsection that explicitly states that. I think that's a reasonable starting point. I think the only config that's GA might be kubeconfig and the scheduler config.

Is it sufficient to say "REST resources and component configs" since they use the same mechanisms? Or to call out component configs and say "see REST resources" ?

@thockin I'd do the latter: Call out component configs and say that the same policies apply as those that apply to REST resources.

lavalamp · 2016-12-06T01:27:35Z

You are thinking of binary versions, this table is about API versions.

…

On Mon, Dec 5, 2016 at 5:13 PM, David Aronchick ***@***.***> wrote: ***@***.**** commented on this pull request. ------------------------------ In docs/deprecation_policy.md <#1856 (review)> : > +which supports a particular API group. A new Kubernetes release is made every +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 | I thought we had a "2 version" deprecation policy exclusively (no time)? This is much larger than we currently test against. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1856 (review)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAngljqNk_1B0Ow6iVTTUUmVnWTu72pxks5rFLbQgaJpZM4LEe3L> .

vishh · 2016-12-06T02:33:48Z

docs/deprecation_policy.md

+   * GA: 1 year or 2 releases (whichever is longer)
+   * Beta: 3 months or 1 release (whichever is longer)
+   * Alpha: 0 releases
+


Should we also require releasing additional tooling that will help translate old API objects to newer versions?

Maybe, but that is covered elsewhere - this doc is about deprecation and nothing more.

vishh · 2016-12-06T02:36:20Z

docs/deprecation_policy.md

+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.


Do we really to support all features or is this a side effect of the round tripping requirement?

vishh · 2016-12-06T02:38:51Z

docs/deprecation_policy.md

+Sometimes, we need to 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 “alpha” or


How do we handle alpha features that are exposed as top level commands?

alpha CLI commands is interesting. They probably should be denoted "alpha" somehow, but I think these rules are sufficient to cover deprecation.

vishh · 2016-12-06T02:40:37Z

docs/deprecation_policy.md

+Rule #6: 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.


This subjective policy will lead to confusion. Would it make sense to define a process for deciding deprecation period for such features?

I could be convinced to add more words here, but I don;t want this to become a legal treatise on the meaning of "significant".

roberthbailey · 2016-12-06T05:49:24Z

docs/deprecation_policy.md

+   * REST resources (aka API objects)
+   * Fields of REST resources
+   * Enumerated or constant values
+These rules are enforced between official releases, not between


Need a blank line before this so that it's a new paragraph.

roberthbailey · 2016-12-06T05:49:57Z

docs/deprecation_policy.md

+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


Can you bold or ### each rule so that they stand out a bit more?

roberthbailey · 2016-12-06T05:53:28Z

docs/deprecation_policy.md

+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


I think none of these rules should apply to alpha apis. They should be able to change in arbitrary ways at any point in time to encourage fast development.

once we publish an alpha API, I think it's unreasonable to change it in incompatible ways. Revving APIs should be cheap (I know it's not but @lavalamp is on it :)

roberthbailey · 2016-12-06T05:54:36Z

docs/deprecation_policy.md

+
+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
+3 months (4 per year).  The following table describes which API versions are


nit: made approximately every 3 months.

roger roger

roberthbailey · 2016-12-06T05:56:19Z

docs/deprecation_policy.md

+| 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 |


I don't see it explicitly called out that you can't deprecate v1 until v2 is available (e.g. it shouldn't be possible to deprecate v1 at X+3 because we almost have a v2 ready, just to speed up the time at which we can remove v1).

ooh, good one. Added.

roberthbailey · 2016-12-06T05:57:17Z

docs/deprecation_policy.md

+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.


This is covered below (search for "deprecatedMagnitude").

thockin · 2016-12-06T06:23:04Z

New push is up with much feedback addressed. File was renamed, so github may lose comments.

davidopp · 2016-12-06T10:27:08Z

docs/deprecation-policy.md

+Sometimes, we need to 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 “alpha” or


Do we have flags that control the behavior of alpha/beta features today? If so what you describe here would require some bulk flag renaming.

davidopp · 2016-12-06T10:31:27Z

docs/deprecation-policy.md

+their deprecation policies.  Unless a flag is explicitly prefixed “alpha” or
+“beta”, it is considered GA.
+
+CLI elements are effectively part of the API to the system, but since they are


I couldn't quite figure out what a "CLI element" is. For kubectl, do you mean a subcommand (like get, drain, proxy, etc.)? What does it mean for kubelet?

thockin · 2016-12-06T18:49:11Z

ACK

…

On Mon, Dec 5, 2016 at 11:34 PM, Brian Grant ***@***.***> wrote: ***@***.**** commented on this pull request. ------------------------------ In docs/deprecation_policy.md <#1856>: > + +### 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. + +### Future work @thockin <https://github.com/thockin> I'd do the latter: Call out component configs and say that the same policies apply as those that apply to REST resources. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1856>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AFVgVKyMdNpozdrBniUWkutvRVWUfs85ks5rFQ_tgaJpZM4LEe3L> .

thockin · 2016-12-06T18:50:08Z

yeah, we have not been 100% consistent on naming. Will add "or documented"

…

On Tue, Dec 6, 2016 at 2:27 AM, David Oppenheimer ***@***.***> wrote: ***@***.**** commented on this pull request. ------------------------------ In docs/deprecation-policy.md <#1856 (review)> : > + +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. + +### Future work + +We intend to introduce more fine-grained API versions, at which point we will +adjust these rules as needed. + +## Deprecating a flag or CLI + +The Kubernetes system is comprised of several different programs cooperating. +Sometimes, we need to 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 “alpha” or Do we have flags that control the behavior of alpha/beta features today? If so what you describe here would require some bulk flag renaming. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1856 (review)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AFVgVEPm_ZXkz8g5iKWR0nRldCwOquaWks5rFTh9gaJpZM4LEe3L> .

thockin · 2016-12-06T18:51:07Z

I defined it in the previous paragraph

…

On Tue, Dec 6, 2016 at 2:31 AM, David Oppenheimer ***@***.***> wrote: ***@***.**** commented on this pull request. ------------------------------ In docs/deprecation-policy.md <#1856 (review)> : > + +### Future work + +We intend to introduce more fine-grained API versions, at which point we will +adjust these rules as needed. + +## Deprecating a flag or CLI + +The Kubernetes system is comprised of several different programs cooperating. +Sometimes, we need to 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 “alpha” or +“beta”, it is considered GA. + +CLI elements are effectively part of the API to the system, but since they are I couldn't quite figure out what a "CLI element" is. For kubectl, do you mean a subcommand (like get, drain, proxy, etc.)? What does it mean for kubelet? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1856 (review)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AFVgVC0WocK3UlVxVz8eaHg2HvJETpTUks5rFTmBgaJpZM4LEe3L> .

bgrant0607 · 2016-12-06T20:17:58Z

@thockin

LGTM. I'm favor of merging whenever you feel like you've addressed enough of the comments and iterating more in subsequent PRs.

Any idea why netlify failed?

thockin · 2016-12-06T20:22:56Z

I'm waiting for Devin to do a docs pass and to tell me where he wants the doc to live and where to link to it from :)

…

On Tue, Dec 6, 2016 at 12:17 PM, Brian Grant ***@***.***> wrote: @thockin <https://github.com/thockin> LGTM. I'm favor of merging whenever you feel like you've addressed enough of the comments and iterating more in subsequent PRs. Any idea why netlify failed? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1856 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AFVgVDg1QCXjBcPXFy17cJrOSALYJ9pLks5rFcL3gaJpZM4LEe3L> .

davidopp · 2016-12-06T20:23:51Z

I defined it in the previous paragraph

I think part of my confusion is whether "e.g. kubectl" is modifying "user-facing components" or "CLI elements" (and likewise whether "e.g. kubelet" is modifying "admin-facing components" or "CLI elements."

TBH I stll don't know what a CLI element is even after re-reading. You say "CLI elements are effectively part of the API" but that doesn't tell me what they are.

thockin · 2016-12-07T01:23:10Z

``` The Kubernetes system is comprised of several different programs cooperating. Sometimes, we need to remove flags or CLI commands (collectively “CLI elements”) in these programs. ``` is that not clear? Suggest rewording?

…

On Tue, Dec 6, 2016 at 12:23 PM, David Oppenheimer ***@***.*** > wrote: I defined it in the previous paragraph I think part of my confusion is whether "e.g. kubectl" is modifying "user-facing components" or "CLI elements" (and likewise whether "e.g. kubelet" is modifying "admin-facing components" or "CLI elements." TBH I stll don't know what a CLI element is even after re-reading. You say "CLI elements are effectively part of the API" but that doesn't tell me what they are. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1856 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AFVgVJ5-mO2WyS1OyHUFp6-QOt5XMkUqks5rFcRYgaJpZM4LEe3L> .

soltysh · 2016-12-08T16:37:14Z

docs/deprecation-policy.md

+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


I think a different example would be better, eg. v1 has magnitude, which transforms into magnitude1 and magnitude1 in v2. The round-trip knows how to deal with that, obviously. That's what will usually happen, imho. Adding deprecatedField in v2 to be then removed when v1 is gone, is confusing.

derekwaynecarr · 2016-12-08T18:18:28Z

docs/deprecation-policy.md

+group name) and “extensions”.  We will incrementally move resources 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


@kubernetes/sig-autoscaling -- this was the point I was trying to find in our meeting today. @DirectXMan12 my reading of this is that HPA v2 would need to convert to HPA v1 when handling scaling on metrics other than cpu.

If that's the case, this should probably provide an explicit "if it adds new features, you have to have corresponding annotations on v1" or something like that.

(as in, an official policy for what to do when v1 is insufficiently expressive)

see annotation example here: https://github.com/kubernetes/community/blob/master/contributors/devel/api_changes.md#adding-unstable-features-to-stable-versions

@thockin What's the policy for adding completely new features in a new API version? Example we have in mind is adding support for custom metrics in v2 HPA API.

thockin · 2016-12-09T01:24:48Z

@soltysh, but that's what I am trying to illustrate - how do you get rid of a field?

…

On Thu, Dec 8, 2016 at 8:37 AM, Maciej Szulik ***@***.***> wrote: ***@***.**** commented on this pull request. ------------------------------ In docs/deprecation-policy.md <#1856 (review)> : > + +Consider a hypothetical REST resource named Widget, which was present in API v1 +in the above timeline, and which we want to deprecate. 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 I think a different example would be better, eg. v1 has magnitude, which transforms into magnitude1 and magnitude1 in v2. The round-trip knows how to deal with that, obviously. That's what will usually happen, imho. Adding deprecatedField in v2 to be then removed when v1 is gone, is confusing. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1856 (review)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AFVgVHJY5dEYlgpU7uUtoxtJYzZh-zCpks5rGDI7gaJpZM4LEe3L> .

thockin · 2016-12-09T01:27:04Z

@DirectXMan12 fair point.

…

On Thu, Dec 8, 2016 at 10:22 AM, Solly Ross ***@***.***> wrote: ***@***.**** commented on this pull request. ------------------------------ In docs/deprecation-policy.md <#1856>: > + +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, we have 2 “monolithic” API groups - “core” (no +group name) and “extensions”. We will incrementally move resources 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 If that's the case, this should probably provide an explicit "if it adds new features, you have to have corresponding annotations on v1" or something like that. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1856>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AFVgVD4B2rvyQ17Qxa-dFG23pzOe0T-pks5rGErQgaJpZM4LEe3L> .

thockin · 2016-12-09T01:32:15Z

@fgrzadkowski The current rule is that it must be able to round-trip. Consider if you add something in v2, the user uses that thing, but your cluster is still using v1 as a storage-version.

…

On Thu, Dec 8, 2016 at 1:22 PM, Filip Grzadkowski ***@***.***> wrote: ***@***.**** commented on this pull request. ------------------------------ In docs/deprecation-policy.md <#1856>: > + +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, we have 2 “monolithic” API groups - “core” (no +group name) and “extensions”. We will incrementally move resources 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 @thockin <https://github.com/thockin> What's the policy for adding completely new features in a new API version? Example we have in mind is adding support for custom metrics in v2 HPA API. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1856>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AFVgVI4QSybJ40JpeZSQUUj3UAudugajks5rGHUCgaJpZM4LEe3L> .

soltysh · 2016-12-12T13:41:16Z

@soltysh, but that's what I am trying to illustrate - how do you get rid of a field?

Right, nvmd, I misread it. Sorry. This LGTM.

thockin · 2016-12-13T06:22:40Z

Now that 1.5 is out, maybe @devin-donnelly can pour some brain power into the finer points of where this should live and whether humans can read it. :)

devin-donnelly · 2016-12-21T23:36:04Z

docs/deprecation-policy.md

+
+# Kubernetes Deprecation Policy
+
+Kubernetes is a large system with many components and many contributors.  As


Try to avoid "we" constructs.

"Kubernetes is a large system with many components and contributors. As with any such software, the feature set 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 making breaking changes for existing users, Kubernetes is instituting a deprecation policy for aspects of the system that are slated to be removed."

devin-donnelly · 2016-12-21T23:37:01Z

docs/deprecation-policy.md

+committed to not breaking users, so we can’t just make breaking changes.  This
+is when deprecation is triggered.
+
+This document details the policies we hold on deprecation for various facets of


"This document details the policies for deprecating the different facets of the Kubernetes system should they be removed in future releases."

devin-donnelly · 2016-12-21T23:38:57Z

docs/deprecation-policy.md

+
+## Deprecating parts of the API
+
+Since Kubernetes is an API-driven system, it’s not surprising that the API


"We/our" construct.

"Since Kubernetes is an API-driven system, the API has evolved over time to reflect an evolving understanding of the problem space. The Kubernetes API consists of several "API groups", and each API group is independently versioned."

devin-donnelly · 2016-12-21T23:46:17Z

docs/deprecation-policy.md

+number of versions of each.
+
+The following rules govern the deprecation of elements of the API.  This
+includes:


Needs a blank line underneath to make the bullet list render correctly.

devin-donnelly · 2016-12-21T23:48:06Z

docs/deprecation-policy.md

+
+## Deprecating a flag or CLI
+
+The Kubernetes system is comprised of several different programs cooperating.


"we" construct.

"Sometimes, a Kubernetes release might remove flags or CLI commands"

devin-donnelly · 2016-12-21T23:49:31Z

@thockin A few wording nits. Otherwise, no problems.

thockin · 2016-12-22T06:51:39Z

All "we" have been hunted down and exterminated. Is this the right dir for this file? This proposes http://kubernetes.io/docs/deprecated/ as a dir for the various deprecation notices. OK?

…

On Wed, Dec 21, 2016 at 3:49 PM, devin-donnelly ***@***.***> wrote: @thockin <https://github.com/thockin> A few wording nits. Otherwise, no problems. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1856 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AFVgVN7Zxy60V_4nmFUbZ7Nm2u8deernks5rKbsNgaJpZM4LEe3L> .

devin-donnelly · 2016-12-23T02:45:42Z

@thockin Yes, this file is fine in the root directory, and I'm fine with the location for Deprecation notices. Anybody else need to sign off on this before I can merge it?

thockin · 2016-12-23T04:30:14Z

Nope! Thanks. I'll start directing deprecation notice PRs to http://kubernetes.io/docs/deprecated/

…

On Thu, Dec 22, 2016 at 6:45 PM, devin-donnelly ***@***.***> wrote: @thockin <https://github.com/thockin> Yes, this file is fine in the root directory, and I'm fine with the location for Deprecation notices. Anybody else need to sign off on this before I can merge it? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1856 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AFVgVFKNIqloKYYJYE1L66iURzoogaW_ks5rKzXXgaJpZM4LEe3L> .

thockin · 2016-12-27T01:21:36Z

rebased and repushed. I do not have access to the netlify, but it said it failed before.

thockin · 2017-01-03T07:43:02Z

rebased and pushed again. Gonna self-merge

…cument (kubernetes#1856) * kubernetes#1775 Issue: Localized the content/en/software-as-a-service.md document to Spanish * Fix the spelling and translated the English part of the file * Fixes the spell check failure and update the content/es/software-as-a-service.md Signed-off-by: Naymul Islam <[email protected]> Signed-off-by: Naymul Islam <[email protected]>

k8s-ci-robot added the cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. label Dec 5, 2016

thockin commented Dec 5, 2016

View reviewed changes

k8s-github-robot assigned jaredbhatti Dec 5, 2016

smarterclayton reviewed Dec 5, 2016

View reviewed changes

mtaufen reviewed Dec 5, 2016

View reviewed changes

bgrant0607 reviewed Dec 5, 2016

View reviewed changes

vishh reviewed Dec 6, 2016

View reviewed changes

roberthbailey reviewed Dec 6, 2016

View reviewed changes

thockin force-pushed the deprecation branch 2 times, most recently from b7f196a to 8843cf0 Compare December 6, 2016 06:22

thockin force-pushed the deprecation branch 2 times, most recently from 91bc79c to b321881 Compare December 6, 2016 06:27

davidopp reviewed Dec 6, 2016

View reviewed changes

thockin force-pushed the deprecation branch from b321881 to a1df07e Compare December 6, 2016 18:52

soltysh reviewed Dec 8, 2016

View reviewed changes

derekwaynecarr reviewed Dec 8, 2016

View reviewed changes

thockin force-pushed the deprecation branch from 816788d to f2b593d Compare December 9, 2016 01:32

thockin force-pushed the deprecation branch from 8b8a5b9 to 7b803b4 Compare December 13, 2016 06:21

thockin force-pushed the deprecation branch from 7b803b4 to 27caf4f Compare December 14, 2016 00:13

devin-donnelly suggested changes Dec 21, 2016

View reviewed changes

thockin force-pushed the deprecation branch from 27caf4f to 8fa48e8 Compare December 22, 2016 06:49

devin-donnelly approved these changes Dec 23, 2016

View reviewed changes

thockin force-pushed the deprecation branch from 8fa48e8 to 167cdac Compare December 27, 2016 01:20

Add deprecation policy

930503a

thockin force-pushed the deprecation branch from f73797a to 930503a Compare January 3, 2017 07:42

thockin merged commit 6ebd943 into kubernetes:master Jan 3, 2017

geojaz pushed a commit to geojaz/kubernetes.github.io that referenced this pull request Jan 4, 2017

Add deprecation policy (kubernetes#1856)

d485f2e


		# Kubernetes Deprecation Policy

		Kubernetes is a large system with many components and many contributors. As


		## Deprecating parts of the API

		Since Kubernetes is an API-driven system, it’s not surprising that the API


		## Deprecating a flag or CLI

		The Kubernetes system is comprised of several different programs cooperating.

Add deprecation policy #1856

Add deprecation policy #1856

Conversation

thockin commented Dec 5, 2016 • edited by k8s-reviewable Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

smarterclayton Dec 5, 2016 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bgrant0607 commented Dec 5, 2016

sarahnovotny commented Dec 5, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bgrant0607 commented Dec 5, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lavalamp commented Dec 6, 2016 via email

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

thockin commented Dec 6, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

thockin commented Dec 6, 2016 via email

thockin commented Dec 6, 2016 via email

thockin commented Dec 6, 2016 via email

bgrant0607 commented Dec 6, 2016

thockin commented Dec 6, 2016 via email

davidopp commented Dec 6, 2016

thockin commented Dec 7, 2016 via email

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

thockin commented Dec 9, 2016 via email

thockin commented Dec 9, 2016 via email

thockin commented Dec 9, 2016 via email

soltysh commented Dec 12, 2016

thockin commented Dec 13, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

devin-donnelly commented Dec 21, 2016

thockin commented Dec 22, 2016 via email

devin-donnelly commented Dec 23, 2016

thockin commented Dec 23, 2016 via email

thockin commented Dec 27, 2016

thockin commented Jan 3, 2017

thockin commented Dec 5, 2016 •

edited by k8s-reviewable

Loading

smarterclayton Dec 5, 2016 •

edited

Loading