cannam@133: How to release
cannam@133: ==============
cannam@133: 
cannam@133: * First, develop some new features to release!  As you do, make sure to keep the documentation
cannam@133:   up-to-date.
cannam@133: 
cannam@133: * Run `super-test.sh` on as many platforms as you have available.  Remember that you can easily run
cannam@133:   on any machine available through ssh using `./super-test.sh remote [hostname]`.  Also run in
cannam@133:   Clang mode.  (If you are Kenton and running from Kenton's home machine and network, use
cannam@133:   `./super-test.sh kenton` to run on all supported compilers and platforms.)
cannam@133: 
cannam@133: * Write a blog post discussing what is new, placing it in doc/_posts.
cannam@133: 
cannam@133: * Run jekyll locally and review the blog post and docs.
cannam@133: 
cannam@133: * Check out the master branch in a fresh directory.  Do NOT use your regular repo, as the release
cannam@133:   script commits changes and if anything goes wrong you'll probably want to trash the whole thing
cannam@133:   without pushing.  DO NOT git clone the repo from an existing local repo -- check it out directly
cannam@133:   from github.  Otherwise, when it pushes its changes back, they'll only be pushed back to your
cannam@133:   local repo.
cannam@133: 
cannam@133: * Run `./release.sh candidate`.  This creates a new release branch, updates the version number to
cannam@133:   `-rc1`, builds release tarballs, copies them to the current directory, then switches back to the
cannam@133:   master branch and bumps the version number there.  After asking for final confirmation, it will
cannam@133:   upload the tarball to S3 and push all changes back to github.
cannam@133: 
cannam@133: * Install your release candidates on your local machine, as if you were a user.
cannam@133: 
cannam@133: * Go to `c++/samples` in the git repo and run `./test.sh`.  It will try to build against your
cannam@133:   installed copy.
cannam@133: 
cannam@133: * Post the release candidates somewhere public and then send links to the mailing list for people
cannam@133:   to test.  Wait a bit for bug reports.
cannam@133: 
cannam@133: * If there are any problems, fix them in master and start a new release candidate by running
cannam@133:   `./release.sh candidate <commit>...` from the release branch.  This will cherry-pick the specified
cannam@133:   commits into the release branch and create a new candidate.  Repeat until all problems are fixed.
cannam@133:   Be sure that any such fixes include tests or process changes so that they don't happen again.
cannam@133: 
cannam@133: * You should now be ready for an official release.  Run `./release.sh final`.  This will remove the
cannam@133:   "-rcN" suffix from the version number, update the version number shown on the downloads page,
cannam@133:   build the final release package, and -- after final confirmation -- upload the binary, push
cannam@133:   changes to git, and publish the new documentation.
cannam@133: 
cannam@133: * Submit the newly-published blog post to news sites and social media as you see fit.
cannam@133: 
cannam@133: * If problems are discovered in the release, fix them in master and run
cannam@133:   `./release.sh candidate <commit>...` in the release branch to start a new micro release.  The
cannam@133:   script automatically sees that the current branch's version no longer contains `-rc`, so it starts
cannam@133:   a new branch.  Repeat the rest of the process above.  If you decide to write a blog post (not
cannam@133:   always necessary), do it in the master branch and cherry-pick it.