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
.