Support draft and pre-releases in bin/release

[awh]

This PR refactors the bin/release script to have three steps:

bin/release build
bin/release draft [--pre-release]
bin/release publish

The second step creates the GitHub release in draft state, optionally marked as pre-release; the final step removes the draft state (making the release visible to the outside world) and updates latest in {Git,Docker}Hub only if the pre-release attribute is missing.

Caveats

• The previous implementation used git-describe with a --match=v* to find the most recent version tag. To support non-mainline releases I've had to remove all the 'v' related logic with three consequences:
  • The version in the changelog must match the exact tag name. For mainline releases it must include the 'v' prefix, which is not currently the case
  • With no prefix to search for, the new implementation uses git tag --points-at HEAD and expects to find a single tag there which it assumes is the version tag. This is slightly less flexible that before, because it means the HEAD of your local branch must be the tagged commit that you want to build
  • The latest_release tag must point at the version tag, not directly at the commit object (e.g. you must now use git tag -af latest_release v2.0.0 whereas before you could have had v2.0.0 checked out and done git tag -af latest_release). The current release instructions describe the first method anyway, so probably not a big deal

Outstanding Issues

• Something of a showstopper - the github-release edit command used to remove the draft status resets the description field. I can think of a several solutions to this, none of which are very appealing:
  • Read the description with github release info first and then supply it back as an argument to github-release edit. Note that the output of info isn't really amenable to reliable parsing, particularly in the face of the freeform multiline description field
  • Manipulate the GitHub API directly to remove the draft status. Not straightforward due to the need to manually search through the (potentially paginated) list of releases to find the release ID; if we are willing to do this, begs the question of why we're bothering with github-release
  • Prompt the user to publish the release manually using the Github UI. We could do this either at the end of bin/release publish, or we could require them to do it first and check at the start
• The current release process instructions specify (in bold) that the user updates the latest_release tag in the repository cloned into releases/, not in the repository in which they created the version tag and are running bin/release. This seems odd - does anyone object to the checks being modified so that they all operate on the 'outer' repository? (Related, there's a bug in the current logic anyway - see the 'Fix latest_release hash test' commit in this PR)

@dpw @rade @squaremo particularly interested in your opionions on the caveats and issues - this PR isn't ideal at the moment. Will hold off producing updated release process instructions for the wiki until things are ironed out.

Further explanatory material is available in the individual commit messages.

Fixes #880, fixes #909.

[awh]

I've looked at fixing github-release edit so that it only populates the PATCH JSON for those properties that have been specified, but the command line parser they use isn't up to it (it can't distinguish between not specifying a string vs specifying an empty string for example). It wouldn't be hard to add a github-release publish that just flips the bit we require though, and it does align with the GitHub UI operations so would probably be acceptable upstream as a PR.

[awh]

I have forked github-release, implemented github-release publish and updated bin/release to use it.

go get github.com/weaveworks/github-release to test...

[awh]

After discussion with @squaremo I have modified the script so that all tag checking operations happen on the outer repository. Since both currently outstanding issues are now addressed, I've included another commit which adds docs/release-process.md outlining the new release process.

[awh]

Have tested both mainline and pre-release paths; this PR is ready for review.

[awh]

Update documentation.

[rade]

LGTM

I suggest we

• get rid of https://github.com/weaveworks/weave/wiki/Release-Process
• add a link to the new docs to https://github.com/weaveworks/weave/wiki and https://github.com/weaveworks/weave/wiki/TestingReleaseProcess (or perhaps incorporate the latter as a separate section in the new docs)