1--- 2title: Release Process 3type: docs 4menu: thanos 5--- 6# Release Process 7 8This page describes the release cadence and process for Thanos project. 9 10We use [Semantic Versioning](http://semver.org/). 11 12NOTE: As [Semantic Versioning](http://semver.org/spec/v2.0.0.html) states all 0.y.z releases can contain breaking 13changes in API (flags, grpc API, any backward compatibility) 14 15## Cadence 16 17We aim for regular and strict one release per *6 weeks*. 6 weeks is counter from first release candidate to another. 18This means that there is no *code freeze* or anything like that. We plan to stick to the exact 6 weeks, so there is no 19rush into being within release (except bug fixes). 20 21No feature should block release. 22 23Additionally we (obviously) aim for `main` branch being stable. 24 25We are assigning a release shepherd for each minor release. 26 27Release shepherd responsibilities: 28 29* Perform releases (from first RC to actual release). 30* Announce all releases on all communication channels. 31 32| Release | Time of first RC | Shepherd (GitHub handle) | 33|-----------|--------------------------|--------------------------| 34| v0.22.0 | (planned) 2021.07.06 | TBD | 35| v0.21.0 | (planned) 2021.05.25 | TBD | 36| v0.20.0 | 2021.04.20 | `@kakkoyun` | 37| v0.19.0 | 2021.03.02 | `@bwplotka` | 38| v0.18.0 | 2021.01.06 | `@squat` | 39| v0.17.0 | 2020.11.18 | `@metalmatze` | 40| v0.16.0 | 2020.10.26 | `@bwplotka` | 41| v0.15.0 | 2020.08.12 | `@kakkoyun` | 42| v0.14.0 | 2020.07.10 | `@kakkoyun` | 43| v0.13.0 | 2020.05.13 | `@bwplotka` | 44| v0.12.0 | 2020.04.15 | `@squat` | 45| v0.11.0 | 2020.02.19 | `@metalmatze` | 46| v0.10.0 | 2020.01.08 | `@GiedriusS` | 47| v0.9.0 | 2019.11.26 | `@bwplotka` | 48| v0.8.0 | 2019.10.09 | `@bwplotka` | 49| v0.7.0 | 2019.08.28 | `@domgreen` | 50| v0.6.0 | 2019.07.12 | `@GiedriusS` | 51| v0.5.0 | 2019.06.31 | `@bwplotka` | 52 53# For maintainers: Cutting individual release 54 55Process of releasing a *minor* Thanos version: 56 571. Release `v<major>.<minor+1>.0-rc.0` 581. If after 3 work days there is no major bug, release `v<major>.<minor>.0` 591. If within 3 work days there is major bug, let's triage it to fix it and then release `v<major>.<minor>.0-rc.++` Go to 60 step 2. 611. Do patch release if needed for any bugs afterwards. Use same `release-xxx` branch and migrate fixes to main. 62 63## How to release a version 64 65Release is happening on separate `release-<major>.<minor>` branch. 66 671. Prepare PR to branch `release-<major>.<minor>` that will start minor release branch and prepare changes to cut 68 release. 69 70 Push the created branch to origin (Thanos repository) to be able to make your PR with the CHANGELOG.md changes 71 against this branch later. 72 73 ```bash 74 $ git push origin release-<major>.<minor> 75 ``` 76 77For release candidate just reuse same branch and rebase it on every candidate until the actual release happens. 78 791. Create small PR to `main` (!) to cut CHANGELOG. This helps to maintain new changelog on main. 80 81 1. Add entry to CHANGELOG indicating release in progress. This reduces risk for the new PRs to add changelog entries 82 to already released release. 83 1. Update `VERSION` file to version one minor version higher than the released one and `dev` suffix. This allows CI 84 to build thanos binary with the version indicating potential next minor release, showing that someone uses 85 non-released binary (which is fine, just better to know this!). 86 87Feel free to mimic following PR: https://github.com/thanos-io/thanos/pull/3861 88 891. Update [CHANGELOG file](/CHANGELOG.md) 90 91Note that `CHANGELOG.md` should only document changes relevant to users of Thanos, including external API changes, 92performance improvements, and new features. Do not document changes of internal interfaces, code refactorings and 93clean-ups, changes to the build process, etc. People interested in these are asked to refer to the git history. Format 94is described in `CHANGELOG.md`. 95 96The whole release from release candidate `rc.0` to actual release should have exactly the same section. We don't 97separate what have changed between release candidates. 98 991. Double check backward compatibility: 100 101 1. *In case of version after `v1+.y.z`*, double check if none of the changes break API compatibility. This should be 102 done in PR review process, but double check is good to have. 103 1. In case of `v0.y.z`, document all incompatibilities in changelog. 104 1051. Double check metric changes: 106 107 1. Note any changes in the changelog 108 1. If there were any changes then update the relevant alerting rules and/or dashboards since `thanos-mixin` is part 109 of the repository now 110 1111. Update website's [hugo.yaml](../website/hugo.yaml) to have correct links for new release ( 112 add `0.y.z: "/:sections/:filename.md"`). 113 1141. Update tutorials: 115 116 1. Update the Thanos version used in the [tutorials](../tutorials) manifests. 117 1. In case of any breaking changes or necessary updates adjust the manifests so the tutorial stays up to date. 118 1. Update the [scripts/quickstart.sh](../scripts/quickstart.sh) script if needed. 119 1201. After review, merge the PR and immediately after this tag a version: 121 122 ```bash 123 tag=$(cat VERSION) 124 git tag -s "v${tag}" -m "v${tag}" 125 git push origin "v${tag}" 126 ``` 127 128 Signing a tag with a GPG key is appreciated, but in case you can't add a GPG key to your Github account using the 129 following [procedure](https://help.github.com/articles/generating-a-gpg-key/), you can replace the `-s` flag by `-a` 130 flag of the `git tag` command to only annotate the tag without signing. 131 132 Please make sure that you are tagging the merge commit because otherwise GitHub's UI will show that there were more 133 commits after your release. 134 1351. Once a tag is created, the release process through CircleCI will be triggered for this tag. 136 1371. You must create a Github Release using the UI for this tag, as otherwise CircleCI will not be able to upload tarballs 138 for this tag. Also, you must create the Github Release using a Github user that has granted access rights to 139 CircleCI. List of maintainers is available [here](/MAINTAINERS.md) 140 1411. Go to the releases page of the project, click on the `Draft a new release` button and select the tag you just pushed. 142 Describe release and post relevant entry from changelog. Click `Save draft` rather than `Publish release` at this 143 time. (This will prevent the release being visible before it has got the binaries attached to it.) 144 1451. Once tarballs are published on release page, you can click `Publish` and release is complete. 146 1471. Announce `#thanos` slack channel. 148 1491. Pull commits from release branch to main branch for non `rc` releases. 150 1511. After releasing a major version, please cut a release for `kube-thanos` as well. 152 https://github.com/thanos-io/kube-thanos/releases 153 Make sure all the flag changes are reflected in the manifests. Otherwise, the process is the same, except we don't 154 have `rc` for the `kube-thanos`. We do this to make sure we have compatible manifests for each major versions. 155 156## Pre-releases (release candidates) 157 158The following changes to the above procedures apply: 159 160* In line with [Semantic Versioning](http://semver.org/), append something like `-rc.0` to the version (with the 161 corresponding changes to the tag name, the release name etc.). 162* Tick the `This is a pre-release` box when drafting the release in the Github UI. 163* Still update `CHANGELOG.md`, but when you cut the final release later, merge all the changes from the pre-releases 164 into the one final update. 165