From 5744ed8994bb5429d7a6b26961623d025c5f62f1 Mon Sep 17 00:00:00 2001
From: Adam Harrison <harrisonadamw@gmail.com>
Date: Wed, 2 Sep 2015 12:35:13 +0100
Subject: [PATCH] Document release process

---
 docs/release-process.md | 131 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 131 insertions(+)
 create mode 100644 docs/release-process.md

diff --git a/docs/release-process.md b/docs/release-process.md
new file mode 100644
index 00000000..80ed163c
--- /dev/null
+++ b/docs/release-process.md
@@ -0,0 +1,131 @@
+# Release Process
+## Prerequisites
+
+* Up-to-date versions of `git`, `go` etc
+* Install GitHub release tool `go get github.com/weaveworks/github-release`
+* Create a [github token for
+  github-release](https://help.github.com/articles/creating-an-access-token-for-command-line-use/);
+set and export `$GITHUB_TOKEN` with this value
+* Update all dependencies with `make update`
+
+## Build Phase
+### Update CHANGELOG.md
+
+* Checkout the branch from which you wish to release
+* Choose an appropriate version tag, henceforth referred to as `$TAG`.
+  Mainline releases use a version number (e.g. `TAG=v2.0.0`), whereas
+  pre-releases get a descriptive name (e.g. `TAG=feature-preview-20150902`)
+* Add a changelog entry for the new tag at the top of `CHANGELOG.md`.
+  The first line must be a markdown header of the form `## Release
+  $TAG`
+
+Commit the changelog update:
+
+    git commit -m "Add release $TAG" CHANGELOG.md
+
+### Create Version Tag
+
+Next you must tag the changelog commit with `$TAG`
+
+    git tag -a -m "Release $TAG" $TAG
+
+### Execute Build
+
+You are now ready to perform the build. If you have skipped the
+previous steps (e.g. because you're doing a rebuild), you must ensure
+that `HEAD` points to the tagged commit. You may then execute
+
+    bin/release build
+
+This has the following effects:
+
+* `git tag --points-at HEAD` is used to determine `$TAG` (hence the
+  `HEAD` requirement)
+* Your *local* repository is cloned into `releases/$TAG`
+* `CHANGELOG.md` is checked to ensure it has an entry for `$TAG`
+* Distributables injected with `$TAG` are built
+* Tests are executed
+
+## Draft Phase
+### Push Version Tag Upstream
+
+First you must push your version tag upstream, so that an associated
+GitHub release may be created:
+
+    git push git@github.com:weaveworks/weave $TAG
+
+N.B. if you're testing the release process, push to your fork
+instead!
+
+### Create Draft Release
+
+You're now ready to draft your release notes:
+
+    bin/release draft [--pre-release]
+
+This has the following effects:
+
+* A [release](https://help.github.com/articles/about-releases) is
+  created in GitHub for `$TAG`. This release is in the draft state, so
+  it is only visible to contributors
+* The `weave` script is uploaded as an attachment to the release
+* If `--pre-release` is specified, the release will have the
+  pre-release attribute set (this affects the way GitHub displays the
+  release and modifies the behaviour of the publish phase)
+
+Navigate to https://github.com/weaveworks/weave/releases, 'Edit' the
+draft and input the release notes. When you are done make sure you
+'Save draft' (and not 'Publish release'!).
+
+Once the release notes have passed review, proceed to the publish
+phase.
+
+## Publish Phase
+### Move/Force Push `latest_release` Tag
+
+This step must only be performed for mainline (non pre-release)
+releases:
+
+    git tag -af -m "Release $TAG" latest_release $TAG
+    git push -f git@github.com:weaveworks/weave latest_release
+
+The `latest_release` tag *must* point at `$TAG`, *not* at `HEAD` -
+the build script will complain otherwise.
+
+N.B. if you're testing the release process, push to your fork
+instead!
+
+### Publish Release & Distributable Artefacts
+
+You can now publish the release and upload the remaining
+distributables to DockerHub:
+
+    bin/release publish
+
+This has the following effects:
+
+* Docker images are tagged `$TAG` and pushed to DockerHub
+* GitHub release moves from draft to published state
+
+Furthermore, if this is a mainline release (detected automatically
+from the GitHub release, you do not need to specify the flag again to
+the publish step)
+
+* Images tagged `latest` are updated on DockerHub
+* Release named `latest_release` is updated on GitHub
+
+
+## Troubleshooting
+
+There's a few things that can go wrong.
+
+ * If the build is wonky, e.g., the tests don't pass, you can delete
+   the directory in `./releases/`, fix whatever it is, move the
+   version tag (which should still be only local) and have another go.
+ * If the DockerHub pushes fail (which sadly seems to happen a lot),
+   you can just run `./bin/release publish` again.
+ * If you need to overwrite a release you can do so by manually
+   deleting the GitHub version release and re-running the process.
+   Please note that the DockerHub `latest` images, GitHub
+   `latest_release` and download links may be in an inconsistent state
+   until the overwrite is completed.