Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Helm: review and update of release process by tech writer #4500

Merged
merged 4 commits into from
Mar 29, 2023
Merged

Helm: review and update of release process by tech writer #4500

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
b43df45
Incorporate feedback from Ursula and Krajo.
osg-grafana Mar 29, 2023
28d6491
Note the step that triggers the release process.
osg-grafana Mar 29, 2023
1a16a11
Run make doc.
osg-grafana Mar 29, 2023
84d0f61
Fix bare URLs.
osg-grafana Mar 29, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
108 changes: 74 additions & 34 deletions operations/helm/charts/mimir-distributed/RELEASE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,55 +1,95 @@
# Releases

## Pre-requisites
The release processes that follow apply to the Grafana Mimir Helm chart.

Either:
## Before you begin

- Both Mimir and Enterprise Metrics (GEM) have container images released to Docker Hub that line up (same weekly, same RC, same release version).
- Mimir and GEM images do not match, but there are no breaking changes between the two. That is all shared configuration parameters behave the same way. For example GEM has a bugfix in a maintenance version.
One of the following scenarios must apply:

## Release process
- Both Grafana Mimir and Grafana Enterprise Metrics (GEM) have container images, whose image versions match. The image versions have the same weekly, RC, and final versions. These versions are released to Docker Hub.
- The Mimir and GEM image versions do not match, but there are no breaking changes between them because all of the shared configuration parameters behave the same way. For example, because GEM contains a bugfix, the version of GEM is `2.5.1` and the version of Mimir is `2.5.0`.

1. Determine version number.
## Release process for a weekly release

Helm [mandates semantic versioning](https://helm.sh/docs/topics/charts/#the-chartyaml-file).
Each weekly release is created automatically, but you need to approve and merge it manually. For an example, see [PR 4600](https://github.com/grafana/mimir/pull/4600).

- Weekly releases should have the version: `x.y.z-weekly.w` (e.g. `3.1.0-weekly.196`). These are created automatically, but need to be approved and merged manually ([sample PR](https://github.com/grafana/mimir/pull/4309)).
- Release candidate: `x.y.z-rc.w` (e.g. `3.1.0.rc.1`)
- Final version: `x.y.z` (e.g. `3.1.0`)
[The Chart.yaml file](https://helm.sh/docs/topics/charts/#the-chartyaml-file) requires semantic versioning.

**Note**: the weekly and RC number must be separated with dot (.) for correct version ordering.
Weekly releases have the version `x.y.z-weekly.w`, for example `3.1.0-weekly.196`, where `196` represents an incrementing week number.

1. For stable versions, create and merge a PR targeting `main` updating the [Helm changelog](https://github.com/grafana/mimir/blob/main/operations/helm/charts/mimir-distributed/CHANGELOG.md) and moving `## main / unreleased` items under the section for this release.
> **Note**: You must precede the week number (such as `196`) with a dot (`.`).

- If there are any deprecated features that should be removed in this release, then verify that they have been removed, and move their deprecation notices into the section for this release.
## Release process for a release candidate or final release

1. For stable versions, create and push or reuse a branch based on `main` named `mimir-distributed-release-x.y` (eg. `mimir-distributed-release-4.2` for all `4.2.x` releases).
The following steps apply to a release candidate or a final release.

- This branch will be used as the target branch for the PR you'll create in the next step.
- The new branch should start from the commit created by the previous step, so that the changelog is in the right state.
1. Determine the Helm chart version number.

1. Update Helm chart and documentation:
[The Chart.yaml file](https://helm.sh/docs/topics/charts/#the-chartyaml-file) requires semantic versioning:

1. Set the image versions in [values.yaml](https://github.com/grafana/mimir/blob/main/operations/helm/charts/mimir-distributed/values.yaml) as needed:
- `image.tag` (Mimir)
- `enterprise.image.tag` (GEM) - note that unlike the other image tags, GEM image tags start with `v`, eg. `v2.6.0`, not `2.6.0`
- `smoke_test.image.tag` (Smoke test, usually same as Mimir)
- `continuous_test.image.tag` (Continuous test, usually same as Mimir)
1. Set the `version` to the desired chart version number in the Helm [Chart.yaml](https://github.com/grafana/mimir/blob/main/operations/helm/charts/mimir-distributed/Chart.yaml), e.g. 4.2.0, determined in the very first step.
1. Set the `appVersion` to the included version of Mimir in the Helm [Chart.yaml](https://github.com/grafana/mimir/blob/main/operations/helm/charts/mimir-distributed/Chart.yaml), e.g. 2.6.0, doesn't have to include non zero patch version.
1. Update the `home` URL to point to the appropriate documentation version in the Helm [Chart.yaml](https://github.com/grafana/mimir/blob/main/operations/helm/charts/mimir-distributed/Chart.yaml). This should be the closest Mimir documentation version, not "latest" or "next" that change content.
1. For a new stable release, write release notes in [release notes](https://github.com/grafana/mimir/tree/mimir-distributed-release-4.2/docs/sources/helm-charts/mimir-distributed/release-notes). For a patch release to a stable release, update the release notes in question.
1. Run `make doc`, to update [README.md](https://github.com/grafana/mimir/blob/main/operations/helm/charts/mimir-distributed/README.md) from its template
1. Open a PR.
- Release candidates have the version `x.y.z-rc.w`, for example `3.1.0-rc.7`.
- The final version has the version `x.y.z`, for example `3.1.0`.

For stable versions, ensure your PR targets the `mimir-distributed-release-x.y` branch you created above.
> **Note**: You must precede the release candidate number (such as `7`) with a dot (`.`).

For all other versions, your PR should target `main`.
1. If you do not have a release branch, create one:

1. Merge the PR after review
a. Create a PR, whose target is `main`, that updates the [Helm chart changelog](https://github.com/grafana/mimir/blob/main/operations/helm/charts/mimir-distributed/CHANGELOG.md), and move any `## main / unreleased` items under this release’s version.

The [release process](https://github.com/grafana/mimir/blob/main/.github/workflows/helm-release.yaml) checks and creates a Git tag formatted as `mimir-distributed-<version>` (e.g. `mimir-distributed-3.1.0-weekly.196`) on the merge commit created when the PR is merged. The release process fails if the tag already exists to prevent releasing the same version with different content. The release is published in the [Grafana helm-charts](https://grafana.github.io/helm-charts/) Helm repository.
> **Note:** If there are any deprecated features that should be removed in this release, then verify that they have been removed, and move their deprecation notices into the section for this release.

When a `mimir-distributed-x.y.z` stable version tag is pushed, the documentation is [published](https://github.com/grafana/mimir/blob/main/.github/workflows/publish-technical-documentation-release-helm-charts.yml) on the website.
b. Have the PR reviewed by a maintainer.

1. For stable versions, once the release tag in Git is created, merge the branch back to `main`, follow the same procedure as for Mimir releases: [Merging release branch into main](https://github.com/grafana/mimir/blob/main/RELEASE.md#merging-release-branch-into-main).
c. Merge the PR upon approval.

d. Create and push a branch starting from the commit created by the previous PR and name it `mimir-distributed-release-x.y`.

For example, `mimir-distributed-release-4.5` for any `4.5.x` release.

1. Switch to the release branch.

For example, `mimir-distributed-release-4.5` for any `4.5.x` release.

1. Set the image versions in [values.yaml](https://github.com/grafana/mimir/blob/main/operations/helm/charts/mimir-distributed/values.yaml), as needed:

- `image.tag` (Mimir)
- `enterprise.image.tag` (GEM)

> **Note:** Unlike the Mimir image tags, GEM image tags start with `v`. For example, `v2.6.0` instead of `2.6.0`.

- `smoke_test.image.tag` (Smoke test; usually the same as Mimir)
- `continuous_test.image.tag` (Continuous test; usually the same as Mimir)

1. Set the `version` field, in the [Chart.yaml](https://github.com/grafana/mimir/blob/main/operations/helm/charts/mimir-distributed/Chart.yaml) file, to the desired version.

For example, `4.5.0`.

> **Note:** This is the step that triggers the release process GitHub Action.

1. Set the `appVersion` field, in the [Chart.yaml](https://github.com/grafana/mimir/blob/main/operations/helm/charts/mimir-distributed/Chart.yaml) file, to the version of Mimir that the Helm chart deploys.

For example, `2.6.0`.

1. Create or update the release notes in [release notes](https://github.com/grafana/mimir/tree/mimir-distributed-release-4.2/docs/sources/helm-charts/mimir-distributed/release-notes).

1. From the root directory of the repository, run `make doc` so a template can update the [README.md](https://github.com/grafana/mimir/blob/main/operations/helm/charts/mimir-distributed/README.md) file.

1. Open a PR, and make sure that your PR targets the release branch.

1. Have the PR reviewed by a maintainer.

1. Merge the PR upon approval.

1. Verify that the Helm chart is published; run the following commands:

`helm repo update && helm search repo grafana/mimir-distributed --version <VERSION>`

You might have to wait a few minutes.

1. In a browser, go to [https://grafana.com/docs/helm-charts/mimir-distributed](https://grafana.com/docs/helm-charts/mimir-distributed) and refresh the page.

1. After the release tag in Git is created, merge the branch back into `main` by following the same procedure as for Mimir releases: [Merging release branch into main](https://github.com/grafana/mimir/blob/main/RELEASE.md#merging-release-branch-into-main).

The [release process](https://github.com/grafana/mimir/blob/main/.github/workflows/helm-release.yaml) checks and creates a Git tag formatted as `mimir-distributed-<version>`, for example `mimir-distributed-4.5.0`, on the merge commit created when the PR is merged. To prevent releasing the same version with different content, the release process fails if the tag already exists. The release is published in the [Grafana helm-charts](https://grafana.github.io/helm-charts/) Helm repository.

When a `mimir-distributed-x.y.z` final version tag is pushed, the Helm chart documentation is [published](https://github.com/grafana/mimir/blob/main/.github/workflows/publish-technical-documentation-release-helm-charts.yml) to [https://grafana.com/docs/helm-charts/mimir-distributed](https://grafana.com/docs/helm-charts/mimir-distributed).