Skip to content

Release Process

Jump to bottom
Ilya Dmitrichenko edited this page Sep 28, 2016 · 45 revisions

This is fine.

This runbook cobbled together from

When you have a problem, please ask a Scope team member, starting with Peter, for help. When you've figured it out, please edit the document to reflect the fix! Through our powers combined, we can make this process better.

Live-stream your release

If you have the energy, please consider live-streaming your release on the chat. It's really helpful for tracking problems and fixes. It can also serve as a helpful source of information for those who follow in your footsteps.

Set up your docker env

E.g. under Mac OS:

eval "$(docker-machine env weave-1)"

Make deps

Get the latest tools.

$ make deps

Create a release branch

$ git checkout -b release-0.1

NB don't include patch versions in the branch name - successive patch versions for a given minor will be released of the same branch. (i.e. name your branch release-0.1 and not relase-0.1.0)

Get a GitHub token

If you don't have one already, go to https://github.com/settings/tokens/new and make one with a funny name, and the public_repo scope only. (I think.)

Update the CHANGELOG, update docs and test

See https://github.com/weaveworks/scope/compare/latest_release...master for a diff. A starting point for the CHANGELOG entry for this release can be obtained by running a little CLI-fu. (Make sure to have jq installed for JSON processing.):

# set github token
export GITHUB_TOKEN=xxx
# update latest_release tag in local clone
git fetch -t origin
# get merged PR titles
git log --oneline latest_release...HEAD | \
  sed  -n -e 's%^.*Merge pull request #\([[:digit:]]*\) .*$%\1%p' -e 's%^.*(#\([[:digit:]]*\))$%\1%p'  | \
  xargs -I '{}' -- curl -s https://api.github.com/repos/weaveworks/scope/issues/{}?access_token=$GITHUB_TOKEN | \
  jq -r '(.number | tostring) as $number | "- " + .title + "\n" + "\t[#" + $number + "](https://github.com/weaveworks/scope/pull/" + $number + ")"'

Then sort the lines by feature, bug fix, performance etc. sections. You may find it helpful to look at the original issues of the PRs to see what they are about. Commit and push the CHANGELOG to the release branch.

Update docs

Update all version references in the documentation (i.e. under the site/ directory) to the version being released (e.g. all image versions in the installation docs such as weaveworks/scope:0.15 )

Test the release

  • Create a PR for the release branch, merging into master
  • For the description of the PR, supply a GFM checklist of things that need to be tested:
    • if it's a major release, use the Release Qualification checklist
    • if it's a patch release, make a list of things to be tested

Also, load the release branch on your test machines, and click around. If you discover any issues, or find yourself looking for anything in particular, update the Release Qualification checklist so we can get it deliberately next time.

Proceed from here only when:

  • Every item on the checklist has been tested and confirmed to work
  • The changelog has been reviewed and you have an LGTM

Tag

$ git tag -a -m "Release v0.1.0" v0.1.0
$ git push --tags origin release-0.1
$ git tag -a -f -m "Release v0.1.0" latest_release v0.1.0
$ git push -f git@github.com:weaveworks/scope latest_release

bin/release build

This performs sanity checks and produces artifacts.

$ bin/release build

If you don't need sudo (most likely under Mac OS), run:

$ SUDO= bin/release build

bin/release draft

Create release draft on GitHub

$ env GITHUB_TOKEN=xxx bin/release draft

Edit release description on GitHub

Go to https://github.com/weaveworks/scope/releases and edit the most recent release description so it matches the previous releases, editing the links as appropriate. Click Save draft, not Publish!

bin/release publish

Log in to Docker Hub with your account.

$ docker login
Username: <your username>
Password:
Email: <your email>

Then push the release:

$ env GITHUB_TOKEN=xxx bin/release publish

This interacts with Docker. If you don't need sudo to run Docker commands, you should do

$ env GITHUB_TOKEN=xxx SUDO= bin/release publish

Merge

Merge the release branch to master.

Add new release to checkpoint-api.weave.works

Go to https://checkpoint-api.weave.works/admin and fill in the details of the release for both for the scope-app and scope-probe products so that users can be automatically informed of a new version being available.

Publish release documentation

  1. Install wordepress: go get -u github.com/weaveworks/wordepress/cmd/wordepress
  2. Obtain a Wordpress application password:
    • Login to https://weave.works/wp-admin
    • Navigate to Users -> Your Profile -> Application Passwords
    • Enter 'wordepress' as the application name and choose 'Add New'
  3. Publish the documentation:
    • Dry run: wordepress publish --dry-run --url https://www.weave.works --user yourwordpressuser --password 'your wordpress application password' --product scope --tag latest --version 0.1.0 releases/v0.1.0/site
    • If everything went well, pubslish without dry-run: wordepress publish --url https://www.weave.works --user yourwordpressuser --password 'your wordpress application password' --product scope --tag latest --version 0.1.0 releases/v0.1.0/site

You're done. Congratulations.

Updating release documentation

If you merged a documentation change to master, you can update the published docs with wordepress (see above for setup instructions).

First, check commit log to confirm that master doesn't have documentation that doesn't relate to the release:

git fetch --tags
git log -p latest_release..@ site/

If all looks good, do this:

wordepress publish --dry-run --url https://www.weave.works --user 'you' --password 'secret' --product scope --tag latest --version 0.17.1 site

The output should look similar to this:

2016/09/28 14:28:35 Loading 6 markdown files from site
2016/09/28 14:28:36 Loaded document scope-latest-plugins
2016/09/28 14:28:36 Loaded document scope-latest-introducing
2016/09/28 14:28:36 Loaded document scope-latest-installing
2016/09/28 14:28:36 Loaded document scope-latest-how-it-works
2016/09/28 14:28:36 Loaded document scope-latest-features
2016/09/28 14:28:36 Loaded document scope-latest-building
2016/09/28 14:28:36 Would skip document: scope-latest-building
2016/09/28 14:28:36 Would skip document: scope-latest-features
2016/09/28 14:28:36 Would skip document: scope-latest-how-it-works
2016/09/28 14:28:36 Would update document: scope-latest-installing
2016/09/28 14:28:36 Would skip document: scope-latest-introducing
2016/09/28 14:28:36 Would skip document: scope-latest-plugins
2016/09/28 14:28:36 Would skip image: e9fc2b7bec70c15acf1e954af137bae149bd0ffe.png
2016/09/28 14:28:36 Would skip image: 1f6124fdbc669622d6b498572e44894880e78e5a.png
2016/09/28 14:28:36 Would skip image: cd819a0671f32847e35a23e21420b13766d2e8fa.png
2016/09/28 14:28:36 Would skip image: 30e8bef5b3470abc9c64b11a63d864a74d1fecdd.png
2016/09/28 14:28:36 Would skip image: a2aaa36fe950f3fbfa663c9272e6dc523cabb2f3.png
2016/09/28 14:28:36 Would skip image: 67ef4e34ecf59431a1a787cafe1f56cc225e8d69.png
2016/09/28 14:28:36 Would skip image: 6e5464122a73510c718b8242ed4be58402edc95b.png
2016/09/28 14:28:36 Would skip image: 12feb8d1235160296f11ddb22edfaaa34a9bf0eb.png
2016/09/28 14:28:36 Would skip image: 29238657a28fa87c6588fa4207e6cecdd16840f0.png

In the above case we can see that the only file that will updates is this:

2016/09/28 14:28:36 Would update document: scope-latest-installing

Which is good, so no run without --dry-run:

wordepress publish --dry-run --url https://www.weave.works --user 'you' --password 'secret' --product scope --tag latest --version 0.17.1 site
Clone this wiki locally