RELEASE.md

Release schedule

Kube-prometheus has a somehow predictable release schedule, releases were historically cut in sync with OpenShift releases as per downstream needs. So far there hasn't been any problem with this schedule since it is also in sync with Kubernetes releases. So for every new Kubernetes release, there is a new release of kube-prometheus, although it tends to happen later.

How to cut a new release

This guide is strongly based on the prometheus-operator release instructions.

Branch management and versioning strategy

We use Semantic Versioning.

We maintain a separate branch for each minor release, named release-<major>.<minor>, e.g. release-1.1, release-2.0.

The usual flow is to merge new features and changes into the master branch and to merge bug fixes into the latest release branch. Bug fixes are then merged into master from the latest release branch. The master branch should always contain all commits from the latest release branch.

If a bug fix got accidentally merged into master, cherry-pick commits have to be created in the latest release branch, which then has to be merged back into master. Try to avoid that situation.

Maintaining the release branches for older minor releases happens on a best effort basis.

Cut a release of kubernetes-mixins

kube-prometheus and kubernetes-mixins releases are tied, so before cutting the release of kube-prometheus we should make sure that the same release of kubernetes-mixins exists.

Update components version

Every release of kube-prometheus should include the latest versions of each component. Updating them is automated via a CI job that can be triggered manually from this workflow.

Once the workflow is completed, the prometheus-operator bot will create some PRs. You should merge the one prefixed by [bot][main] if created before proceeding. If the bot didn't create the PR, it is either because the workflow failed or because the main branch was already up-to-date.

Update Kubernetes supported versions

The main branch of kube-prometheus should support the last 2 versions of Kubernetes. We need to make sure that the CI on the main branch is testing the kube-prometheus configuration against both of these versions by updating the CI worklow to include the latest kind version and the 2 latest images versions that are attached to the kind release. Once that is done, the compatibility matrix in the README should also be updated to reflect the CI changes.

Create pull request to cut the release

Pin Jsonnet dependencies

Pin jsonnet dependencies in jsonnetfile.json. Each dependency should be pinned to the latest release branch or if it doesn't have one, pinned to the latest commit.

Start with a fresh environment

make clean

Update Jsonnet dependencies

make update

Generate manifests

make generate

Update the compatibility matrix

Update the compatibility matrix in the README, by adding the new release based on the main branch compatibility and removing the oldest release branch to only keep the latest 5 branches in the matrix.

Update changelog

Iterate over the PRs that were merged between the latest release of kube-prometheus and the HEAD and add the changelog entries to the CHANGELOG.

Create release branch

Once the PR cutting the release is merged, pull the changes, create a new release branch named release-x.y based on the latest changes and push it to the upstream repository.

Create follow-up pull request

Unpin Jsonnet dependencies

Revert previous changes made when pinning the jsonnet dependencies since we want the main branch to be in sync with the latest changes of its dependencies.

Update CI workflow

Update the versions workflow to include the latest release branch and remove the oldest one to reflect the list of supported releases.

Update Kubernetes versions used by kubeconform

Update the versions of Kubernetes used when validating manifests with kubeconform in the Makefile to align with the compatibility matrix.