Releasing

What does a release do?
How to specify my own version number scheme?
How to specify my own tag name and commit message?

Now that we built and tested our awesome software, let’s tell the world and release it.

Each buildfile can specify the current version with a constant named VERSION_NUMBER or THIS_VERSION.

THIS_VERSION = "1.0.0-SNAPSHOT"

define 'killer-app' do

  project.version = THIS_VERSION

  # ...
end

What does a release do?

The default behavior of the Release task is the following:

Check that the version to be released and the next version are different
Check that the project is being tracked by Git or Subversion
Package, test and deploy the artifacts using THIS_VERSION value minus the -SNAPSHOT suffix (if any)
Tag the repository with the released version number
Update the value of THIS_VERSION in the buildfile with the next version number

Buildr will increment the last digit of the 3-digit versioni number if THIS_VERSION ends with -SNAPSHOT.
So, at the end of a release, the buildfile now looks like this:

THIS_VERSION = "1.0.1-SNAPSHOT"

define 'killer-app' do

  project.version = THIS_VERSION

  # ...
end

And the Git repository now contains two new commits and a new tag.

~/w/killer-app[master]$git ol -4
c1af3d5  (HEAD, origin/master, master) Changed version number to 1.0.1-SNAPSHOT
dd35015  (tag: 1.0.0) Changed version number to 1.0.0
76c96e7  Last fix before the release

How to specify my own version number scheme?

If THIS_VERSION does not contain -SNAPSHOT, Buildr delegates the resolution of the next version number to the user which has 2 differents ways to express her wishes: Release.next_version or the environment variable NEXT_VERSION.

Using Release.next_version

The Release class can receive the next version of the buildfile. This could be a string or a proc that would receive the current version and return the next version.

THIS_VERSION = "1.0.0-SNAPSHOT"

# a string
Release.next_version = "2.0.0-SNAPSHOT"

# or a proc - equivalent result
Release.next_version = lambda do |this_version| # 2.0.0-SNAPSHOT
    new_version = THIS_VERSION.split /\./
    new_version[0] = new_version[0].to_i + 1
    new_version[1] = 0
    new_version[2] = '0-SNAPSHOT'
    new_version.join '.'
end

define 'killer-app' do

  project.version = THIS_VERSION

  # ...
end

Using the environment variable NEXT_VERSION

If the environment variable NEXT_VERSION is set, Buildr will use this value to update THIS_VERSION at the end of the release.

For conveniency, this variable is case insensitive.

So, all 3 following commands will run a release with a custom new version:

$ buildr release next_version="1.0.0-rc1"
$ env next_version="1.0.0-rc1" buildr release
$ env NEXT_VERSION="1.0.0-rc1" buildr release

Those commands will generate the Buildfile below:

THIS_VERSION = "1.0.0-rc1"

define 'killer-app' do

  project.version = THIS_VERSION

  # ...
end

The environment variable NEXT_VERSION has precedence over Release.next_version.

Using an alternate version file

To avoid dealing with conflicts over the Buildfile, you can store the version inside version.rb next to it.

version.rb:

THIS_VERSION = "1.0.0-rc1"

Your Buildfile should import version.rb like so:

require File.join(File.dirname(__FILE__), 'version.rb')

How to specify my own tag name and commit message?

As explained earlier, Buildr will create two new commits and a new tag in the version control system. Similarly to Release.next_version, the commit message and the tag name can be customized with Release.message and Release.tag_name. Both could be strings or procs that would receive the released version THIS_VERSION without -SNAPSHOT.