buildar

Buildar

Buildar provides a set of rake tasks to help automate releasing your gem:

• Versioning
• Building / Packaging
• Publishing

With a set of options to integrate with your current project.

Rake tasks

Core

• release - build, publish, tag
• build - prebuild, gem build
• gem_package - pre_build, build with Gem::PackageTask
• publish - built, gem push
• buildar - config check

Aux

• pre_build - invoke test and bump:build conditionally
• built - invoke build conditionally
• install - built, gem install
• install_new - build, gem install
• version - show the current project version

With git integration

• tag - message, git tag current version, git push to origin
• message - capture a message from ENV['message'] or prompt STDIN

With version file integration

• bump:build - increment the 4th version number (1.2.3.4 -> 1.2.3.5)
• bump:patch - increment the 3rd version number (1.2.3.4 -> 1.2.4.0)
• bump:minor - increment the 2nd version number (1.2.3.4 -> 1.3.0.0)
• bump:major - increment the 1st version number (1.2.3.4 -> 2.0.0.0)
• release:patch - bump:patch, release
• release:minor - bump:minor, release
• release:major - bump:major, release

Just show me the tasks

Install

$ gem install buildar     # sudo as necessary

Usage

Edit your Rakefile. Add to the top:

require 'buildar'

Buildar.new do |b|
  b.gemspec_file = 'example.gemspec'
end

That is basically the minimal Rakefile needed for Buildar to operate, assuming you have a valid gemspec file named example.gemspec.

Let's try a Buildar task, release:

$ rake release

gem build example.gemspec
WARNING:  no email specified
Successfully built RubyGem
Name: example
Version: 1.2.3
File: example-1.2.3.gem
mv example-1.2.3.gem pkg/example-2.0.1.1.gem
gem push pkg/example-1.2.3.gem
Pushing gem to https://rubygems.org...
Successfully registered gem: example (1.2.3)

Without a gemspec file

Buildar.new do |b|
  b.gemspec.name = 'example'
  b.gemspec.summary  = 'Example of foo lorem ipsum'
  b.gemspec.author   = 'Buildar'
  b.gemspec.license  = 'MIT'
  b.gemspec.description = 'Foo bar baz quux'
  b.gemspec.files = ['Rakefile']
  b.gemspec.version = '1.2.3'
end

From examples/no_gemspec_file.rb

Dogfood

Here is Buildar's Rakefile:

begin
  require 'buildar'

  Buildar.new do |b|
    b.gemspec_file = 'buildar.gemspec'
    b.version_file = 'VERSION'
    b.use_git      = true
  end

rescue LoadError => e
  warn "buildar failed to load: #{e}"
end

Let's try release:patch, this time with b.version_file and b.use_git:

$ rake release:patch message="added version task; demonstrating Usage"

bumping 2.0.0.9 to 2.0.1.0
git commit VERSION -m "Buildar version:bump_patch to 2.0.1.0"
[master 5df1ff8] Buildar version:bump_patch to 2.0.1.0
1 file changed, 1 insertion(+), 1 deletion(-)
bumping 2.0.1.0 to 2.0.1.1
git commit VERSION -m "Buildar version:bump_build to 2.0.1.1"
[master 73d9bdb] Buildar version:bump_build to 2.0.1.1
1 file changed, 1 insertion(+), 1 deletion(-)
gem build buildar.gemspec
WARNING:  no email specified
Successfully built RubyGem
Name: buildar
Version: 2.0.1.1
File: buildar-2.0.1.1.gem
mv buildar-2.0.1.1.gem pkg/buildar-2.0.1.1.gem
gem push pkg/buildar-2.0.1.1.gem
Pushing gem to https://rubygems.org...
Successfully registered gem: buildar (2.0.1.1)
git tag -a "v2.0.1.1" -m "added version task; demonstrating Usage"
git push origin --tags
To https://github.com/rickhull/buildar.git
* [new tag]         v2.0.1.1 -> v2.0.1.1

Use a VERSION file

• Buildar can manage your version numbers with b.version_file
• The version only matters in the context of a release. For internal development, git SHAs vastly outclass version numbers.
• "The right version number" for the next release is a function of the current release version and the magnitude (or breakiness) of the change
• http://guides.rubygems.org/patterns/#semantic-versioning
• http://semver.org/
• Automate everything

The VERSION file at your project root should look something like

1.2.3.4

Buildar will be able to bump:major, bump:minor, bump:patch, and bump:build. This helps with a repeatable, identifiable builds: build invokes bump:build etc.

Every build bumps the build number. Since the build operates off of your potentially dirty working copy, and not some commit SHA, there is no guarantee that things haven't changed between builds, even if "nothing is supposed to have changed". This guarantees that you can't have 2 builds floating around with the same version number but different contents.

Typically you'll want to let Buildar manage the build number, and you manage the major, minor, and patch numbers with:

• release:major - bump:major
• release:minor - bump:minor
• release:patch - bump:patch

To make your app or lib aware of its version via this file, simply:

# e.g. lib/foo.rb
#################
module Foo
  def self.version
    file = File.expand_path('../../VERSION', __FILE__)
    File.read(file).chomp
  end
end

b.version_file defaults to nil, so if you don't set it, you'll have to keep your gemspec's version attribute updated.

Gemspec file tricks

With

Buildar.new do |b|
  b.gemspec_file = 'example.gemspec'
  b.version_file = 'VERSION'

You'll need to keep your gemspec file in synch with b.version_file. Here's how Buildar does it:

https://github.com/rickhull/buildar/blob/04ee729169bc4f77fc6f68778e565c7fcf914e7d/buildar.gemspec#L12-L15