diff --git a/docs/release-process.md b/docs/release-process.md index 80ed163c..3f00d751 100644 --- a/docs/release-process.md +++ b/docs/release-process.md @@ -8,13 +8,27 @@ set and export `$GITHUB_TOKEN` with this value * Update all dependencies with `make update` +## Release Types + +The release script behaves differently depending on the kind of +release you are doing. There are three types: + +* **Mainline** - a release (typically from master) with version tag + `vX.Y.Z` where Z is zero (e.g. `v2.1.0`) +* **Branch** - a bugfix release (typically from a branch) with version tag + `vX.Y.Z` where Z is non-zero (e.g `v2.1.1`) +* **Prerelease** - a release from an arbitrary branch with an arbitrary + version tag (e.g. `feature-preview-20150904`) + +N.B. the release script _infers the release type from the format of the +version tag_. Ensure your tag is in the correct format and the desired +behaviours for that type of release will be obtained from the script. + ## 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`) +* Choose a version tag (see above) henceforth referred to as `$TAG`. * 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` @@ -61,17 +75,15 @@ instead! You're now ready to draft your release notes: - bin/release draft [--pre-release] + bin/release draft 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 + it is only visible to contributors; for **Prerelease** builds the + pre-release attribute will also be set * 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 @@ -83,7 +95,7 @@ phase. ## Publish Phase ### Move/Force Push `latest_release` Tag -This step must only be performed for mainline (non pre-release) +This step must only be performed for **Mainline** and **Branch** releases: git tag -af -m "Release $TAG" latest_release $TAG @@ -102,17 +114,19 @@ distributables to DockerHub: bin/release publish -This has the following effects: +The effects of this step depend on the inferred release type. The +following occurs for all types: * 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) +Additionally, for **Mainline** and **Branch** types: + +* Release named `latest_release` is updated on GitHub + +Finally, for **Mainline** releases only: * Images tagged `latest` are updated on DockerHub -* Release named `latest_release` is updated on GitHub ## Troubleshooting