RELEASE.md 11.2 KB
Newer Older
Frederic Branczyk committed
1 2
# Releases

3
This page describes the release process and the currently planned schedule for upcoming releases as well as the respective release shepherd. Release shepherds are chosen on a voluntary basis.
Frederic Branczyk committed
4 5 6 7 8

## Release schedule

Release cadence of first pre-releases being cut is 6 weeks.

9
| release series | date of first pre-release (year-month-day) | release shepherd                            |
Frederic Branczyk committed
10 11 12 13
|----------------|--------------------------------------------|---------------------------------------------|
| v2.4           | 2018-09-06                                 | Goutham Veeramachaneni (GitHub: @gouthamve) |
| v2.5           | 2018-10-24                                 | Frederic Branczyk (GitHub: @brancz)         |
| v2.6           | 2018-12-05                                 | Simon Pasquier (GitHub: @simonpasquier)     |
14
| v2.7           | 2019-01-16                                 | Goutham Veeramachaneni (GitHub: @gouthamve) |
15
| v2.8           | 2019-02-27                                 | Ganesh Vernekar (GitHub: @codesome)         |
16
| v2.9           | 2019-04-10                                 | Brian Brazil (GitHub: @brian-brazil)        |
17
| v2.10          | 2019-05-22                                 | Björn Rabenstein (GitHub: @beorn7)          |
18
| v2.11          | 2019-07-03                                 | Frederic Branczyk (GitHub: @brancz)         |
19 20
| v2.12          | 2019-08-14                                 | Julius Volz (GitHub: @juliusv)              |
| v2.13          | 2019-09-25                                 | Krasi Georgiev (GitHub: @krasi-georgiev)    |
21
| v2.14          | 2019-11-06                                 | Chris Marchbanks (GitHub: @csmarchbanks)    |
22
| v2.15          | 2019-12-18                                 | Bartek Plotka (GitHub: @bwplotka)           |
23
| v2.16          | 2020-01-29                                 | Callum Styan (GitHub: @cstyan)              |
24
| v2.17          | 2020-03-11                                 | Julien Pivotto (GitHub: @roidelapluie)      |
25
| v2.18          | 2020-04-22                                 | Bartek Plotka (GitHub: @bwplotka)           |
26 27
| v2.19          | 2020-06-03                                 | Ganesh Vernekar (GitHub: @codesome)         |
| v2.20          | 2020-07-15                                 | Björn Rabenstein (GitHub: @beorn7)          |
28 29 30
| v2.21          | 2020-08-26                                 | Julien Pivotto (GitHub: @roidelapluie)      |
| v2.22          | 2020-10-07                                 | Frederic Branczyk (GitHub: @brancz)         |
| v2.23          | 2020-11-18                                 | **searching for volunteer**                 |
Frederic Branczyk committed
31 32 33

If you are interested in volunteering please create a pull request against the [prometheus/prometheus](https://github.com/prometheus/prometheus) repository and propose yourself for the release series of your choice.

34
## Release shepherd responsibilities
Frederic Branczyk committed
35

36
The release shepherd is responsible for the entire release series of a minor release, meaning all pre- and patch releases of a minor release. The process formally starts with the initial pre-release, but some preparations should be done a few days in advance.
Frederic Branczyk committed
37

38 39 40
* We aim to keep the master branch in a working state at all times. In principle, it should be possible to cut a release from master 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 master. 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.
* On the date listed in the table above, the release shepherd cuts the first pre-release (using the suffix `-rc.0`) and creates a new branch called  `release-<major>.<minor>` 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 running and monitoring a benchmark run of the pre-release for 3 days, after which, if successful, the pre-release is promoted to a stable release.
41
* If regressions or critical bugs are detected, they need to get fixed before cutting a new pre-release (called `-rc.1`, `-rc.2`, etc.).
42

Frederic Branczyk committed
43 44 45 46 47 48 49 50
See the next section for details on cutting an individual release.

## How to cut an individual release

These instructions are currently valid for the Prometheus server, i.e. the [prometheus/prometheus repository](https://github.com/prometheus/prometheus). Applicability to other Prometheus repositories depends on the current state of each repository. We aspire to unify the release procedures as much as possible.

### Branch management and versioning strategy

51
We use [Semantic Versioning](https://semver.org/).
Frederic Branczyk committed
52 53 54

We maintain a separate branch for each minor release, named `release-<major>.<minor>`, e.g. `release-1.1`, `release-2.0`.

55 56
Note that branch protection kicks in automatically for any branches whose name starts with `release-`. Never use names starting with `release-` for branches that are not release branches.

57
The usual flow is to merge new features and changes into the master branch and to merge bug fixes into the latest release branch. Bug fixes are then merged into master from the latest release branch. The master branch should always contain all commits from the latest release branch. As long as master hasn't deviated from the release branch, new commits can also go to master, followed by merging master back into the release branch.
Frederic Branczyk committed
58

beorn7 committed
59
If a bug fix got accidentally merged into master after non-bug-fix changes in master, the bug-fix commits have to be cherry-picked into the release branch, which then have to be merged back into master. Try to avoid that situation.
Frederic Branczyk committed
60 61 62

Maintaining the release branches for older minor releases happens on a best effort basis.

63
### 0. Updating dependencies
64

65
A few days before a major or minor release, consider updating the dependencies.
66 67 68 69 70 71 72 73 74 75 76 77

Then create a pull request against the master branch.

Note that after a dependency update, you should look out for any weirdness that
might have happened. Such weirdnesses include but are not limited to: flaky
tests, differences in resource usage, panic.

In case of doubt or issues that can't be solved in a reasonable amount of time,
you can skip the dependency update or only update select dependencies. In such a
case, you have to create an issue or pull request in the GitHub project for
later follow-up.

78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103
#### Updating Go dependencies

```
make update-go-deps
git add go.mod go.sum vendor
git commit -m "Update dependencies"
```

#### Updating React dependencies

Either upgrade the dependencies within their existing version constraints as specified in the `package.json` file (see https://docs.npmjs.com/files/package.json#dependencies):

```
cd web/ui/react-app
yarn upgrade
git add yarn.lock
```

Or alternatively, update all dependencies to their latest major versions. This is potentially more disruptive and will require more follow-up fixes, but should be done from time to time (use your best judgement):

```
cd web/ui/react-app
yarn upgrade --latest
git add package.json yarn.lock
```

104
### 1. Prepare your release
Frederic Branczyk committed
105

106
At the start of a new major or minor release cycle create the corresponding release branch based on the master branch. For example if we're releasing `2.17.0` and the previous stable release is `2.16.0` we need to create a `release-2.17` branch. Note that all releases are handled in protected release branches, see the above `Branch management and versioning` section. Release candidates and patch releases for any given major or minor release happen in the same `release-<major>.<minor>` branch. Do not create `release-<version>` for patch or release candidate releases.
Frederic Branczyk committed
107

108
Changes for a patch release or release candidate should be merged into the previously mentioned release branch via pull request.
Frederic Branczyk committed
109

110
Bump the version in the `VERSION` file and update `CHANGELOG.md`. Do this in a proper PR pointing to the release branch as this gives others the opportunity to chime in on the release in general and on the addition to the changelog in particular. For a release candidate, append something like `-rc.0` to the version (with the corresponding changes to the tag name, the release name etc.).
Frederic Branczyk committed
111 112 113

Note that `CHANGELOG.md` should only document changes relevant to users of Prometheus, including external API changes, 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.

114 115
For release candidates 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.

Frederic Branczyk committed
116 117 118 119 120 121 122
Entries in the `CHANGELOG.md` are meant to be in this order:

* `[CHANGE]`
* `[FEATURE]`
* `[ENHANCEMENT]`
* `[BUGFIX]`

123
### 2. Draft the new release
Frederic Branczyk committed
124

125
Tag the new release via the following commands:
Frederic Branczyk committed
126 127

```bash
Ben Kochie committed
128 129 130
$ tag="v$(< VERSION)"
$ git tag -s "${tag}" -m "${tag}"
$ git push origin "${tag}"
Frederic Branczyk committed
131 132
```

Ben Kochie committed
133 134 135 136 137 138 139 140 141
Optionally, you can use this handy `.gitconfig` alias.

```ini
[alias]
  tag-release = "!f() { tag=v${1:-$(cat VERSION)} ; git tag -s ${tag} -m ${tag} && git push origin ${tag}; }; f"
```

Then release with `git tag-release`.

Frederic Branczyk committed
142 143
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://help.github.com/articles/generating-a-gpg-key/), you can replace the `-s` flag by `-a` flag of the `git tag` command to only annotate the tag without signing.

Simon Pasquier committed
144
Once a tag is created, the release process through CircleCI will be triggered for this tag and Circle CI will draft the GitHub release using the `prombot` account.
Frederic Branczyk committed
145

146
Finally, wait for the build step for the tag to finish. The point here is to wait for tarballs to be uploaded to the Github release and the container images to be pushed to the Docker Hub and Quay.io. Once that has happened, click _Publish release_, which will make the release publicly visible and create a GitHub notification.
147
** Note: ** for a release candidate version ensure the _This is a pre-release_ box is checked when drafting the release in the Github UI. The CI job should take care of this but it's a good idea to double check before clicking _Publish release_.`
148 149

### 3. Wrapping up
Frederic Branczyk committed
150

151
For release candidate versions (`v2.16.0-rc.0`), run the benchmark for 3 days using the `/prombench vX.Y.Z` command, `vX.Y.Z` being the latest stable patch release's tag of the previous minor release series, such as `v2.15.2`.
Frederic Branczyk committed
152 153 154

If the release has happened in the latest release branch, merge the changes into master.

155
To update the docs, a PR needs to be created to `prometheus/docs`. See [this PR](https://github.com/prometheus/docs/pull/952/files) for inspiration (note: only actually merge this for final releases, not for pre-releases like a release candidate).
Frederic Branczyk committed
156

157
Once the binaries have been uploaded, announce the release on `prometheus-announce@googlegroups.com`. (Please do not use `prometheus-users@googlegroups.com` for announcements anymore.) Check out previous announcement mails for inspiration.