From 6cf5fa60aab1b5fcc8b57d3022ea729e07d7d671 Mon Sep 17 00:00:00 2001 From: Michael Bridgen Date: Wed, 14 Nov 2018 15:52:17 +0000 Subject: [PATCH] Update doc on release process Mainly to account for using "release series" branches, as we've started to do. And to be a bit more generous with explanation. --- internal_docs/releasing.md | 134 ++++++++++++++++++++++++++++++++----- 1 file changed, 119 insertions(+), 15 deletions(-) diff --git a/internal_docs/releasing.md b/internal_docs/releasing.md index ba04f8885..1d35921ec 100644 --- a/internal_docs/releasing.md +++ b/internal_docs/releasing.md @@ -1,27 +1,131 @@ -# How to make a release of flux +# How to release Flux and the Helm operator -This process will create a new tagged release of flux, push dockerfiles and upload the `fluxctl` binary to GitHub releases. +The release process needs to do these things: + + - create a new release on GitHub, with a tag + - push Docker image(s) to quay.io + - possibly upload the `fluxctl` binaries to the GitHub release + - make sure the version is entered into the checkpoint database so + that up-to-date checks report back accurate information + +Much of this is automated, but it needs a human to turn the wheel. + +## Overview + +The Flux daemon and the Helm operator have separate releases, and use +different branches and tags. Flux daemon releases use just a semver +version, like `1.8.1`, and the Helm operator uses the prefix "helm", +e.g., `helm-0.5.0`. + +Each minor version has its own "release series" branch, from which +patch releases will be put together, called e.g., `release/1.8.x`, or +for the Helm operator, `release/helm-0.5.x`. + +The CircleCI script runs builds for tags, which push Docker images and +upload binaries. This is triggered by creating a release in GitHub, +which will create the tag. ## Requirements -- Circle CI must have a secret environmental variable called `GITHUB_TOKEN` which is a personal access token. + +- CircleCI must have a secret environmental variable called + `GITHUB_TOKEN` which is a personal access token. (This is almost + certainly already set up, but mentioned here in case it needs to be + reinstated.) ## Release process -1. Alter and commit the /CHANGELOG.md file to signify what has changed in this version. -2. Ensure example deployment is up-to-date. (Check image tags) -3 Push that to a PR and have it reviewed. - 3.1 Merge! -4. Create a new release: https://github.com/weaveworks/flux/releases/new -5. Fill in the version number for the name and tag. The version number should conform to [semver](semver.org); i.e., look like `1.2.3` (NB: no leading 'v'); optionally with a pre-release suffix, e.g., `1.0.0-beta` -6. Fill in the Description field (possibly a copy paste from the CHANGELOG.md) -7. Click "Publish release" -8. Add a new release to https://checkpoint-api.weave.works/admin +**Preparing the release PR** + +1. If the release is a new minor version, create a "release series" + branch and push it to GitHub. + +Depending on what is to be includeed in the release, you may need to +pick a point from which branch that is not HEAD of master. But +usually, it will be HEAD of master. + +2. From the release series branch, create _another_ branch for the + particular release. This will be what you submit as a PR. + +For example, + +```sh +git checkout release/1.8.x +git pull origin +git checkout -b release/1.8.1 +``` + +3. Put the commits you want in the release, into your branch + +If you just created a new release series branch, i.e., this is a +`x.y.0` patch release, you may already have what you need, because +you've just branched from master. + +If this is _not_ the first release on this branch, you will need to +either merge master, or cherry-pick commits from master, to get the +things you want in the release. + +4. Put an entry into the changelog + +For the Flux daemon, it's `CHANGELOG.md`; for the Helm operator, it's +`CHANGELOG-helmop.md`. Follow the format established, and commit your +change. + +If you cherry-picked commits, remember to only mention those changes. + +To compile a list of people (GitHub usernames) to thank, you can use a +script (if you have access to weaveworks/dx) or peruse the commits/PRs +merged/issues since the last release. There's no exact way to do +it. Be generous. + +5. Post the branch as a PR to the release series + +Push the patch release branch -- e.g., `release/1.8.1` -- to GitHub, +and create a PR from it. + +**Please note** You will need to change the branch the PR targets, +from `master` to the release series, e.g., `release/1.8.x`, while +creating the PR. + +Get the PR reviewed, and merge it. + +**Creating the release** + +6. [Create a release in GitHub](https://github.com/weaveworks/flux/releases/new) + +Use a tag name as explained above; semver for the flux daemon, `helm-` +then the semver for the Helm operator. + +Copy and paste the changelog entry. You may need to remove newlines +that have been inserted by your editor, so that it wraps nicely. + +Publishing the release will create the tag, and that will trigger CI +to build images and binaries. + +**After publishing the release** + +7. Put an entry in the checkpoint database + +Add a row to the [checkpoint +database](https://checkpoint-api.weave.works/admin) (or ask someone at +Weaveworks to do so). This is so that the up-to-date check will report +the latest available version correctly. + +8. Merge the release series branch back into master, so it has the + changelog entry. + +You can do this by creating a new PR in GitHub -- you don't need to +create any new branches, since you want to merge a branch that already +exists. -Circle will then run the build and upload the built binaries to the "Downloads" section of the release. +9. Consider updating the deploy manifest examples and the Helm + chart. -## Outputs +The example manifests are in [deploy](./deploy/) and +[deploy-helm](./deploy-helm/). Check the changes included in the +release, to see if arguments, volume mounts, etc., have changed. -The most recent binaries are always available at: https://github.com/weaveworks/flux/releases/latest +You can do these as additional PRs. Read on, for how to publish a new +Helm chart version. ## Helm chart release process