Server Release Procedure

This is the procedure to follow when managing a Buendia server release.

Version numbering

Note the project's package version numbering conventions.

Prerequisites

First make sure you have the git flow extension installed. On a Mac, brew install git-flow, or on Linux, apt-get install git-flow.

In your working repository, set up git flow like this:

  git checkout master
  git flow init

You'll be asked a few questions. You only need to type "dev" for next release development and "v" for the version tag prefix. Hit Enter to get the default for everything else:

  Branch name for production releases: [master]
  Branch name for "next release" development: [master] dev   # <-- type "dev"
  How to name your supporting branch prefixes?
  Feature branches? [feature/] # <-- type YOUR username here followed by "/", so we know whose branch it is
  Release branches? [release/]
  Hotfix branches? [hotfix/]
  Support branches? [support/]
  Version tag prefix? [] v  # <-- type "v"

Starting a release branch

(Note that in order to do a release, there must be at least one new commit on dev since the last release. In practice, this should always be the case. If for some reason it isn't, commit a trivial change to dev like adding a blank line to README.md, and then proceed.)

When it's time to freeze new feature development, start a release branch for work focused on stability and bugfixes:

  git checkout dev  # switch to the dev branch
  git pull  # bring local dev up to date with origin/dev
  git flow release start N.N.N  # start a release
  git flow release publish N.N.N  # make the release branch available to others

Replace N.N.N with the release number. Release numbers generally consist of two or three numbers, joined with periods (digits only, no letters).

After this point, new feature development continues on the dev branch, and only bugfixes should be committed to the release branch.

Choosing a release message

Compose a one-line description of the most important change or improvement in this release. Most releases should have one main purpose. The message should be a complete sentence that states what the release accomplishes, for example:

Release N.N.N brings about world peace.

For examples of good release messages, you can see all the previous messages with git tag -n1.

You'll use this message when it's time to finish the release.

Finishing the release

When you are sufficiently satisfied with the stability and quality of the tip of the release branch and everything has been thoroughly tested, it's time to finish the release with this command:

  git checkout master           # make sure you have the latest origin/master
  git pull
  git flow release finish N.N.N

This will merge the release branch to both master and dev and tag the commit on master.

You'll be asked to enter two commit messages in order: First, a merge message; secondly, a tag description. For both of these, enter the release message you composed.

Finally, use these commands to publish the new release on GitHub:

  git push --tags origin master
  git push origin dev            # ensure that any changes backported to dev get pushed

CircleCI will detect that a new tag has been applied to the master branch, and kick off the construction of newly versioned packages, and then include them in the project apt repository.