# Releases

The release processes that follow apply to the Grafana Mimir Helm chart.

## Schedule

The release schedule follows the Grafana Mimir releases. This usually happens within 2 weeks of the Mimir release. For the Mimir release schedule consult the Mimir [RELEASE.md](../../../../RELEASE.md).

Security updates of Mimir will also trigger a Helm chart release. The Helm chart can be released independently of Mimir, but this is only done if
there's some urgent update needed.

There are weekly releases with the latest Mimir build, but they are intended for testing purposes only, not production. Weekly releases are marked with a development version and helm will ignore them unless the `--devel` flag is used on the command line.

## Before you begin

Mimir must have container images released to Docker Hub with the version (weekly, RC, or final) that will be included in the Helm chart.

## Release process for a weekly release

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).

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

Weekly releases have the version `x.y.z-weekly.w`, for example `3.1.0-weekly.196`, where `196` represents an incrementing week number.

> **Note**: You must precede the week number (such as `196`) with a dot (`.`).

## Release process for a release candidate

1. Determine the Helm chart version number.

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

   - Release candidates have the version `x.y.z-rc.w`, for example `3.1.0-rc.7`.

   > **Note**: You must precede the release candidate number (such as `7`) with a dot (`.`).

1. Prepare changelog.

   - 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.

   > **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.

   - Have the PR reviewed by a maintainer.

   - Merge the PR upon approval.

1. Notify open PRs about the cut change log.

   - From the root directory of the repository run

     ```bash
     ./tools/release/notify-changelog-cut.sh operations/helm/charts/mimir-distributed/CHANGELOG.md
     ```

1. Create a release branch.

   - Create (if the branch is not created yet), switch to and push a branch starting from the commit created by the prepare changelog PR and name it `mimir-distributed-release-x.y`.

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

   - Push the branch to origin without any commit added.

     ```bash
     git fetch
     git checkout origin/main
     git checkout -b mimir-distributed-release-<version>
     git push -u origin mimir-distributed-release-<version>
     ```

   - Once the branch is pushed, all changes to `mimir-distributed-release-x.y` branch must be done through PR.

1. Create a branch from release branch if it hasn't been created yet, to update Mimir image and helm chart version.

   For example `user/update-mimir-distributed-release-x.y`.

1. Update versions and links in the `user/update-mimir-distributed-release-x.y` branch.

   - Set the `image.tag` version in [values.yaml](https://github.com/grafana/mimir/blob/main/operations/helm/charts/mimir-distributed/values.yaml):

   - 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 release candidate version.

     For example, `4.5.0-rc.0`.

     > **Note:** Once this change is merged to `mimir-distributed-x.y` branch, it will trigger the release process GitHub Action. Unless you want to release final release, make sure to append the correct rc version.

   - 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`.

   - Add a changelog entry in `mimir-distributed/CHANGELOG.md` about upgading the chart's version of Mimir.

   - Create or update the release notes in `docs/sources/helm-charts/mimir-distributed/release-notes` directory.

     The release notes should refer to the correct Mimir version and its specific documentation version.

     > **Note:** This step can be done in a separate PR and shouldn't block release candidate from getting published.

   - Update the Mimir documentation version parameter in [\_index.md](https://github.com/grafana/mimir/blob/main/docs/sources/helm-charts/mimir-distributed/_index.md)

     The parameter is `MIMIR_VERSION`. With the exception of the release notes, the Helm chart documentation should refer to the documentation of Mimir that is actually included in the Helm chart.

   - Update the Mimir version in the [deploy preview workflow](https://github.com/grafana/mimir/blob/main/.github/workflows/deploy-pr-preview.yml).

     This ensures the deploy preview mounts the Mimir documentation in PRs to the directory expected by the Helm chart documentation.

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

   - Verify that the links on the [README.md](https://github.com/grafana/mimir/blob/main/operations/helm/charts/mimir-distributed/README.md) are correct.

1. Open PR to release branch

   - Create PR that contains all the changes we have so far from `user/update-mimir-distributed-release-x.y` branch and make sure that your PR targets the release branch `mimir-distributed-release-x.y`.

   - Have the PR reviewed by a maintainer.

   - 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 --devel --version <VERSION>`

     You might have to wait a few minutes.

   - 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).

1. Backport and additional release candidate.

   - If additional changes need to be added to this release, another release candidate version has to be created.
   - Follow [backport process](https://github.com/grafana/mimir/blob/main/RELEASE.md#cherry-picking-changes-into-release-branch) similar with Mimir release to backport changes from main branch.
   - Go back to step 5. Update versions and links in the user/update-mimir-distributed-release-x.y branch to update the next release candidate.

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.

## Release process for a final release

1. Determine the Helm chart version number.

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

   - The final version has the version `x.y.z`, for example `3.1.0`.
   - Normally we will proceed the same `x.y.z` version value from the release candidate step.

1. Create a branch from release branch to update Mimir image and helm chart version.

   For example `user/update-mimir-distributed-release-x.y-final`.

1. Update versions and links in the `user/update-mimir-distributed-release-x.y-final` branch.

   - Set the `image.tag` version in [values.yaml](https://github.com/grafana/mimir/blob/main/operations/helm/charts/mimir-distributed/values.yaml):

   - Optionally finalize release note and update version in the `user/update-mimir-distributed-release-x.y-final` branch.

   - Finalize the chart's changelog. Update the title of the release section by setting it to the final release version number.

     For example, `## 4.5.0`.

   - 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 final release version.

     For example, `4.5.0`.

     > **Note:** Once this change is merged to `mimir-distributed-x.y` branch, it will trigger the release process GitHub Action.

   - There shouldn't be anymore update needed in documentation because that has been done in the release candidate step above.

     > **Note:** Check that the final version of Mimir defined in the chart matches that mentioned in the changelog and the release notes.

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

1. Open PR to release branch

   - Create PR that contains all the changes we have so far from `user/update-mimir-distributed-release-x.y-final` branch and make sure that your PR targets the release branch `mimir-distributed-release-x.y`.

   - Have the PR reviewed by a maintainer.

   - 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.

   - For stable releases (i.e. excluding release candidates): In a browser, go to the [helm chart docs versions](https://grafana.com/docs/versions/?project=/docs/helm-charts/mimir-distributed/) and verify that the new version is selectable. This might take up to 15 minutes. If this doesn't happen because the `publish-technical-documentation-release-helm-charts` action can't find the release tag, try re-running the workflow on the release branch again after waiting a few minutes.

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).
