Nice approach

/lgtm

Addressed nits, can be merged after review / CI. Thanks!

/hold

I want to think about this more... I would love to use this as part of resolving #14307

The current issue is: Once this merges and gets pushed to older versions (release-1.13 -> 1.17), it will no longer be nextMinorVersion. It would be "this (old) version + 1."

Thoughts?

@jimangel , for my own information, is there a k8s doc that describes versioning? For example,
under what circumstances will the major version move to 2 (minor version 0)?
The next (minor) version is relative to the version (not necessarily the minor version assoc with the latest version). Also, the minor version is a component of the version, <major>.<minor>.

Funny you ask! Essentially no... https://github.com/kubernetes/sig-release/tree/master/release-team#during-major-releases

I would imagine that getting all of the APIs to GA would be a big part of that, but that's me speculating.

The current issue is: Once this merges and gets pushed to older versions (release-1.13 -> 1.17), it will no longer be nextMinorVersion. It would be "this (old) version + 1."

What's the “it” in those sentences? (I'm not sure I know).

What's the “it” in those sentences? (I'm not sure I know).

The nextMinorVersion:

For example, let's say we use nextMinorVersion as a key in version skew doc representing the upcoming release.

When the release is cut, master is now a new version, we move the state of master into a release-vX.y.z. This now involves touching config.tomls in all branches to represent this shift (version shifts, dropping the oldest supported, etc).

I don't think it's impossible for the release lead to manage this, but I think it's unwelcome complexity. I'm going to try an alternate approach today / tomorrow.

👋 @jimangel, Is this PR still in progress?

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

Built with commit 00b106a

https://deploy-preview-18173--kubernetes-io-master-staging.netlify.com

My reluctance to merge this was because, at some point, all releases will have a latest and a nextMinorVersion after latest. Not a huge impact to my "start contributing" document change, but somewhat strange for the skew documents I mentioned (if you're on a v1.14 docs page and the skew document is referencing 1.19; that's weird).

Traditionally, older releases were "cut-off" from changes that were not security related or of MAJOR impact.

After further review, even if we keep the nextMinorVersion current throughout all releases and the impact is that all release branches share the same skew document, I can't see a negative. As it is today, the skew document is incredibly out of date and it has had no impact or distaste.

Leaving this PR to be "as-is" and we can tweak as we see fit. Ready to merge with approval.

@VineethReddy02 will need to update the Docs release handbook with this change too.

/hold cancel

/hold

@sftim @kbhawkey I rebased 😄 but I really want to incorporate a change that fixes ALL version pages:

• https://kubernetes.io/docs/contribute/start/#choose-which-git-branch-to-use
• https://kubernetes.io/docs/setup/release/version-skew-policy
• Potentially a new release page that compares to what https://en.wikipedia.org/wiki/Kubernetes#Release_Versions has

We can merge this as is if we want, but I think we need a programmatic way to reference each version (n, n+1, n-1) and have an approach that deprecates nicely for each release.

Can either of you think of the best way to reference n-1 (for the skew policy)? We have the variable set in config.toml (params.versions).

Thoughts?

We can merge this as is if we want, but I think we need a programmatic way to reference each version (n, n+1, n-1) and have an approach that deprecates nicely for each release.

Can either of you think of the best way to reference n-1 (for the skew policy)? We have the variable set in config.toml (params.versions).

Thoughts?

@jimangel , If I understand correctly, you are looking for a way to use a Hugo template or shortcode to express the semantic versioning in the skew and contrib docs?
Currently, only the minor and patch versions need to change and every version string published in the docs is based off of the latest field (from config.toml). Using a shortcode helps to maintain the versioning info in the docs. You don't want to update config.toml every time a minor or patch version changes.

You could split (or use a reg. expression to tease out the version info) latest string and use the Hugo (go) Math functions (https://gohugo.io/functions/math/), to create two new strings that contain the prev and next for the release version, n-1, n+1.
In the simplest case, you could create two templates (shortcodes?):
latest-plus-one (or some number)
latest-minus-one

Is this what you are thinking?

@jimangel , If I understand correctly, you are looking for a way to use a Hugo template or shortcode to express the semantic versioning in the skew and contrib docs?

After thinking about this, we have two problems and I'm on the fence how this PR solves Problem 1.

Problem 1:

Fix contrib docs and skew docs with variables.

This PR adds n+1 and can be used to fix our contrib docs and, if we had a way to call n-1 (maybe another shortcode or math as you mention), could fix skew too.

In today's case, those variables needed would be: 1.19, 1.18, 1.17

Problem 2:

Creating a release page that is up to date with our releases semantic versioning.

Something very similar to:

• https://wiki.ubuntu.com/Releases
• https://www.kernel.org/category/releases.html
• https://en.wikipedia.org/wiki/Kubernetes#Release_Versions

You don't want to update config.toml every time a minor or patch version changes.

This might be a "when you're a hammer everything is a nail" view-point. But I actually was thinking of updating config.toml for each patch version 😅. At some point this would be automated, but until then I could work with the patch release team to open an issue on sig-docs for a fix each release (good first issue!). The patch releases are fairly consistent and scheduled: https://github.com/kubernetes/sig-release/blob/master/releases/patch-releases.md#timelines unless there's a security / CVE quick patch.

This is where I am lost...

We currently have each minor or patch version in config.toml under fullversion: (https://github.com/kubernetes/website/blob/master/config.toml#L98-L131) we just don't do the best job at updating it.

Any thoughts on how we could use those variables in a table? If it's not simple, do you think it would be worth creating it's own block of variables for this use case?

var1: 1.18.x
var2: 1.17.x
var3: 1.16.x

We only need 3 since the k8s community only supports 3 releases, after that, we can convert the variable to text after the "last release."

Originally I was getting bent on the complexities of the release cycle (ie: how does it impact previous release docs) but I think we just wrap the old pages in a shortcode that says "look at master release doc."

You could split (or use a reg. expression to tease out the version info) latest string and use the Hugo (go) Math functions (https://gohugo.io/functions/math/), to create two new strings that contain the prev and next for the release version, n+1, n-1.

If you have a suggestion for getting n-1 to solve Problem 1, This PR would be good to merge since it solves contrib and skew.

Problem 2 can be another issue / PR - I just wanted to capture my thoughts here. Many thanks @kbhawkey!

@jimangel ,
re: Problem 2, I see the release/version tables from the links. Couple of questions:

• Where would you get most of the information for the table (release name, release date, link to release notes)? You want to use the items in, params.versions and call a template or shortcode to populate a Markdown file with a table.
• Would this doc publish from the website?

Here is a shortcode to get the next or prev version based off of latest.

{{- $latestVersion := site.Params.latest -}}
{{- $latestVersion := (replace $latestVersion "v" "") }}
{{- $nextMinorVersion := 0 -}}
{{- $prevMinorVersion := 0 -}}

{{- $versionArray := split $latestVersion "." -}}
{{- $minorVersion := int (index $versionArray 1) -}}
{{- $nextMinorVersion := add $minorVersion 1 -}}
{{- $prevMinorVersion := sub $minorVersion 1 -}}
{{- $latestVersion := $nextMinorVersion -}}
{{- $nextMinorVersion := printf "%s.%d" (index $versionArray 0) $nextMinorVersion -}}
{{- $nextMinorVersion -}}

Could update the shortcode to take an arg (next or prev).

This has been open so long the page was rewritten 😅 I think there's still some work to do on the content, but the shortcode works and I can use this solution to fix the skew page as well.

Ready to merge after review. @kbhawkey @sftim @tengqm

/hold cancel

Aside for code spelunkers: this approach might need to change when Kubernetes has two next releases due: an upcoming minor version release and an upcoming major version release.

/sig release

Page preview:
https://deploy-preview-18173--kubernetes-io-master-staging.netlify.com/docs/contribute/new-content/new-features/#for-developers-or-other-sig-members

Thanks @jimangel
/approve

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: kbhawkey

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

The pull request process is described here