Adding Links to Deprecations for Each Release and new Deprecations Page

[drewhagen]

This is a Feature Request

:information_source: If this sounds like a feature you'd like, please add a :+1: reaction under the description.

What would you like to be added

A comprehensive and easily accessible deprecations and removals section for each Kubernetes release on the Kubernetes website. This should include a new page titled “Deprecations in this release,” which would cover all types of deprecations (APIs, support for old versions, etc.) and provide links or references to the API deprecation reference. Additionally, a feature to filter deprecations by specific Kubernetes versions would be beneficial.

Why is this needed

Currently, users face challenges in finding comprehensive deprecation information for different Kubernetes versions, especially when planning upgrades that span multiple versions. Having a centralized and detailed deprecation guide will aid users in better understanding the impact of upgrades and the necessary actions for a smooth transition.

Comments

This enhancement would involve updating the /releases/ page to refer to the new broader deprecations page. It may also include restructuring the existing API deprecations page into a pure reference and a per-release migration guide. Collaboration between SIG Docs and SIG Release could be necessary to gather and maintain this information.

Technical Notes:

Link to Release History page on the website. The markdown for the Release History page is documented here, which uses the shortcode pointing to HTML here and then using Hugo to template data located here.

Mockups

Linking to deprecations from the release history page...

OR

but as I understand it, we'd have to create the new deprecations page that these link to.

X-post (Slack conversation): https://kubernetes.slack.com/archives/C0156PJ62RE/p1705954754517599

cc: @sftim

[drewhagen]

/sig release /language en

[sftim]

/priority important-longterm /sig docs

/triage accepted

[arujjval]

Where can we find the info related to deprecations?

[sftim]

Where can we find the info related to deprecations?

https://kubernetes.io/releases/notes/ links to pages that have quite a lot of the detail, but it's not yet presented how we'd like. Contributors working on this issue can also refer to the blog articles for the announcements of each minor release, the mid-release announcements of upcoming deprecations, and https://kubernetes.io/docs/reference/using-api/deprecation-guide/

I expect there's four parts for this work:

1. design the layout and user experience for a new page
2. for the English localization, collate and write content for that new page
3. work out how we'll help readers find the deprecation details for their Kubernetes distribution, if they use one
   • we might link to any certified Kubernetes distribution's deprecation guide
   • we might link to any deprecation guide that somebody asks us to (I see this as unlikely, but the decision is open.
4. define and document the process that needs to be followed, each minor or major release, to ensure that page stays current

[arujjval]

Where can we find the info related to deprecations?

https://kubernetes.io/releases/notes/ links to pages that have quite a lot of the detail, but it's not yet presented how we'd like. Contributors working on this issue can also refer to the blog articles for the announcements of each minor release, the mid-release announcements of upcoming deprecations, and https://kubernetes.io/docs/reference/using-api/deprecation-guide/

I expect there's four parts for this work:

1. design the layout and user experience for a new page
2. for the English localization, collate and write content for that new page

3. work out how we'll help readers find the deprecation details for their Kubernetes distribution, if they use one

   • we might link to any certified Kubernetes distribution's deprecation guide
   • we might link to any deprecation guide that somebody asks us to (I see this as unlikely, but the decision is open.
4. define and document the process that needs to be followed, each minor or major release, to ensure that page stays current

So we have to make new pages that are something similar to Deprecated API Migration Guide ?

[dshebib]

From looking at the deprecation policy it seems that the challenge is to centralize the following types of deprecations into a single page:

1. Deprecated APIs
2. CLI's/flags
3. Features
4. Metrics
5. Plugins

Based on currently available resources it seems that for each deprecation type:

1. These are listed in the deprecated API guide. Deprecated or breaking changes in changelogs which are not reflected here should likely be part of a separate issue
2. These may be less important as the CLI itself will issue a warning. The only centralized location for these seems to be the individual version changelogs
3. These are implicitly listed in Feature Gates, but despite having multiple tables there is no way to look up a list of deprecated features by version
4. Because these are exposed through an API, these should already be in the deprecated api guide (and it looks like they are, but could need verification)
5. These are not listed in any deprecation reference, but are potentially important (e.g. the deprecation of included aws and azure authentication plugins in kubectl to separate plugins that must be installed separately)

I am seeing some potential steps to proceed:

1. Make a list of deprecated feature gates per-version parsed from Feature Gates. This includes feature gates that have been dropped from alpha or have been graduated from beta to GA and are no longer available to be specified, and only the changes from the previous major version.
2. Make a new page combining the list of deprecated feature gates with the existing Deprecated API Guide page to make a complete deprecation guide that lists, for each major version, deprecated APIs, breaking API changes, and deprecated or graduated feature gates. We may need to verify manually the accuracy of the API changes listed in the Deprecated API Guide as they seem pretty sparse.
3. In addition to the above, append important plugins or flags that have been deprecated or replaced in each version. This would have to be done manually from the changelogs in each release.
4. Organize the guide by having a section for each major version and link to each section under the releases page as in the second image mockup.

This is just a first pass so please correct me if the issues or steps seem incorrect. It does seem like users currently have to rely on changelogs or error messages from Kubernetes when upgrading.

[sftim]

From looking at the deprecation policy it seems that the challenge is to centralize the following types of deprecations into a single page:

1. Deprecated APIs
2. CLI's/flags
3. Features
4. Metrics
5. Plugins

That's part of it; however, we'd want to track removals too.

[dshebib]

I agree, in terms of covering the different types of removals and deprecations does this seem exhaustive? Im willing to make a mocked up example for the most recent release as a prototype to focus efforts.

[dshebib]

Mockup for v1.29

[sftim]

Thanks for the mockup.

Rather than “Deprecations by Kubernetes version”, I'd expect to see a heading “Deprecations and removals in Kubernetes v1.29” and then some links to help you find the equivalent page for other minor releases.

[dshebib]

Added a page in #45356.

As we're thinking about older versions, adding older releases to the release page might be an easy first step.

[sftim]

We might find a content adapter useful; see https://gohugo.io/content-management/content-adapters/

Not sure.

[sftim]

Only one upvote?