Define K8up Versioning and Release Process

[tobru]

Summary

As K8up developer
I want to know how the release process works and how the versioning scheme looks like
So that release are a breeze and versioning is consistent and makes sense

Context

The current release process is undefined (not documented / automated) and the versioning of K8up is arbitrary. The release process also doesn't take documentation into consideration.

Out of Scope

• Automate the release process -> Should be handled in a separate issue once it's clear how the release process should look like

Further links

• https://semver.org/
• https://docs.antora.org/antora/2.3/content-source-versioning-methods/
• Automatically assign version to component based on reference (branch or tag) name (refname) if version not specified

Acceptance criteria

Given a new K8up release is imminent
When I want to do a new release
Then I know exactly what the new version will be and how the process works

Implementation Ideas

• Use Semantic Versioning 2.0.0 as versioning scheme
• Document manual release process in README so that it later can be automated
• Create a branch and a tag per release (?)
• Release process must include: Release notes / Changelog, docs (version) update, ...

Implemented so far:

• K8up releases with semantic versioning, using the v prefix, e.g. v1.0.0
• K8up supports pre-releases with numbered release candidates, e.g. v1.0.0-rc1
• (Pre)Releases are triggered by pushing a git tag using the v prefix
• PreReleases push an image tag to docker.io and quay.io with the exact version tag, e.g. v1.0.0-rc1
• Commits to master releases an image tag with master tag
• Releases push images with exact version tag, e.g. v1.0.0
• Releases push images with floating latest tag and point to exact version tag ("latest stable release")
• Releases push images with floating Major version tag, e.g. v1
• The binaries and CRDs are attached to each GitHub Release for easy download
• The Changelog is automatically generated based on PRs. PRs need to have the following labels in order to show up in their category: bug, enhancement, dependency, change, breaking, documentation

[ccremer]

It looks like the process has to be first defined and the result is purely documentation. Does it make sense to move this issue into a GH Discussion (so we can try out the beta)?

[tobru]

I have put some much ❤️ into this issue 🙈 Honestly: Yes, why not, I don't mind...

[ccremer]

nothing is lost :)

[ccremer]

Other things to discuss, related to release roadmaps:

• Documentation of Migrations between Major versions of K8up
• Have a version policy for Operator API versioning (v1alpha1 to v1 or v2alpha1 etc)
• Define release process for Helm charts for major versions of K8up

[tobru]

We want to do pre-releases of K8up. How should we name them? rc? beta? I'd go for -rc.X just like Kubernetes does.

[tobru]

OK, this has been answered implicitly by the very first pre-release of K8up: https://github.com/vshn/k8up/releases/tag/v1.0.0-rc1

The scheme therefore is to add -rcX to the to-be-released version, starting with x=1.

[ccremer]

We can do another release with your proposed rc.X suffix. we can clean the docker tags and github release. Since it's just 1 release it's a thing done in 10 min

[tobru]

It's perfectly fine to have it without the dot. For example k3s also does it without a dot.

[corvus-ch]

We were in need for a pre-release and I opted to name it v1.0.0-rc1. rc (as in release candidate) is the most neutral term, alpha, beta etc imply some sort of maturity level and are hard to use correctly without a good definition. The - is required by Goreleaser as the trigger for a pre-release. Any other separating characters like the dot in -rc.X can confuse pattern matching. The number is required if we need more than one pre release.

[tobru]

Changelog generation could be done by for example using https://github.com/github-changelog-generator/github-changelog-generator and integration into goreleaser for fully automated releasing.

[ccremer]

With #248 being implemented now, I would like to discuss a detail for breaking changes.

When a PR is listed under "breaking changes", then a link is generated to that PR. I would propose that we update the PR description with either the action needed for users directly, or at least give a link to documentation with any migration guide.

My thought process is, that if a breaking change is listed there, I'd click on the PR to find out more about the change. I then expect some summary, reasons or other documentation that helps me in preparing the release upgrade. This could be a simple link to documentation if any upgrade notes are documented elsewhere. Might also need to be done after the release so that linking to the correct (tagged) version stays stable.

Should we make that part of the release process? Or should we simply update the PR template with a section for documenting breaking changes (which can be deleted if not the case) and hope PR authors and reviewers will maintain this?

Or should we simply have a section in the documentation like "Migration guide from 1.x to 2.x" and "Migration guide from 2.x to 3.x", holding all breaking changes in one place? There would be a need to filter PRs by "breaking" label and then create/update documentation based on those

[tobru]

My idea is to document upgrade steps in https://k8up.io/k8up/1.0.0/how-tos/upgrade.html, having a link there in the PR certainly helps.

As the documentation is part of the code I expect that a PR labeled for a breaking change also includes an update to this part of the documentation. (Of course updating documentation should be part of every PR when applicable).

[ccremer]

Following up an internal discussion with @tobru and @akosma regarding documentation with Antora

starting situation

• We have documentation together with code. They follow the same semver release semantics
• We use Antora as documentation system. Antora doesn't use the git tag as the version number, instead it's required to set the version number in a antora.yml config file.
• This limitation makes the release process more complicated, since we have to commit the next version into the file, and then creating the git tag thereof.

Possible options (that I know of)

• Document a release process that we have to follow manually before doing a git tag.
• Automate said release process. Instead of pushing a git tag, we could trigger a GH workflow manually with input variable so that it bumps the version in antora.yml from the variable and then commits & tags the release. The trigger can happen in the GH UI.
• Only use the Major version number in the Antora version selector. Every 1.x release just points to a "v1" version tag in k8up.io
• Hack Antora so that Antora supports picking the version from git ref instead of antora.yml. See https://gitlab.com/antora/antora/-/merge_requests/580/diffs

[tobru]

Having an Antora documentation for each patch version isn't needed. We only need a version per minor version, so 0.x, 1.x, 1.y, 2.x. If the referenced merge request would allow to pin the documentation version to the Git tag that would be fantastic of course.

[ccremer]

Having an Antora documentation for each patch version isn't needed.

So we still need to follow (and not forget about) the process to manually patch the config file.

If the referenced merge request would allow to pin the documentation version to the Git tag that would be fantastic of course.

not sure what you mean? How does the MR/PR know which git it should be pinning if the git tag is done after merging?