From 718a401e47014f8199373ecf274cba190a0f02a8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Peter=20=C5=A0tibran=C3=BD?= Date: Wed, 22 Jun 2022 18:18:34 +0200 Subject: [PATCH 1/9] Add more releases, split long lines for easier editing. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Peter Štibraný --- RELEASE.md | 60 ++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 42 insertions(+), 18 deletions(-) diff --git a/RELEASE.md b/RELEASE.md index a1667cb1d1a..149b3f347a7 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -7,20 +7,32 @@ This document describes the Mimir release process as well as release shepherd re A new Grafana Mimir release is cut approximately every 6 weeks. The following table contains past releases and tentative dates for upcoming releases: | Version | Date | Release shepherd | -| ------- | ---------- | ----------------- | +|---------|------------|-------------------| | 2.0.0 | 2022-03-20 | Marco Pracucci | | 2.1.0 | 2022-05-16 | Johanna Ratliff | -| 2.2.0 | 2022-06-27 | _To be announced_ | +| 2.2.0 | 2022-06-27 | Oleg Zaytsev | | 2.3.0 | 2022-08-08 | _To be announced_ | +| 2.4.0 | 2022-09-19 | _To be announced_ | +| 2.5.0 | 2022-10-31 | _To be announced_ | ## Release shepherd responsibilities -The release shepherd is responsible for an entire minor release series, meaning all pre- and patch releases of a minor release. The process formally starts with the initial pre-release, but some preparations should be made a few days in advance. - -- We aim to keep the main branch in a working state at all times. In principle, it should be possible to cut a release from main at any time. In practice, things might not work out as nicely. A few days before the pre-release is scheduled, the shepherd should check the state of main. Following their best judgement, the shepherd should try to expedite bug fixes that are still in progress but should make it into the release. On the other hand, the shepherd may hold back merging last-minute invasive and risky changes that are better suited for the next minor release. -- There may be some actions left to address when cutting this release. The release shepherd is responsible for going through TODOs in the repository and verifying that nothing is that is due this release is forgotten. -- On the planned release date, the release shepherd cuts the first pre-release (using the suffix `-rc.0`) and creates a new branch called `release-.` starting at the commit tagged for the pre-release. In general, a pre-release is considered a release candidate (that's what `rc` stands for) and should therefore not contain any known bugs that are planned to be fixed in the final release. -- With the pre-release, the release shepherd is responsible for coordinating or running the release candidate in any end user production environment for at least 1 week. This is typically done at Grafana Labs. +The release shepherd is responsible for an entire minor release series, meaning all pre- and patch releases of a minor release. +The process formally starts with the initial pre-release, but some preparations should be made a few days in advance. + +- We aim to keep the `main` branch in a working state at all times. In principle, it should be possible to cut a release + from `main` at any time. In practice, things might not work out as nicely. A few days before the pre-release is scheduled, + the shepherd should check the state of `main` branch. Following their best judgement, the shepherd should try to expedite + bug fixes that are still in progress but should make it into the release. On the other hand, the shepherd may hold back + merging last-minute invasive and risky changes that are better suited for the next minor release. +- There may be some actions left to address when cutting this release. The release shepherd is responsible for going through + TODOs in the repository and verifying that nothing is that is due this release is forgotten. +- On the planned release date, the release shepherd cuts the first pre-release (using the suffix `-rc.0`) and creates + a new branch called `release-.` starting at the commit tagged for the pre-release. In general, a pre-release + is considered a release candidate (that's what `rc` stands for) and should therefore not contain any known bugs that + are planned to be fixed in the final release. +- With the pre-release, the release shepherd is responsible for coordinating or running the release candidate in any end + user production environment for at least 1 week. This is typically done at Grafana Labs. - If regressions or critical bugs are detected, they need to get fixed before cutting a new pre-release (called `-rc.1`, `-rc.2`, etc.). See the next section for details on cutting an individual release. @@ -33,7 +45,10 @@ We use [Semantic Versioning](https://semver.org/). We maintain a separate branch for each minor release, named `release-.`, e.g. `release-1.1`, `release-2.0`. -The usual flow is to merge new features and changes into the main branch and to merge bug fixes into the latest release branch. Bug fixes are then merged into main from the latest release branch. The main branch should always contain all commits from the latest release branch. As long as main hasn't deviated significantly from the release branch, new commits can also go to main, followed by cherry picking them back into the release branch. +The usual flow is to merge new features and changes into the `main` branch and to merge bug fixes into the latest release branch. +Bug fixes are then merged into `main` from the latest release branch. +The `main` branch should always contain all commits from the latest release branch. +As long as `main` hasn't deviated significantly from the release branch, new commits can also go to `main`, followed by cherry picking them back into the release branch. Maintaining the release branches for older minor releases happens on a best effort basis. @@ -49,13 +64,16 @@ This helps ongoing PRs to get their changes in the right place, and to consider ### Prepare your release -For a new major or minor release, create the corresponding release branch based on the main branch. For a patch release, work in the branch of the minor release you want to patch. +For a new major or minor release, create the corresponding release branch based on the main branch. +For a patch release, work in the branch of the minor release you want to patch. -To prepare a release branch, first create new release branch (release-X.Y) in the Mimir repository from the main commit of your choice, and then do the following steps on a temporary branch (prepare-release-X.Y) and make a PR to merge said branch into the new release branch (prepare-release-X.Y -> release-X.Y): +To prepare a release branch, first create new release branch (release-X.Y) in the Mimir repository from the main commit of your choice, +and then do the following steps on a temporary branch (prepare-release-X.Y) and make a PR to merge said branch into +the new release branch (prepare-release-X.Y -> release-X.Y): 1. Make sure you've a GPG key associated with your GitHub account (`git tag` will be signed with that GPG key) - You can add a GPG key to your GitHub account following [this procedure](https://help.github.com/articles/generating-a-gpg-key/) -1. Update the version number in the `VERSION` file to say "X.Y-rc.0" +1. Update the version number in the `VERSION` file to say `X.Y-rc.0` 1. Update `CHANGELOG.md` - Ensure changelog entries for the new release are in this order: - `[CHANGE]` @@ -64,7 +82,7 @@ To prepare a release branch, first create new release branch (release-X.Y) in th - `[BUGFIX]` - Run `./tools/release/check-changelog.sh LAST-RELEASE-TAG...main` and add any missing PR which includes user-facing changes -Once your release preparation PR is approved, merge it to the "release-X.Y" branch, and continue with publishing. +Once your release preparation PR is approved, merge it to the `release-X.Y` branch, and continue with publishing. ### Publish a release candidate @@ -80,10 +98,12 @@ To publish a release candidate: ### Publish a stable release -> **Note:** Technical documentation is automatically published on release tags or release branches with a corresponding release tag. The workflow that publishes documentation is defined in [`publish-technical-documentation-release.yml`](.github/workflows/publish-technical-documentation-release.yml). -> To publish a stable release: +> **Note:** Technical documentation is automatically published on release tags or release branches with a corresponding +> release tag. The workflow that publishes documentation is defined in [`publish-technical-documentation-release.yml`](.github/workflows/publish-technical-documentation-release.yml). -1. Do not change the release branch directly; make a PR to the release-X.Y branch with VERSION and any CHANGELOG changes. +To publish a stable release: + +1. Do not change the release branch directly; make a PR to the `release-X.Y` branch with VERSION and any CHANGELOG changes. 1. Ensure the `VERSION` file has **no** `-rc.X` suffix 1. Update the Mimir version in the following locations: - `operations/mimir/images.libsonnet` (`_images.mimir` and `_images.query_tee` fields) @@ -101,7 +121,7 @@ To publish a release candidate: - Create `merge-release-X.Y-to-main` branch **from the `release-X.Y` branch** locally - Merge the upstream `main` branch into your `merge-release-X.Y-to-main` branch and resolve conflicts - Make a PR for merging your `merge-release-X.Y-to-main` branch into `main` - - Once approved, merge the PR with a "Merge" commit through one of the following strategies: + - Once approved, merge the PR with a **Merge** commit through one of the following strategies: - Temporarily enable "Allow merge commits" option in "Settings > Options" - Locally merge the `merge-release-X.Y-to-main` branch into `main`, and push the changes to `main` back to GitHub. This doesn't break `main` branch protection, since the PR has been approved already, and it also doesn't require removing the protection. 1. Open a PR to add the new version to the backward compatibility integration test (`integration/backward_compatibility_test.go`) @@ -115,7 +135,11 @@ To publish a release candidate: ### How to tag a release -Every release is tagged with `mimir-..`, e.g. `mimir-2.0.0`. Note the `mimir-` prefix, which we use to specifically avoid the Go compiler recognizing them as version tags. We don't want compatibility with Go's module versioning scheme, since it would require us to keep each major version's code in its own directory beneath the repository root, f.ex. v2/. We also don't provide any API backwards compatibility guarantees within a single major version. +Every release is tagged with `mimir-..`, e.g. `mimir-2.0.0`. +Note the `mimir-` prefix, which we use to specifically avoid the Go compiler recognizing them as version tags. +We don't want compatibility with Go's module versioning scheme, since it would require us to keep each major version's +code in its own directory beneath the repository root, f.ex. v2/. +We also don't provide any API backwards compatibility guarantees within a single major version. You can do the tagging on the commandline: From 1cc70a2e98b9facb2fba0434026f2ed153a0e813 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Peter=20=C5=A0tibran=C3=BD?= Date: Wed, 22 Jun 2022 18:57:23 +0200 Subject: [PATCH 2/9] Added section on creating release on GitHub with contributor stats and new contributors section. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Peter Štibraný --- RELEASE.md | 22 ++++++++++++++++------ 1 file changed, 16 insertions(+), 6 deletions(-) diff --git a/RELEASE.md b/RELEASE.md index 149b3f347a7..d3889aadd07 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -92,9 +92,21 @@ To publish a release candidate: 1. Ensure the `VERSION` file has the `-rc.X` suffix (`X` starting from `0`) 1. After merging your PR to the release branch, `git tag` the new release (see [How to tag a release](#how-to-tag-a-release)) from the release branch. 1. Wait until the CI pipeline succeeds (once a tag is created, the release process through GitHub Actions will be triggered for this tag) -1. Create a pre-release on GitHub - - Write the release notes (including a copy-paste of the changelog) - - Build binaries with `make BUILD_IN_CONTAINER=true dist` and attach them to the release (building in container ensures standardized toolchain) +1. Create a pre-release on GitHub. See [Creating release on GitHub](#creating-release-on-github) + +### Creating release on GitHub + +1. When creating release on GitHub, select your new tag, use `Mimir ` as Release Title, and click "Generate release notes" button. + This will pre-fill the changelog for the release. You can delete all of it, except "New Contributors" section. +1. Release notes should contain: + - "This release contains XX contributions from YY authors. Thank you!" at the beginning. + - You can find the numbers by doing compare like `https://github.com/grafana/mimir/compare/mimir-2.0.0...mimir-2.1.0` from previous Mimir release. (Note the syntax: `.../compare/...`, yes there are three periods). + - Number of commits = "contributions", number of contributors = "authors". + - As an example, for [current HEAD on commit 017a738](https://github.com/grafana/mimir/compare/mimir-2.1.0...017a738e94) shows 185 contributions and 36 authors since Mimir 2.1.0.) + - Most interesting new features for users. Use your judgement. + - Full copy-paste of the CHANGELOG since previous release. + - "New Contributors" section at the end (created by "Generate release notes" button in GitHub UI). +1. Build binaries with `make BUILD_IN_CONTAINER=true dist` and attach them to the release (building in container ensures standardized toolchain) ### Publish a stable release @@ -114,9 +126,7 @@ To publish a stable release: 1. Open a PR 1. After merging your PR to the release branch, `git tag` the new release (see [How to tag a release](#how-to-tag-a-release)) from the release branch. 1. Wait until the CI pipeline succeeds (once a tag is created, the release process through GitHub Actions will be triggered for this tag) -1. Create a release on GitHub - - Write the release notes (including a copy-paste of the changelog) - - Build binaries with `make BUILD_IN_CONTAINER=true dist` and attach them to the release (building in container ensures standardized toolchain) +1. Create a release on GitHub. This is basically a copy of release notes from pre-release version, with up-to-date CHANGELOG (if there were any changes in release candidates). 1. Merge the release branch `release-x.y` into `main` - Create `merge-release-X.Y-to-main` branch **from the `release-X.Y` branch** locally - Merge the upstream `main` branch into your `merge-release-X.Y-to-main` branch and resolve conflicts From a7df36bbd95f4b4039056e8decc85455bf3ab57c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Peter=20=C5=A0tibran=C3=BD?= Date: Thu, 23 Jun 2022 11:29:36 +0200 Subject: [PATCH 3/9] Added part about cherry-picking with -x and squash & merge. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Peter Štibraný --- RELEASE.md | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) diff --git a/RELEASE.md b/RELEASE.md index d3889aadd07..2c17531cd4e 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -48,13 +48,13 @@ We maintain a separate branch for each minor release, named `release-. # Cherry pick the change using -x option to add original commit ID to the message +$ git push origin cherry-pick-pr-ZZZ # Push branch to Github, create PR (set release-X.Y as base branch!) and ask for review +``` + +After PR with cherry-picked commit is reviewed, do a standard "Squash & Merge" commit that we use in Mimir. +Keep the commit message suggested by Github, which is a combination of original commit message, new PR number and cherry-picked commit hash. +Github will properly attribute you and also original commit author as contributors to this change, and will also link to original commit in the UI. From 64845fc8e1564ed80a89d84f66c50e147ec8dc4a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Peter=20=C5=A0tibran=C3=BD?= Date: Thu, 23 Jun 2022 12:45:38 +0200 Subject: [PATCH 4/9] Move opening PR to text. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Peter Štibraný --- RELEASE.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/RELEASE.md b/RELEASE.md index 2c17531cd4e..7de7ed0fe01 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -167,9 +167,11 @@ To cherry-pick a change (commit) from `main` into release branch, please do the $ git checkout release-X.Y # Start with the release branch $ git checkout -b cherry-pick-pr-ZZZ # Create new branch for cherry-picking $ git cherry-pick -x # Cherry pick the change using -x option to add original commit ID to the message -$ git push origin cherry-pick-pr-ZZZ # Push branch to Github, create PR (set release-X.Y as base branch!) and ask for review +$ git push origin cherry-pick-pr-ZZZ # Push branch to Github. ``` +After pushing branch to PR, you can create the branch by opening `https://github.com/grafana/mimir/pull/new/cherry-pick-pr-ZZZ`. +Make sure to set `release-X.Y` as the base branch, into which PR should be merged. After PR with cherry-picked commit is reviewed, do a standard "Squash & Merge" commit that we use in Mimir. Keep the commit message suggested by Github, which is a combination of original commit message, new PR number and cherry-picked commit hash. Github will properly attribute you and also original commit author as contributors to this change, and will also link to original commit in the UI. From 9f81673bb484e7b7fcb6fe9e492ac6e4ec02e68a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Peter=20=C5=A0tibran=C3=BD?= Date: Thu, 23 Jun 2022 12:47:32 +0200 Subject: [PATCH 5/9] What's more in life than happy linter? MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Peter Štibraný --- RELEASE.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/RELEASE.md b/RELEASE.md index 7de7ed0fe01..b19695c752f 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -7,7 +7,7 @@ This document describes the Mimir release process as well as release shepherd re A new Grafana Mimir release is cut approximately every 6 weeks. The following table contains past releases and tentative dates for upcoming releases: | Version | Date | Release shepherd | -|---------|------------|-------------------| +| ------- | ---------- | ----------------- | | 2.0.0 | 2022-03-20 | Marco Pracucci | | 2.1.0 | 2022-05-16 | Johanna Ratliff | | 2.2.0 | 2022-06-27 | Oleg Zaytsev | @@ -27,7 +27,7 @@ The process formally starts with the initial pre-release, but some preparations merging last-minute invasive and risky changes that are better suited for the next minor release. - There may be some actions left to address when cutting this release. The release shepherd is responsible for going through TODOs in the repository and verifying that nothing is that is due this release is forgotten. -- On the planned release date, the release shepherd cuts the first pre-release (using the suffix `-rc.0`) and creates +- On the planned release date, the release shepherd cuts the first pre-release (using the suffix `-rc.0`) and creates a new branch called `release-.` starting at the commit tagged for the pre-release. In general, a pre-release is considered a release candidate (that's what `rc` stands for) and should therefore not contain any known bugs that are planned to be fixed in the final release. @@ -99,13 +99,13 @@ To publish a release candidate: 1. When creating release on GitHub, select your new tag, use `Mimir ` as Release Title, and click "Generate release notes" button. This will pre-fill the changelog for the release. You can delete all of it, except "New Contributors" section. 1. Release notes should contain: - - "This release contains XX contributions from YY authors. Thank you!" at the beginning. - - You can find the numbers by doing compare like `https://github.com/grafana/mimir/compare/mimir-2.0.0...mimir-2.1.0` from previous Mimir release. (Note the syntax: `.../compare/...`, yes there are three periods). - - Number of commits = "contributions", number of contributors = "authors". - - As an example, for [current HEAD on commit 017a738](https://github.com/grafana/mimir/compare/mimir-2.1.0...017a738e94) shows 185 contributions and 36 authors since Mimir 2.1.0.) - - Most interesting new features for users. Use your judgement. - - Full copy-paste of the CHANGELOG since previous release. - - "New Contributors" section at the end (created by "Generate release notes" button in GitHub UI). + - "This release contains XX contributions from YY authors. Thank you!" at the beginning. + - You can find the numbers by doing compare like `https://github.com/grafana/mimir/compare/mimir-2.0.0...mimir-2.1.0` from previous Mimir release. (Note the syntax: `.../compare/...`, yes there are three periods). + - Number of commits = "contributions", number of contributors = "authors". + - As an example, for [current HEAD on commit 017a738](https://github.com/grafana/mimir/compare/mimir-2.1.0...017a738e94) shows 185 contributions and 36 authors since Mimir 2.1.0.) + - Most interesting new features for users. Use your judgement. + - Full copy-paste of the CHANGELOG since previous release. + - "New Contributors" section at the end (created by "Generate release notes" button in GitHub UI). 1. Build binaries with `make BUILD_IN_CONTAINER=true dist` and attach them to the release (building in container ensures standardized toolchain) ### Publish a stable release From 2e4fdb23f89e4eca2cb22508c7204253a89ab656 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Peter=20=C5=A0tibran=C3=BD?= Date: Fri, 24 Jun 2022 09:09:41 +0200 Subject: [PATCH 6/9] Apply feedback from review. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Peter Štibraný --- RELEASE.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/RELEASE.md b/RELEASE.md index b19695c752f..151d1820ef0 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -89,10 +89,10 @@ Once your release preparation PR is approved, merge it to the `release-X.Y` bran To publish a release candidate: 1. Do not change the release branch directly; make a PR to the release-X.Y branch with VERSION and any CHANGELOG changes. - 1. Ensure the `VERSION` file has the `-rc.X` suffix (`X` starting from `0`) + 1. Ensure the `VERSION` file has the `-rc.X` suffix (`X` starting from `0`). 1. After merging your PR to the release branch, `git tag` the new release (see [How to tag a release](#how-to-tag-a-release)) from the release branch. -1. Wait until the CI pipeline succeeds (once a tag is created, the release process through GitHub Actions will be triggered for this tag) -1. Create a pre-release on GitHub. See [Creating release on GitHub](#creating-release-on-github) +1. Wait until the CI pipeline succeeds (once a tag is created, the release process through GitHub Actions will be triggered for this tag). +1. Create a pre-release on GitHub. See [Creating release on GitHub](#creating-release-on-github). ### Creating release on GitHub @@ -100,13 +100,13 @@ To publish a release candidate: This will pre-fill the changelog for the release. You can delete all of it, except "New Contributors" section. 1. Release notes should contain: - "This release contains XX contributions from YY authors. Thank you!" at the beginning. - - You can find the numbers by doing compare like `https://github.com/grafana/mimir/compare/mimir-2.0.0...mimir-2.1.0` from previous Mimir release. (Note the syntax: `.../compare/...`, yes there are three periods). + - You can find the numbers by doing compare like `https://github.com/grafana/mimir/compare/mimir-2.0.0...mimir-2.1.0` from previous Mimir release. (Note the syntax: `.../compare/...`, yes there are three dots). - Number of commits = "contributions", number of contributors = "authors". - - As an example, for [current HEAD on commit 017a738](https://github.com/grafana/mimir/compare/mimir-2.1.0...017a738e94) shows 185 contributions and 36 authors since Mimir 2.1.0.) + - As an example, for [current HEAD on commit 017a738](https://github.com/grafana/mimir/compare/mimir-2.1.0...017a738e94) shows 185 contributions and 36 authors since Mimir 2.1.0. - Most interesting new features for users. Use your judgement. - Full copy-paste of the CHANGELOG since previous release. - "New Contributors" section at the end (created by "Generate release notes" button in GitHub UI). -1. Build binaries with `make BUILD_IN_CONTAINER=true dist` and attach them to the release (building in container ensures standardized toolchain) +1. Build binaries with `make BUILD_IN_CONTAINER=true dist` and attach them to the release (building in container ensures standardized toolchain). ### Publish a stable release @@ -170,8 +170,8 @@ $ git cherry-pick -x # Cherry pick the change using -x o $ git push origin cherry-pick-pr-ZZZ # Push branch to Github. ``` -After pushing branch to PR, you can create the branch by opening `https://github.com/grafana/mimir/pull/new/cherry-pick-pr-ZZZ`. +After pushing branch to PR, you can create the PR by opening `https://github.com/grafana/mimir/pull/new/cherry-pick-pr-ZZZ` link. Make sure to set `release-X.Y` as the base branch, into which PR should be merged. After PR with cherry-picked commit is reviewed, do a standard "Squash & Merge" commit that we use in Mimir. -Keep the commit message suggested by Github, which is a combination of original commit message, new PR number and cherry-picked commit hash. +Keep the commit message suggested by Github, which is a combination of original commit message, original PR number, new PR number and cherry-picked commit hash. Github will properly attribute you and also original commit author as contributors to this change, and will also link to original commit in the UI. From 02fe99a53f072461b7ffd120094d29d059e23c73 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Peter=20=C5=A0tibran=C3=BD?= Date: Fri, 24 Jun 2022 10:18:33 +0200 Subject: [PATCH 7/9] Fix. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Peter Štibraný --- RELEASE.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/RELEASE.md b/RELEASE.md index 151d1820ef0..96c8f256ec6 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -167,11 +167,11 @@ To cherry-pick a change (commit) from `main` into release branch, please do the $ git checkout release-X.Y # Start with the release branch $ git checkout -b cherry-pick-pr-ZZZ # Create new branch for cherry-picking $ git cherry-pick -x # Cherry pick the change using -x option to add original commit ID to the message -$ git push origin cherry-pick-pr-ZZZ # Push branch to Github. +$ git push origin cherry-pick-pr-ZZZ # Push branch to GitHub. ``` -After pushing branch to PR, you can create the PR by opening `https://github.com/grafana/mimir/pull/new/cherry-pick-pr-ZZZ` link. +After pushing branch to GitHub, you can create the PR by opening `https://github.com/grafana/mimir/pull/new/cherry-pick-pr-ZZZ` link. Make sure to set `release-X.Y` as the base branch, into which PR should be merged. After PR with cherry-picked commit is reviewed, do a standard "Squash & Merge" commit that we use in Mimir. -Keep the commit message suggested by Github, which is a combination of original commit message, original PR number, new PR number and cherry-picked commit hash. -Github will properly attribute you and also original commit author as contributors to this change, and will also link to original commit in the UI. +Keep the commit message suggested by GitHub, which is a combination of original commit message, original PR number, new PR number and cherry-picked commit hash. +GitHub will properly attribute you and also original commit author as contributors to this change, and will also link to original commit in the UI. From 188b05bdd9c82423c2b131cfe4790e93daf1745b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Peter=20=C5=A0tibran=C3=BD?= Date: Fri, 24 Jun 2022 10:49:25 +0200 Subject: [PATCH 8/9] Address review feedback. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Peter Štibraný --- RELEASE.md | 60 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 37 insertions(+), 23 deletions(-) diff --git a/RELEASE.md b/RELEASE.md index 96c8f256ec6..7c684d3d1e5 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -20,19 +20,18 @@ A new Grafana Mimir release is cut approximately every 6 weeks. The following ta The release shepherd is responsible for an entire minor release series, meaning all pre- and patch releases of a minor release. The process formally starts with the initial pre-release, but some preparations should be made a few days in advance. -- We aim to keep the `main` branch in a working state at all times. In principle, it should be possible to cut a release - from `main` at any time. In practice, things might not work out as nicely. A few days before the pre-release is scheduled, - the shepherd should check the state of `main` branch. Following their best judgement, the shepherd should try to expedite - bug fixes that are still in progress but should make it into the release. On the other hand, the shepherd may hold back - merging last-minute invasive and risky changes that are better suited for the next minor release. -- There may be some actions left to address when cutting this release. The release shepherd is responsible for going through - TODOs in the repository and verifying that nothing is that is due this release is forgotten. -- On the planned release date, the release shepherd cuts the first pre-release (using the suffix `-rc.0`) and creates - a new branch called `release-.` starting at the commit tagged for the pre-release. In general, a pre-release - is considered a release candidate (that's what `rc` stands for) and should therefore not contain any known bugs that - are planned to be fixed in the final release. -- With the pre-release, the release shepherd is responsible for coordinating or running the release candidate in any end - user production environment for at least 1 week. This is typically done at Grafana Labs. +- We aim to keep the `main` branch in a working state at all times. + In principle, it should be possible to cut a release from `main` at any time. + In practice, things might not work out as nicely. + A few days before the pre-release is scheduled, the shepherd should check the state of `main` branch. + Following their best judgement, the shepherd should try to expedite bug fixes that are still in progress but should make it into the release. + On the other hand, the shepherd may hold back merging last-minute invasive and risky changes that are better suited for the next minor release. +- There may be some actions left to address when cutting this release. + The release shepherd is responsible for going through TODOs in the repository and verifying that nothing is that is due this release is forgotten. +- On the planned release date, the release shepherd cuts the first pre-release (using the suffix `-rc.0`) and creates a new branch called `release-.` starting at the commit tagged for the pre-release. + In general, a pre-release is considered a release candidate (that's what `rc` stands for) and should therefore not contain any known bugs that are planned to be fixed in the final release. +- With the pre-release, the release shepherd is responsible for coordinating or running the release candidate in any end user production environment for at least 1 week. + This is typically done at Grafana Labs. - If regressions or critical bugs are detected, they need to get fixed before cutting a new pre-release (called `-rc.1`, `-rc.2`, etc.). See the next section for details on cutting an individual release. @@ -80,10 +79,23 @@ the new release branch (prepare-release-X.Y -> release-X.Y): - `[FEATURE]` - `[ENHANCEMENT]` - `[BUGFIX]` - - Run `./tools/release/check-changelog.sh LAST-RELEASE-TAG...main` and add any missing PR which includes user-facing changes + - Run `./tools/release/check-changelog.sh LAST-RELEASE-TAG...main` and add any missing PR which includes user-facing changes. + - `check-changelog.sh` script also reports number of PRs and authors on the top. Note the numbers and include them in the release notes in GitHub. Once your release preparation PR is approved, merge it to the `release-X.Y` branch, and continue with publishing. +### Write release notes document + +Each Grafana Mimir release comes with a release notes that is published on the website. This document is stored in `docs/sources/release-notes/`, +and contains following sections: +- Features and enhancements +- Upgrade considerations +- Bug fixes + +Please write a draft release notes PR, and get it approved by Grafana Mimir's Product Manager (or ask PM to send PR with the document). +Make sure that release notes document for new version is available from the release branch, and not just `main`. +See [PR 1848](https://github.com/grafana/mimir/pull/1848) for an example PR. + ### Publish a release candidate To publish a release candidate: @@ -96,16 +108,18 @@ To publish a release candidate: ### Creating release on GitHub -1. When creating release on GitHub, select your new tag, use `Mimir ` as Release Title, and click "Generate release notes" button. - This will pre-fill the changelog for the release. You can delete all of it, except "New Contributors" section. -1. Release notes should contain: +1. Go to https://github.com/grafana/mimir/releases/new to start a new release on GitHub (or click "Draft a new release" at https://github.com/grafana/mimir/releases page.) +1. Select your new tag, use `Mimir ` as Release Title. Check that "Previous tag" next to "Generate release notes" button shows previous Mimir release. + Click "Generate release notes" button. This will pre-fill the changelog for the release. + You can delete all of it, but keep "New Contributors" section and "Full Changelog" link for later. +1. Release description consists of: - "This release contains XX contributions from YY authors. Thank you!" at the beginning. - - You can find the numbers by doing compare like `https://github.com/grafana/mimir/compare/mimir-2.0.0...mimir-2.1.0` from previous Mimir release. (Note the syntax: `.../compare/...`, yes there are three dots). - - Number of commits = "contributions", number of contributors = "authors". - - As an example, for [current HEAD on commit 017a738](https://github.com/grafana/mimir/compare/mimir-2.1.0...017a738e94) shows 185 contributions and 36 authors since Mimir 2.1.0. - - Most interesting new features for users. Use your judgement. - - Full copy-paste of the CHANGELOG since previous release. - - "New Contributors" section at the end (created by "Generate release notes" button in GitHub UI). + You can find the numbers by running `./tools/release/check-changelog.sh LAST-RELEASE-TAG...NEW-RELEASE-TAG`. + As an example, running the script with `mimir-2.0.0...mimir-2.1.0` argument reports `Found 417 PRs from 47 authors.`. + - After contributor stats, please include content of the release notes document [created previously](#write-release-notes-document). + - After release notes, please copy-paste content of CHANGELOG.md file since the previous release. + - After CHANGELOG, please include "New Contributors" section and "Full Changelog" link at the end. + Both were created previously by "Generate release notes" button in GitHub UI. 1. Build binaries with `make BUILD_IN_CONTAINER=true dist` and attach them to the release (building in container ensures standardized toolchain). ### Publish a stable release From f8794e9028989602779ae0bc25f25901f5f8b64b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Peter=20=C5=A0tibran=C3=BD?= Date: Fri, 24 Jun 2022 10:50:33 +0200 Subject: [PATCH 9/9] Address review feedback. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Peter Štibraný --- RELEASE.md | 1 + 1 file changed, 1 insertion(+) diff --git a/RELEASE.md b/RELEASE.md index 7c684d3d1e5..6e751afdb14 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -88,6 +88,7 @@ Once your release preparation PR is approved, merge it to the `release-X.Y` bran Each Grafana Mimir release comes with a release notes that is published on the website. This document is stored in `docs/sources/release-notes/`, and contains following sections: + - Features and enhancements - Upgrade considerations - Bug fixes