Streamline release process - Githubissues

ohsu-comp-bio / funnel

Funnel is a toolkit for distributed task execution via a simple, standard API.

https://ohsu-comp-bio.github.io/funnel

MIT License

121 stars 32 forks source link

Streamline release process #186

Open buchanae opened 7 years ago

buchanae commented 7 years ago

Releasing a new version requires great care currently. Ideally we can do it all in one command.

buchanae commented 7 years ago

Some of the steps are documented here: https://ohsu-comp-bio.github.io/funnel/docs/development/#release-process

Three gold stars if we can do this via TravisCI when a PR is merged to master.

buchanae commented 7 years ago

Had a bunch of new issues today:

[x] the git describe --tags --long --dirty LDFLAG gets in the way of releasing when I am also fixing the Makefile's release utils.
[x] figuring out how to properly tarball the releases is tricky. I think I have this solved though.
[x] the website changes are committed afterwards
[x] I forgot how to push the website to gh-pages

buchanae commented 7 years ago

One improvement I think we can make is to use the docs/ folder on the master branch for the website, which would remove the weird gh-pages stuff.

buchanae commented 6 years ago

Errors from other platforms:

$ tar xvfz funnel-linux-amd64-0.3.0.tar.gz
tar: Ignoring unknown extended header keyword `SCHILY.dev'
tar: Ignoring unknown extended header keyword `SCHILY.ino'
tar: Ignoring unknown extended header keyword `SCHILY.nlink'
./
tar: Ignoring unknown extended header keyword `LIBARCHIVE.creationtime'
tar: Ignoring unknown extended header keyword `SCHILY.dev'
tar: Ignoring unknown extended header keyword `SCHILY.ino'
tar: Ignoring unknown extended header keyword `SCHILY.nlink'
./funnel
tar: .: Cannot utime: Operation not permitted
tar: .: Cannot change mode to rwxr-xr-t: Operation not permitted
tar: Exiting with failure status due to previous errors

buchanae commented 6 years ago

Release content prep PR (in progress):

Update all issues and merged PR to have the milestone being released
Write release notes
- Are there backwards incompatible changes to the database schema?
- ...to the library API?
- ...to the command line?
- ...to the config?
- be sure to highlight breaking changes.
- be sure to follow the existing pattern of including links to the milestone and a comparison of commits between the released tag and the previous tag.
Set VERSION in Makefile
Edit website content to include download links and release notes
Make PR including change from steps above.

Release process from master branch:

Be on master branch, with PR merged from above.
Run make
Check funnel version
export GITHUB_TOKEN
Run make upload-release
Download binary to mac, untar, and run funnel version
Download binary to linux, untar and run funnel version
Include release notes in github release page
Run make website
Commit website changes and push to master

buchanae commented 6 years ago

This has gotten a lot easier, but there are still some tweaks to make, so leaving it open for at least on e more iteration.

Ideas for improvement:

look into github draft releases. This might make it easier to prepare/stage everything and have more of a single step publish.
merge generated/released website from a PR, instead of pushing to master
possibly keep release notes in separate files in a directory, so they are easily shared between github and the website.

buchanae commented 6 years ago

We should also include the docker container in the release process. That is currently way out of date.

buchanae commented 6 years ago

I created a homebrew tap for us: https://github.com/ohsu-comp-bio/homebrew-formula

Unfortunately, homebrew is particular about how you name your repo, so it can't live in the funnel repo.

brew tap ohsu-comp-bio/formula
brew install funnel

buchanae commented 6 years ago

Latest version is slightly more streamlined:

Update all issues and merged PR to have the milestone being released
Write release notes
- Are there backwards incompatible changes to the database schema? to the library API? command line? config?
- be sure to highlight breaking changes.
- be sure to follow the existing pattern of including links to the milestone and a comparison of commits between the released tag and the previous tag.
Create a draft release in github. Include the release notes from above.
Set VERSION in Makefile
Edit website content to include download links and release notes
Run make website to build the website content.
Make PR including change from steps above.
Do a test of make build-release, run funnel version on each release artifact (mac, linux, docker)
Merge the PR. This will update the website's download links, so you must finish the steps below soon.
Be on master branch. git pull to get the commits from the PR merged from above.
Run make build-release. Upload tarballs from ./build/release to the github draft release.
Publish the draft release.
Run docker push ohsucompbio/funnel:$version to publish the docker container
Edit https://github.com/ohsu-comp-bio/homebrew-formula/blob/master/Formula/funnel.rb to update the homebrew formula

buchanae commented 6 years ago

Here's a cool idea: https://github.com/buchanae/funnel/blob/release-notes-builder/util/release-notes/build.go

It's pretty easy to access git commit logs and github commit + PR/issue data. We could use that to generate our release notes from the commits and PRs in the log since the last release tag.

buchanae commented 6 years ago

With #504 this inches towards more simplicity. The new process is:

Update the website's download links to point to the new version.
- commit and merge those updates.
Run git tag x.y.z (this is how goreleaser finds the version. don't bother pushing the tag)
Run make release. This will create a draft release in github.
- release notes are generated automatically.
- artifacts are uploaded automatically.
- we've dropped the milestone tracking to make releases easier.
- this will push the docker images to docker hub. possibly we want to disable this.
You can check the built funnel version with ./build/releases/darwin_amd64/funnel version
updating the homebrew formula is still manual, but goreleaser has some support for this.

buchanae commented 6 years ago

https://github.com/ohsu-comp-bio/funnel/commit/04eefda1bfd3367f3928aeaf5b698e38050f32d9 adds some docs about the latest release process

I still wish this was easier. In particular, it's still possible to mess something up in between updating the website, committing to master, creating a tag, building a release, etc.

Some ideas:

Don't bother putting a version in the website or linking directly to download files, just link to the "latest" github release via https://github.com/ohsu-comp-bio/funnel/releases/latest .
- OR, use javascript to build find the latest release download link via the Github API, e.g. https://stackoverflow.com/questions/28236859/download-link-for-latest-release-of-github-project
- either of these would remove the step of modifying the website, committing to master, and pushing changes to the repo. No code changes would be necessary.
Submodule the homebrew formulas repo into funnel, and add a step which copies over the updated formula, commits, and pushes the changes to github.
Ask goreleaser to allow the git tag requirement to be disabled, which would remove an awkward step in the release workflow.

If we can figure out those steps, I think we'll finally arrive at a one-step release.