Create a "releases" page

[sftim]

• Add a page listing Kubernetes releases [preview]
• Add a page that links, via GitHub, to how to download each patch release for the current minor version [preview]

To make this work the release process needs to change: after the release artifacts are available and GitHub is updated, run scripts/update_releases.sh and commit the changes to data/releases/dates.json.

At a stretch you can say that this fixes #20293
although there is clearly room for improvement.

[netlify]

Deploy preview for kubernetes-io-master-staging ready!

Built with commit 3b76dd2

https://deploy-preview-22736--kubernetes-io-master-staging.netlify.app

[sftim]

/sig release

[jimangel]

This is a great start @sftim, thanks for working on this!

General comments / opinions:

• A root /releases page would be preferred, if possible; even if it's an alias.
• For the sake of maintaining, I was planning on only having the master branch docs contain up to date information.
  • Older versions would have shortcode (like the deprecation shortcode) linking to current docs
  • This prevents any strange edge cases of back-ported fixes, patches, or extended cycles
  • Can anyone think of a time where it matters what versions Kubernetes release team supported during the previous release?
  • We'll have to expand this PR's scope to include all supported releases
• Talking with the release team, it seems like it would make sense to keep the data in a single location (like k/sig-release)
  • That might mean scraping data from that repo instead of GitHub
• The process to update the data should be transferred to the release engineering team (once complete)

Not sure if we could leverage something like https://github.com/kubernetes/release/tree/master/cmd/schedule-builder (creates: https://github.com/kubernetes/sig-release/blob/master/releases/schedule.yaml)

I love the use of data templates in this case!

/cc @tpepper @justaugustus

[sftim]

A root /releases page would be preferred, if possible; even if it's an alias.

👍
I think what we want is to have the navigation (breadcrumb trails etc) look similar to this draft but actually give the releases page a canonical URL of https://kubernetes.io/releases/

Not sure how to do that, but it sounds possible.

[sftim]

For the sake of maintaining, I was planning on only having the master branch docs contain up to date information.

I wouldn't use a shortcode for that, but yes that sounds achievable.

[sftim]

We already have a deprecation message, so I'm assuming that the release page for a previous release would say something like

Kubernetes v1.18 documentation is no longer actively maintained. The version you are currently viewing is a static snapshot. For up-to-date documentation, see the latest version.

[kbhawkey]

Hello, all.
Are you targeting these changes for the v1.19 release?

[sftim]

I suspect it's a bit close to the v1.19 release to get this finished. I'd be happy to get this over the line for v1.19 though!

[sftim]

For the release process I have in mind, we might (manually? semi-automatically?) configure documentation for previous releases to automatically redirect some of the release pages to the live site.
This would mean adding redirects each time we cut a branch for a now-previous release.

As a sort of belt-and-braces approach, I've also made Hugo render a link to the current docs in place of showing the release notes list.

What else needs to change before this can go live? I'm keen to hear from SIG Release folks.

[sftim]

Relevant to issue #21063

[tpepper]

• Add a page listing Kubernetes releases

Can this be reverse chronological sort for freshest on top?

[tpepper]

• Add a page that links, via GitHub, to how to download each patch release for the current minor version [preview]

This one should be reverse chronological also. And it might should be trimmed to have just the most recent visible by default for simplicity, plus some collapsabled-by-default UI element to click to "view no longer supported releases".

Similar for the overall list of the 1.0..1.Y releases. Show the current 3 or 4 getting patch support and click to "view no longer supported releases" which are default hidden behind a UI element.

These lists will be growing eternally. We want to make finding the info easier, but also focus eyes on the most relevant ones.

Perhaps by doing this collapsing it's then not necessary to pop off to its own page all the 1.19.Z's and a page for all the 1.18.Z's, etc.?

[sftim]

@tpepper can you clarify if that recent feedback is “we must have these features before we can have a releases page” or “here are some extra features to prioritize once we do”?

I'd like to get something acceptable deployed, and then iterate.

[tpepper]

@sftim reverse chronological order I'd consider a must, but am also open to others' opinions on the UX.

Everything else definitely deploy and iterate.

[sftim]

When I drafted this, there was no v1.19
(and Netlify doesn't rebuild preview sites each time there is a merge into master - you have to manually rebase).

[sftim]

… if it's supposed to be sentence case for headings, then the title should be "Kubernetes releases".

On this website, page titles are in title case.

[kbhawkey]

Hello @sftim .
I am checking on the status of this pull request as the PR has been open for some time.

More feedback:

The current "Getting Started -> Kubernetes Releases" section lists only the current release note information (v1.19).
This is the current page, https://kubernetes.io/docs/setup/release/.

The proposed changes offer the list of release notes and a "Downloads" page.
I am not convinced that the Downloads page belongs in the docs.
Could the home page "Downloads" button point directly to a "kubernetes/kubernetes/download-a-release-page" (preferably a more permanent link so that the home page does not need to be updated per release).

I could imagine a "Release Notes" page that includes the list of release notes instead of a separate
page for the single release note (There is a link to the latest release note page from the docs home page).
I would list the latest release first (similar to how versions are listed in the site's version drop down list in the main nav).
I'd like one page to see all release notes.

To maintain this list of release notes, the script needs to run after the release (or at the end of the release)?
This seems like a reasonable task until an automated process can be created.
Are there other remaining questions?

[sftim]

I am not convinced that the Downloads page belongs in the docs.

Good point. Maybe Downloads could go in place of the Community link on the site navigation (and then we find a different way to signpost readers to https://k8s.dev/)

Overall, this is going to be a long term piece of work I suspect. I might not have time to work more on this until mid-November.

I hope to draw in more help, that'd be ideal.

[sftim]

@justaugustus (following up on a conversation from earlier, sort of) if the release metadata were already published in JSON, I could tell Hugo to render pages based on fetching it.

This approach is OK for a proof-of-concept but it's not really good enough to merge.

[sftim]

@jimangel is there any simple change I can make here to make this a better prototype?

(in other words - there's loads of improvements to potentially make, are there any that stand out as things to fix first)

[jimangel]

@sftim I've been chatting with @justaugustus after his email and we're working on a plan that aligns both SIG Docs and SIG Release. More to come, sorry for the long tail on this. Hopefully coming to a final direction soon!

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-contributor-experience at kubernetes/community.
/lifecycle stale

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
To complete the pull request process, please ask for approval from sftim after the PR has been reviewed.

The full list of commands accepted by this bot can be found here.

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[k8s-ci-robot]

@sftim: PR needs rebase.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[sftim]

Closing this in favor of #27929

[justaugustus]

Closing this in favor of #27929

/close

[k8s-ci-robot]

@justaugustus: Closed this PR.

In response to this:

Closing this in favor of #27929

/close

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.