From ab18b07664112dead87252c0d18136b8cccfdaf6 Mon Sep 17 00:00:00 2001 From: Callum Styan Date: Thu, 13 Feb 2020 14:00:09 -0800 Subject: [PATCH 1/5] Re-arrange contents of RELEASE.md to clarify ordering of steps regardless of the release type (stable or RC). Signed-off-by: Callum Styan --- RELEASE.md | 33 +++++++++++++++++---------------- 1 file changed, 17 insertions(+), 16 deletions(-) diff --git a/RELEASE.md b/RELEASE.md index de92cf787..3b08a5e81 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -46,13 +46,15 @@ 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`. +For a release candidate, append something like `-rc.0` to the version (with the corresponding changes to the tag name, the release name etc.). + 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. 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. Maintaining the release branches for older minor releases happens on a best effort basis. -### Updating dependencies +### 0. Updating dependencies A few days before a major or minor release, consider updating the dependencies: @@ -75,16 +77,21 @@ 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. -### Prepare your release +### 1. Prepare your release -For a patch release, work in the branch of the minor release you want to patch. +Create a new release branch. + +For a patch release, work in the branch of the minor release you want to patch. So for 2.16.1, create a new branch off of 2.16.0. For a new major or minor release, create the corresponding release branch based on the master branch. +** Note: ** this means that for a release candidate you should also create the non-release candidate branch (2.16.0 vs 2.16.0-rc.0) and merge the RC versions into it as you go. 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. 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. +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. + Entries in the `CHANGELOG.md` are meant to be in this order: * `[CHANGE]` @@ -92,7 +99,7 @@ Entries in the `CHANGELOG.md` are meant to be in this order: * `[ENHANCEMENT]` * `[BUGFIX]` -### Draft the new release +### 2. Draft the new release Tag the new release with a tag named `v..`, e.g. `v2.1.3`. Note the `v` prefix. @@ -108,21 +115,15 @@ Signing a tag with a GPG key is appreciated, but in case you can't add a GPG key 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. -Now all you can do 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. +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. +** Note: ** for a release candidate version the _This is a pre-release_ box when drafting the release in the Github UI. -### Wrapping up +### 3. Wrapping up + +For release candidate versions, run the benchmark for 3 days using the `/benchmark x.y.z` command, `x.y.z` being the latest stable patch release of the previous minor release series. If the release has happened in the latest release branch, merge the changes into master. 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). -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. - -### Pre-releases - -The following changes to the above procedures apply: - -* In line with [Semantic Versioning](https://semver.org/), append something like `-rc.0` to the version (with the corresponding changes to the tag name, the release name etc.). -* Tick the _This is a pre-release_ box when drafting the release in the Github UI. -* 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. -* Run the benchmark for 3 days using the `/benchmark x.y.z` command, `x.y.z` being the latest stable patch release of the previous minor release series. +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. \ No newline at end of file From fd20cca00bc43f395bc5edbec85fae53385b1a0d Mon Sep 17 00:00:00 2001 From: Callum Styan Date: Fri, 14 Feb 2020 11:02:32 -0800 Subject: [PATCH 2/5] Updates to RELEASE.md based on review feedback. Signed-off-by: Callum Styan --- RELEASE.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/RELEASE.md b/RELEASE.md index 3b08a5e81..4cdbae6c3 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -46,8 +46,6 @@ 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`. -For a release candidate, append something like `-rc.0` to the version (with the corresponding changes to the tag name, the release name etc.). - 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. 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. @@ -84,9 +82,9 @@ Create a new release branch. For a patch release, work in the branch of the minor release you want to patch. So for 2.16.1, create a new branch off of 2.16.0. For a new major or minor release, create the corresponding release branch based on the master branch. -** Note: ** this means that for a release candidate you should also create the non-release candidate branch (2.16.0 vs 2.16.0-rc.0) and merge the RC versions into it as you go. +** Note: ** this means that for a release candidate you should create the non-release candidate branch (release-2.16) and merge the RC versions (ex: cut-v2.16.0-rc.0) into it as you go. -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. +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.). 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. @@ -120,7 +118,7 @@ Finally, wait for the build step for the tag to finish. The point here is to wai ### 3. Wrapping up -For release candidate versions, run the benchmark for 3 days using the `/benchmark x.y.z` command, `x.y.z` being the latest stable patch release of the previous minor release series. +For release candidate versions, 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` If the release has happened in the latest release branch, merge the changes into master. From b4fb97d8b69ae9c760bb88042b6c140b9f42bfd7 Mon Sep 17 00:00:00 2001 From: Callum Styan Date: Tue, 18 Feb 2020 12:42:52 -0800 Subject: [PATCH 3/5] Clarify release branch conditions and pre-release relase step on GH UI based on Bjorn's review. Signed-off-by: Callum Styan --- RELEASE.md | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/RELEASE.md b/RELEASE.md index 4cdbae6c3..33162bf53 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -77,12 +77,9 @@ later follow-up. ### 1. Prepare your release -Create a new release branch. +For a new major or minor release, create the corresponding release branch based on the master branch. Note that a new a new release branch in `origin` is only necessary if there is not already one for this . version. 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. Patch release don't require their own `release-.., and the same for release candidate versions. -For a patch release, work in the branch of the minor release you want to patch. So for 2.16.1, create a new branch off of 2.16.0. - -For a new major or minor release, create the corresponding release branch based on the master branch. -** Note: ** this means that for a release candidate you should create the non-release candidate branch (release-2.16) and merge the RC versions (ex: cut-v2.16.0-rc.0) into it as you go. +For a patch release or release candidate any changes should be merged into the previously mentioned release branch. So for `2.16.1` or `2.16.0-rc.1` create a new branch off of `release-2.16` and open a PR with the necessary bug/regression fix. 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.). @@ -114,11 +111,11 @@ Signing a tag with a GPG key is appreciated, but in case you can't add a GPG key 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. 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. -** Note: ** for a release candidate version the _This is a pre-release_ box when drafting the release in the Github UI. +** 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_.` ### 3. Wrapping up -For release candidate versions, 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` +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`. If the release has happened in the latest release branch, merge the changes into master. From 6ad7ec50f7fd004dfa0f5ffc2d4dfc5ccee0d5af Mon Sep 17 00:00:00 2001 From: Callum Styan Date: Wed, 19 Feb 2020 10:35:34 -0800 Subject: [PATCH 4/5] Clarify branch naming/not creating release-x branches for patch/RC. Signed-off-by: Callum Styan --- RELEASE.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/RELEASE.md b/RELEASE.md index 33162bf53..6c551d3de 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -46,6 +46,8 @@ 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`. +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. + 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. 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. @@ -77,9 +79,9 @@ later follow-up. ### 1. Prepare your release -For a new major or minor release, create the corresponding release branch based on the master branch. Note that a new a new release branch in `origin` is only necessary if there is not already one for this . version. 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. Patch release don't require their own `release-.., and the same for release candidate versions. +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-.` branch. Do not create `release-` for patch or release candidate releases. -For a patch release or release candidate any changes should be merged into the previously mentioned release branch. So for `2.16.1` or `2.16.0-rc.1` create a new branch off of `release-2.16` and open a PR with the necessary bug/regression fix. +Changes for a patch release or release candidate should be merged into the previously mentioned release branch via pull request. 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.). @@ -121,4 +123,6 @@ If the release has happened in the latest release branch, merge the changes into 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). -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. \ No newline at end of file +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. + +Finally, open a PR in the docs repo to \ No newline at end of file From 53aa2541e5feb30f48070087716beed3531f9d88 Mon Sep 17 00:00:00 2001 From: Callum Styan Date: Wed, 19 Feb 2020 10:42:19 -0800 Subject: [PATCH 5/5] Simplify tagging section to reduce chance of misinterpreting what the tag should be. Signed-off-by: Callum Styan --- RELEASE.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/RELEASE.md b/RELEASE.md index 6c551d3de..f1c23f64d 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -98,9 +98,7 @@ Entries in the `CHANGELOG.md` are meant to be in this order: ### 2. Draft the new release -Tag the new release with a tag named `v..`, e.g. `v2.1.3`. Note the `v` prefix. - -You can do the tagging on the commandline: +Tag the new release via the following commands: ```bash $ tag=$(< VERSION) @@ -123,6 +121,4 @@ If the release has happened in the latest release branch, merge the changes into 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). -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. - -Finally, open a PR in the docs repo to \ No newline at end of file +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. \ No newline at end of file