Adding a release page under "Release Information" #27929

jimangel · 2021-05-10T03:55:45Z

Fixes: #20293

TL;DR: I consolidated all release information under k8s.io/releases including all general automation around content updating (based off of SIG Release's schedule.yaml).

Working with SIG Release and SIG Docs, I'm proposing a "MVP," or "Phase 1," of consolidating Kubernetes' release documentation. A wave of improvements could follow once this foundation exists.

The ultimate goal is to raise visibility into the Kubernetes release cycle and reduce website information fragmentation. (More history in original issue: #20293)

Given the countless ways to consume and visualize release data, this PR focuses on a few high-level goals:

Allow for SIG Docs/Release Co-ownership
Data driven (no manual maintenance)
No dual sourced files*
No broken links
No stale release history in previous version docs (ex: https://v1-21.docs.kubernetes.io/releases)

*dual sourced as in created and maintained in two locations.

If folks agree with this approach, I recommend merging this PR, after initial review, and we can iterate on feedback after? 👍 👎

General Architecture

[k/sig-release]--copy-->[k/website/data]--generate-->[k/website/releases]

A folder created in content/en/releases creates a new k8s.io/releases page.

A script ./scripts/update-release-info.sh copies release markdown pages from SIG Release.

Data for Kubernetes versions is copied from SIG Release and stored in data/releases/schedule.yaml

All content copied over has a modified front matter of type: docs prepended in order to inherit the main "/docs" theme for consistency.

A new shortcode {{< release-data >}} was created to render release information from data/releases/schedule.yaml in layouts/shortcodes/release-data.html. This section could be broken into a couple partials or multiple shortcodes. However, I found keeping everything in a single file made it easier to connect all the parts.

content/en/releases/_index.html builds the entire section and pulls the latest html-ready release data using the shortcode {{< release-data >}}

An OWNERS file is placed in data/releases/, content/en/releases/ that includes SIG Release.

Summed up:

Copy over SIG Release markdown to k/website (content/en/releases/)
Copy over SIG Release schedule data to k/website (data/releases/schedule.yaml)
Generate "Release Information" under k8s.io/releases (content/en/releases/_index.html -> layouts/shortcodes/release-data.html)

In the future, SIG Release could move their data source to k/website and the process would be automated 100% with co-ownership between SIG Docs and SIG Release.

Other minor changes included in this PR

Added a link in the community page to "Releases"
Moved /setup/releases to /releases
- Copied file version-skew-policy.md (added type: docs)
- /docs/setup/version-skew-policy/ /docs/setup/release/version-skew-policy/ 301 changed to /docs/setup/version-skew-policy/ /releases/version-skew-policy/ 301
- Created redirect /docs/setup/release/ /releases/ 301
- Created redirect /docs/setup/release/version-skew-policy/ /releases/version-skew-policy/ 301
- Created file notes.md (added type: docs)
- Deleted directory /docs/setup/release/notes/
- Created redirect /docs/setup/release/notes/ /releases/notes/ 301
- Tested redirects via Netlify build
SIG Release OWNERS updated
- OWNERS_ALIASES updated from git.k8s.io/release/OWNERS_ALIASES
  - release-engineering-approvers
  - release-engineering-reviewers
- OWNERS file added to data/releases/, content/en/releases/ including the above approvers / reviewers.

Open questions & items (non blocking)

versionSkew shortcode could be improved to use data/releases vs. site.Params (and math)
Could this fix any of the release docs process (updating the config.toml)?
Any Localization adoption challenges?
How far back should we include for history? (updating data/releases/schedule.yaml)
How could this better be integrated into SIG Release? (krel / schedule-builder)
How to better consolidate the release notes vs. relnotes.k8s.io vs. ...?
I think we could automate the release binary downloads if we could update data/releases/schedule.yaml with URLs (replacing what downloadkubernetes.com does)
- Something like: https://golang.org/dl/?

To update everything

chmod +x ./scripts/update-release-info.sh 
./scripts/update-release-info.sh

Next steps

Add links with examples once page renders
Verify k8s.io/releases works
~~Does having data in /data/releases/ make the most sense? (localization?)~~
Sign off from SIG Release (:wave: @LappleApple @justaugustus @tpepper @saschagrunert)
Sign off from Docs release lead (:wave: @PI-Victor)
Sign off from majority of SIG Docs Co-Chairs & Tech leads (:wave: @irvifa @kbarnard10 @kbhawkey @onlydole @sftim)
Update schedule-builder and other copied files with reference comments
Add redirects to older release-x.y websites to current page (update release handbook too)

/kind feature
/cc @kubernetes/release-engineering @kubernetes/sig-docs-en-owners @mkorbi
/priority important-soon
/sig release
/sig docs
/language en
/hold for review

netlify · 2021-05-10T04:08:20Z

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

Built with commit 7edf890

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

jimangel · 2021-05-10T04:27:16Z

Fly-by review:

Release page is in drop down "Version" menu and accessible via: https://deploy-preview-27929--kubernetes-io-master-staging.netlify.app/releases

The section is added to "Community."

Currently supported releases (from the data file) are summarized and shown automatically.

The other pages work:

The redirects work:

sftim · 2021-05-10T13:16:47Z

https://deploy-preview-27929--kubernetes-io-master-staging.netlify.app/releases/ looks much better than https://kubernetes.io/docs/setup/release/

I'll review more later.

content/en/releases/notes.md

scripts/update-release-info.sh

sftim · 2021-05-10T13:25:25Z

scripts/update-release-info.sh

+---
+EOF
+
+curl https://raw.githubusercontent.com/kubernetes/sig-release/master/releases/patch-releases.md >> content/en/releases/patch-releases.md


Future work: split https://github.com/kubernetes/sig-release/blob/master/releases/patch-releases.md into 2 pages, one for https://k8s.dev/ and one for https://k8s.io/docs/

scripts/update-release-info.sh

static/_redirects

mrbobbytables

Quick review just highlighting some of the links that will need to be updated via the script.

content/en/releases/patch-releases.md

content/en/releases/release.md

sftim

@jimangel this looks really really promising. I also have a bit more feedback.

layouts/shortcodes/release-data.html

kbhawkey · 2021-05-11T01:22:36Z

OWNERS_ALIASES

@@ -233,3 +233,20 @@ aliases:
    - mrbobbytables
    - nikhita
    - parispittman
+  # authoritative source: git.k8s.io/release/OWNERS_ALIASES
+  release-engineering-approvers:
+    - cpanato # Release Manager


@jimangel . I am reading through the changes.
My first reaction is that this is a largish list of approvers/reviewers to add to the docs repository.
Why is this needed/for what purpose?

I appreciate the concern! Adding them to the OWNERS_ALIASES doesn't give them the level of authority the name implies. We could change that, but I copied it as is from git.k8s.io/release/OWNERS_ALIASES. The groups are used to reference approvers & reviewers in their respective release sub folders (via sub OWNERS file).

The release data that is being used by SIG Docs is owned by SIG Release. We'd like to have them store date in our repo for generation purposes. In order to do that efficiently, it made sense to grant SIG Release folks access to their respective sub directories.

We could also demo this MVP with a smaller list to start if you'd be more comfortable! Let me know if that helps. It's also possible I messed up my understandings of OWNERS files 😅

kbhawkey · 2021-05-11T01:24:40Z

content/en/releases/_index.md

+
+<!-- overview -->
+
+The Kubernetes project maintains release branches for the most recent three minor releases ({{< skew latestVersion >}}, {{< skew prevMinorVersion >}}, {{< skew oldestMinorVersion >}}).  Kubernetes 1.19 and newer receive approximately 1 year of patch support. Kubernetes 1.18 and older received approximately 9 months of patch support.


Is there another doc that lists or describes the Kubernetes patch support rules?

I stole that overview from "https://kubernetes.io/docs/setup/release/version-skew-policy/" because I thought it was helpful (although recognized duplication). The version skew policy page has been relocated to this new menu and I've added redirects from the old location.

I'm open to any alternative suggestions for the main overview!

At this point I think we can drop the bit about k8s 1.18 and older:

Suggested change

The Kubernetes project maintains release branches for the most recent three minor releases ({{< skew latestVersion >}}, {{< skew prevMinorVersion >}}, {{< skew oldestMinorVersion >}}). Kubernetes 1.19 and newer receive approximately 1 year of patch support. Kubernetes 1.18 and older received approximately 9 months of patch support.

The Kubernetes project maintains release branches for the most recent three minor releases ({{< skew latestVersion >}}, {{< skew prevMinorVersion >}}, {{< skew oldestMinorVersion >}}). Kubernetes 1.19 and newer receive approximately 1 year of patch support.

I don't think it hurts to leave it in for a little longer. I could be sold either way. 🤷

I agree. I would leave it in a little longer.

kbhawkey · 2021-05-11T01:47:56Z

content/en/releases/patch-releases.md

@@ -0,0 +1,188 @@
+---
+title: Patch Release Details
+type: docs


What is the type?

This is somewhat of a "hack" to have Hugo look at /layouts/docs/ for it's templates. It allows me to use the same "Docs" 3-bar theme for a handful of release docs. It also reduces the need for me to create custom CSS.

kbhawkey · 2021-05-11T02:12:22Z

Hi @jimangel . Some initial feedback:
The copied release pages seem okay. I guess the site offers a place to publish the release content for the release team.
How/when is the script run (release time)?
Would you consider including the release information in the docs content tree?
Why should the "Release Information" add to the Version drop down list? It does not really fit into this list.
What are the alternatives to providing ownership/approval to parts of this repository (another way of retrieving the release content and creating HTML content)?

jimangel · 2021-05-11T02:38:33Z

Thanks for the review @kbhawkey. I updated some of your comments inline and will answer the rest here.

The copied release pages seem okay. I guess the site offers a place to publish the release content for the release team.

Exactly. This PR adds a location for release content and grants SIG Release co-ownership.

How/when is the script run (release time)?

The script could be ran as needed at first (by release team or docs team). The ultimate goal would be to allow SIG Releases tooling to open the PR to update the data file. While the data is important, I don't believe it needs to be 100% automated to get started -- yet.

Would you consider including the release information in the docs content tree?

I'm not sure what you're referencing here. Would you mind clarifying? As far as the current content, I would be ok with removing a lot of it if it improves the end user experience.

Why should the "Release Information" add to the Version drop down list? It does not really fit into this list.

Totally agree! I REALLY wanted it to be a big header that said, "RELEASES" but when I set it up, it looked very strange next to "VERSIONS." I would imagine that would be hard to understand from a new user too. I don't love it where it is now (under the Versions menu) but it seems to make the most logical sense. I'm up for any additional placement / title! Any suggestions?

What are the alternatives to providing ownership/approval to parts of this repository (another way of retrieving the release content and creating HTML content)?

There's alternative ways to run scripts (via Hugo, Netlify, Makefiles / shell) to capture content from URL endpoints. The concern with that is the reliance of data connectivity and increasing the complexity of our build dependencies. I would be up for alternative suggestions but I do feel like there is a very limited scope of access being opened up to SIG Release.

As always, thanks again for your review / attention to detail!

saschagrunert

Generally I'm very supportive about this, glad to see it landing ❤️

Thanks @jimangel! 🙏

layouts/partials/navbar-version-selector.html

pmmalinov01 · 2021-05-11T19:39:57Z

This is amazing work. Thank you for it +1
/lgtm

content/en/releases/patch-releases.md

data/releases/schedule.yaml

celestehorgan · 2021-05-11T20:42:11Z

scripts/update-release-info.sh

+
+EOF
+
+curl --retry 3 https://raw.githubusercontent.com/kubernetes/sig-release/master/releases/patch-releases.md >> content/en/releases/patch-releases.md


Non-blocking: Worth noting that when branch names flip over to main, this script will break

@celestehorgan -- We'll obviate the need for this ahead of any branch renames.

jimangel · 2021-05-11T22:24:19Z

/unhold

I just updated with everyone's actionable feedback. I left the open-ended questions posted for reference later. This is ready to lgtm / merge in my opinion.

I would like +1/2 from a few more @kubernetes/sig-docs-leads 🙏 ❤️

justaugustus · 2021-05-11T22:29:13Z

re-lgtm on behalf of SIG Release
/lgtm

k8s-ci-robot · 2021-05-11T22:29:22Z

LGTM label has been added.

Git tree hash: b72f57c9c8bde0485f2885f9786b9ed10730c547

irvifa

/lgtm

bradtopol · 2021-05-12T03:13:40Z

I am very supportive of this. This is outstanding work! Great job @jimangel!!!
/lgtm

saschagrunert

/lgtm

sftim · 2021-05-12T08:09:35Z

Given #27929 (comment) and other LGTMs
/approve

k8s-ci-robot · 2021-05-12T08:09:48Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: justaugustus, saschagrunert, sftim

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

The pull request process is described here

Needs approval from an approver in each of these files:

~~OWNERS~~ [sftim]

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

sftim · 2021-09-15T08:08:49Z

Issue #29711 requests enhancing this with release date information

k8s-ci-robot requested a review from mkorbi May 10, 2021 03:55

jimangel force-pushed the release-page-v2.0 branch 2 times, most recently from 09600cf to aa2cad9 Compare May 10, 2021 04:26

sftim reviewed May 10, 2021

View reviewed changes

sftim mentioned this pull request May 10, 2021

Create a "releases" page #22736

Closed

mrbobbytables reviewed May 10, 2021

View reviewed changes

content/en/releases/patch-releases.md Show resolved Hide resolved

content/en/releases/release.md Show resolved Hide resolved

content/en/releases/release.md Show resolved Hide resolved

sftim reviewed May 10, 2021

View reviewed changes

layouts/shortcodes/release-data.html Outdated Show resolved Hide resolved

layouts/shortcodes/release-data.html Outdated Show resolved Hide resolved

layouts/shortcodes/release-data.html Outdated Show resolved Hide resolved

kbhawkey reviewed May 11, 2021

View reviewed changes

jimangel force-pushed the release-page-v2.0 branch from aa2cad9 to b2a77ec Compare May 11, 2021 02:11

k8s-ci-robot added the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label May 11, 2021

jimangel force-pushed the release-page-v2.0 branch from b2a77ec to 83559ca Compare May 11, 2021 02:45

k8s-ci-robot removed the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label May 11, 2021

jimangel force-pushed the release-page-v2.0 branch 2 times, most recently from 11f9ccd to 69311b1 Compare May 11, 2021 03:02

saschagrunert reviewed May 11, 2021

View reviewed changes

layouts/partials/navbar-version-selector.html Outdated Show resolved Hide resolved

k8s-ci-robot assigned savitharaghunathan May 11, 2021

k8s-ci-robot assigned pmmalinov01 May 11, 2021

celestehorgan reviewed May 11, 2021

View reviewed changes

content/en/releases/patch-releases.md Outdated Show resolved Hide resolved

celestehorgan reviewed May 11, 2021

View reviewed changes

data/releases/schedule.yaml Show resolved Hide resolved

celestehorgan reviewed May 11, 2021

View reviewed changes

Adding a release page under "Release Information"

7edf890

jimangel force-pushed the release-page-v2.0 branch from 3721222 to 7edf890 Compare May 11, 2021 22:19

k8s-ci-robot removed the lgtm "Looks good to me", indicates that a PR is ready to be merged. label May 11, 2021

k8s-ci-robot removed the do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. label May 11, 2021

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label May 11, 2021

irvifa reviewed May 12, 2021

View reviewed changes

k8s-ci-robot assigned irvifa May 12, 2021

k8s-ci-robot assigned bradtopol May 12, 2021

saschagrunert approved these changes May 12, 2021

View reviewed changes

k8s-ci-robot assigned saschagrunert May 12, 2021

k8s-ci-robot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label May 12, 2021

k8s-ci-robot merged commit 6845b64 into kubernetes:master May 12, 2021

This was referenced May 15, 2021

releases: Update patch release schedule and add Release Manager info #27997

Merged

Move patch release schedule and Release Managers pages to k8s.io kubernetes/sig-release#1577

Merged

jimangel mentioned this pull request Aug 17, 2021

Create a Hugo layout to not display release information on older versions of k8s.io #29428

Closed

sftim mentioned this pull request Sep 9, 2021

Describe release cadence, version numbering, etc #15088

Closed

jai mentioned this pull request Sep 15, 2021

Specify the date of releases #23394

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Adding a release page under "Release Information" #27929

Adding a release page under "Release Information" #27929

jimangel commented May 10, 2021 •

edited

Loading

netlify bot commented May 10, 2021 •

edited

Loading

jimangel commented May 10, 2021 •

edited

Loading

sftim commented May 10, 2021

sftim May 10, 2021

mrbobbytables left a comment

sftim left a comment

kbhawkey May 11, 2021 •

edited

Loading

jimangel May 11, 2021

kbhawkey May 11, 2021

jimangel May 11, 2021

celestehorgan May 11, 2021

jimangel May 11, 2021

bradtopol May 12, 2021

kbhawkey May 11, 2021

jimangel May 11, 2021

kbhawkey commented May 11, 2021

jimangel commented May 11, 2021

saschagrunert left a comment

pmmalinov01 commented May 11, 2021

celestehorgan May 11, 2021 •

edited

Loading

justaugustus May 11, 2021

jimangel commented May 11, 2021

justaugustus commented May 11, 2021

k8s-ci-robot commented May 11, 2021

irvifa left a comment

bradtopol commented May 12, 2021

saschagrunert left a comment

sftim commented May 12, 2021

k8s-ci-robot commented May 12, 2021

sftim commented Sep 15, 2021


		<!-- overview -->

		The Kubernetes project maintains release branches for the most recent three minor releases ({{< skew latestVersion >}}, {{< skew prevMinorVersion >}}, {{< skew oldestMinorVersion >}}). Kubernetes 1.19 and newer receive approximately 1 year of patch support. Kubernetes 1.18 and older received approximately 9 months of patch support.


		EOF

		curl --retry 3 https://raw.githubusercontent.com/kubernetes/sig-release/master/releases/patch-releases.md >> content/en/releases/patch-releases.md

Adding a release page under "Release Information" #27929

Adding a release page under "Release Information" #27929

Conversation

jimangel commented May 10, 2021 • edited Loading

General Architecture

Other minor changes included in this PR

Open questions & items (non blocking)

To update everything

Next steps

netlify bot commented May 10, 2021 • edited Loading

jimangel commented May 10, 2021 • edited Loading

sftim commented May 10, 2021

Choose a reason for hiding this comment

mrbobbytables left a comment

Choose a reason for hiding this comment

sftim left a comment

Choose a reason for hiding this comment

kbhawkey May 11, 2021 • edited 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

kbhawkey commented May 11, 2021

jimangel commented May 11, 2021

saschagrunert left a comment

Choose a reason for hiding this comment

pmmalinov01 commented May 11, 2021

celestehorgan May 11, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jimangel commented May 11, 2021

justaugustus commented May 11, 2021

k8s-ci-robot commented May 11, 2021

irvifa left a comment

Choose a reason for hiding this comment

bradtopol commented May 12, 2021

saschagrunert left a comment

Choose a reason for hiding this comment

sftim commented May 12, 2021

k8s-ci-robot commented May 12, 2021

sftim commented Sep 15, 2021

jimangel commented May 10, 2021 •

edited

Loading

netlify bot commented May 10, 2021 •

edited

Loading

jimangel commented May 10, 2021 •

edited

Loading

kbhawkey May 11, 2021 •

edited

Loading

celestehorgan May 11, 2021 •

edited

Loading