doc/releasing.textile

---
layout: default
title: Releasing
---

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@.

{% highlight ruby %}
THIS_VERSION = "1.0.0-SNAPSHOT"

define 'killer-app' do

  project.version = THIS_VERSION

  # ...
end
{% endhighlight %}


h2(#default). 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:

{% highlight ruby %}
THIS_VERSION = "1.0.1-SNAPSHOT"

define 'killer-app' do

  project.version = THIS_VERSION

  # ...
end
{% endhighlight %}

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

{% highlight sh %}
~/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
{% endhighlight %}


h2(#custom_version). 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@.

h3(#next_version_proc). 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.

{% highlight ruby %}
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
{% endhighlight %}


h3(#next_version_envvar). 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:

{% highlight sh %}
$ 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
{% endhighlight %}

Those commands will generate the Buildfile below:

{% highlight ruby %}
THIS_VERSION = "1.0.0-rc1"

define 'killer-app' do

  project.version = THIS_VERSION

  # ...
end
{% endhighlight %}

The environment variable @NEXT_VERSION@ has precedence over Release.next_version.

h3(#alternate_version_file). 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:
{% highlight ruby %}
THIS_VERSION = "1.0.0-rc1"
{% endhighlight %}

Your Buildfile should import version.rb like so:
{% highlight ruby %}
require File.join(File.dirname(__FILE__), 'version.rb')
{% endhighlight %}

h2(#custom_tag_and_msg). 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@.