github.com/thanos-io/thanos@v0.32.5/docs/release-process.md (about)

     1  # Release Process
     2  
     3  This page describes the release cadence and process for Thanos project.
     4  
     5  We use [Semantic Versioning](http://semver.org/).
     6  
     7  NOTE: As [Semantic Versioning](http://semver.org/spec/v2.0.0.html) states all 0.y.z releases can contain breaking changes in API (flags, grpc API, any backward compatibility)
     8  
     9  ## Cadence
    10  
    11  We aim for regular and strict one release per *6 weeks*. 6 weeks is counter from first release candidate to another. This means that there is no *code freeze* or anything like that. We plan to stick to the exact 6 weeks, so there is no rush into being within release (except bug fixes).
    12  
    13  No feature should block release.
    14  
    15  Additionally, we (obviously) aim for `main` branch being stable.
    16  
    17  We are assigning a release shepherd for each minor release.
    18  
    19  Release shepherd responsibilities:
    20  
    21  * Perform releases (from first RC to actual release).
    22  * Announce all releases on all communication channels.
    23  
    24  | Release | Time of first RC     | Shepherd (GitHub handle)      |
    25  |---------|----------------------|-------------------------------|
    26  | v0.32.0 | (planned) 2023.03.09 | No one ATM                    |
    27  | v0.31.0 | (planned) 2023.01.26 | No one ATM                    |
    28  | v0.30.0 | 2022.12.21           | `@bwplotka`                   |
    29  | v0.29.0 | 2022.10.21           | `@GiedriusS`                  |
    30  | v0.28.0 | 2022.08.22           | `@yeya24`                     |
    31  | v0.27.0 | 2022.06.21           | `@wiardvanrij` and `@matej-g` |
    32  | v0.26.0 | 2022.04.29           | `@wiardvanrij`                |
    33  | v0.25.0 | 2022.03.01           | `@bwplotka` and `@matej-g`    |
    34  | v0.24.0 | 2021.12.22           | `@squat`                      |
    35  | v0.23.0 | 2021.09.02           | `@bwplotka`                   |
    36  | v0.22.0 | 2021.07.06           | `@GiedriusS`                  |
    37  | v0.21.0 | 2021.05.28           | `@metalmatze` and `@onprem`   |
    38  | v0.20.0 | 2021.04.23           | `@kakkoyun`                   |
    39  | v0.19.0 | 2021.03.02           | `@bwplotka`                   |
    40  | v0.18.0 | 2021.01.06           | `@squat`                      |
    41  | v0.17.0 | 2020.11.18           | `@metalmatze`                 |
    42  | v0.16.0 | 2020.10.26           | `@bwplotka`                   |
    43  | v0.15.0 | 2020.08.12           | `@kakkoyun`                   |
    44  | v0.14.0 | 2020.07.10           | `@kakkoyun`                   |
    45  | v0.13.0 | 2020.05.13           | `@bwplotka`                   |
    46  | v0.12.0 | 2020.04.15           | `@squat`                      |
    47  | v0.11.0 | 2020.02.19           | `@metalmatze`                 |
    48  | v0.10.0 | 2020.01.08           | `@GiedriusS`                  |
    49  | v0.9.0  | 2019.11.26           | `@bwplotka`                   |
    50  | v0.8.0  | 2019.10.09           | `@bwplotka`                   |
    51  | v0.7.0  | 2019.08.28           | `@domgreen`                   |
    52  | v0.6.0  | 2019.07.12           | `@GiedriusS`                  |
    53  | v0.5.0  | 2019.06.31           | `@bwplotka`                   |
    54  
    55  # For maintainers: Cutting individual release
    56  
    57  Process of releasing a *minor* Thanos version:
    58  
    59  1. Release `v<major>.<minor+1>.0-rc.0`
    60  2. If after 3 work days there is no major bug, release `v<major>.<minor>.0`
    61  3. 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 step 2.
    62  4. Do patch release if needed for any bugs afterwards. Use same `release-xxx` branch and migrate fixes to main.
    63  
    64  ## How to release a version
    65  
    66  Release is happening on separate `release-<major>.<minor>` branch.
    67  
    68  ### Prepare the release branch
    69  
    70  Prepare branch `release-<major>.<minor>` that will start minor release branch and prepare changes to cut release.
    71  
    72  Push the created branch to origin (Thanos repository) to be able to make your PR with the CHANGELOG.md changes against this branch later.
    73  
    74  ```bash
    75  $ git push origin release-<major>.<minor>
    76  ```
    77  
    78  For release candidate, reuse the same branch and rebase it on every candidate until the actual release happens.
    79  
    80  ### Indicate that a release is in progress
    81  
    82  1. Create small PR to `main` (!) to cut CHANGELOG. This helps to maintain new changelog on main. Add entry to CHANGELOG indicating release in progress. This reduces risk for the new PRs to add changelog entries to already released release.
    83  
    84  2. Update `VERSION` file to version one minor version higher than the released one and `dev` suffix. This allows CI to build Thanos binary with the version indicating potential next minor release, showing that someone uses non-released binary (which is fine, just better to know this!).
    85  
    86  Feel free to mimic following PR: https://github.com/thanos-io/thanos/pull/3861
    87  
    88  ### Prepare the release
    89  
    90  1. Create a branch based on the release branch. You will use this branch to include any changes that need to happen as a part of 'cutting' the release. Follow the steps below and commit and resulting changes to this branch.
    91  
    92  2. Double check and update [CHANGELOG file](../CHANGELOG.md). Note that `CHANGELOG.md` should only document changes relevant to users of Thanos, including external API changes, bug fixes, performance improvements, and new features. Do not document changes of internal interfaces, code refactorings and clean-ups, changes to the build process, etc. People interested in these are asked to refer to the git history. Format is described in `CHANGELOG.md`.
    93     - The whole release from release candidate `rc.0` to actual release should have exactly the same section. We don't separate what have changed between release candidates.
    94  
    95  3. Double check backward compatibility:
    96  
    97     1. *In case of version after `v1+.y.z`*, double check if none of the changes break API compatibility. This should be done in PR review process, but double check is good to have.
    98     2. In case of `v0.y.z`, document all incompatibilities in changelog.
    99  
   100  4. Double check metric changes:
   101  
   102     1. Note any changes in the changelog
   103     2. If there were any changes then update the relevant alerting rules and/or dashboards since `thanos-mixin` is part of the repository now
   104  
   105  5. *(Applies only to minor, non-`rc` release)* Update website's [hugo.yaml](https://github.com/thanos-io/thanos/blob/main/website/hugo.yaml) to have correct links for new release ( add `0.y.z: "/:sections/:filename.md"`).
   106  
   107  6. *(Applies only to minor, non-`rc` release)* Update tutorials:
   108  
   109     1. Update the Thanos version used in the [tutorials](https://github.com/thanos-io/tutorials) manifests to use the latest version.
   110     2. In case of any breaking changes or necessary updates adjust the manifests so the tutorial stays up to date.
   111     3. Update the [scripts/quickstart.sh](https://github.com/thanos-io/thanos/blob/main/scripts/quickstart.sh) script if needed.
   112  
   113  7. Set the version in `VERSION` to reflect the tag you are going to make.
   114     - If you are going to tag `v<major>.<minor>.0-rc.0`, this exact tag should be in `VERSION`. Example: [v0.25.2-rc.0/VERSION](https://github.com/thanos-io/thanos/blob/v0.25.2-rc.0/VERSION)
   115  
   116  8. Open a PR with any changes resulting from the previous steps against the release branch and ask the maintainers to review it.
   117  
   118  ### Tag and publish the release
   119  
   120  1. After review and obtaining (an) approval(s), merge the PR and 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 following [procedure](https://docs.github.com/en/authentication/managing-commit-signature-verification/generating-a-new-gpg-key), you can replace the `-s` flag by `-a` flag of the `git tag` command to only annotate the tag without signing.
   129  
   130     Please make sure that you are tagging the merge commit because otherwise GitHub's UI will show that there were more commits after your release.
   131  
   132  2. Once a tag is created and pushed, **immediately** create a GitHub Release using the UI for this tag, as otherwise CircleCI will not be able to upload tarballs for this tag. Go to the releases page of the project, click on the `Draft a new release` button and select the tag you just pushed. Describe release and post relevant entry from changelog. Click `Save draft` **rather** than `Publish release` at this time. (This will prevent the release being visible before it has got the binaries attached to it.) *In case you did not manage to create the draft release before CircleCI run is finished (it will fail on the artifacts upload step in this case), you can re-trigger the run manually from the CircleCI dashboard *after* you created the draft release.*
   133  
   134  3. You are also encouraged to include a list of (first time) contributors to the release. You can do this by clicking on `Auto-generate release notes`, which will generate this section for you (edit the notes as required to remove unnecessary parts).
   135  
   136  4. Once tarballs are published on release page, you can click `Publish` and release is complete.
   137  
   138  ### Completing the release
   139  
   140  1. Announce the release on the `#thanos` Slack channel. You are also encouraged to announce the new release on any Thanos social media accounts, such as Twitter (the credentials are available via Thanos' [Keybase](https://keybase.io/) team which includes all maintainers).
   141  
   142  2. Pull commits from release branch to main branch for non `rc` releases. Make sure to not modify `VERSION`, it should be still pointing to `version+1-dev` ([TODO to automate this](https://github.com/thanos-io/thanos/issues/4741))
   143  
   144  3. After releasing a major version, please cut a release for `kube-thanos` as well. https://github.com/thanos-io/kube-thanos/releases Make sure all the flag changes are reflected in the manifests. Otherwise, the process is the same, except we don't have `rc` for the `kube-thanos`. We do this to make sure we have compatible manifests for each major versions.
   145  
   146  4. Merge `release-<major>.<minor>` branch back to main. This is important for Go modules tooling to make release tags reachable from main branch.
   147  
   148     - Create `merge-release-<major>.<minor>-to-main` branch **from `release-<major>.<minor>` branch** locally
   149     - Merge upstream `main` branch into your `merge-release-<major>.<minor>-to-main` and resolve conflicts
   150     - Open a PR for merging your `merge-release-<major>.<minor>-to-main` branch against `main`
   151     - Once approved, merge the PR **by using "Merge" commit**.
   152       - This can either be done by temporarily enabling "Allow merge commits" option in "Settings > Options".
   153       - Alternatively, this can be done locally by merging `merge-release-<major>.<minor>-to-main` branch into `main`, and pushing resulting `main` to upstream repository. This doesn't break `main` branch protection, since PR has been approved already, and it also doesn't require removing the protection.
   154  
   155  ## Pre-releases (release candidates)
   156  
   157  The following changes to the above procedures apply:
   158  
   159  * In line with [Semantic Versioning](http://semver.org/), append something like `-rc.0` to the version (with the corresponding changes to the tag name, the release name etc.).
   160  * Tick the `This is a pre-release` box when drafting the release in the GitHub UI.
   161  * Still update `CHANGELOG.md`, but when you cut the final release later, merge all the changes from the pre-releases into the one final update.