Merge pull request #1514 from weaveworks/docs/release-process

Update doc on release process

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