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 withGem::PackageTask
-
publish
-built
,gem push
-
buildar
- config check
Aux
-
pre_build
- invoketest
andbump:build
conditionally -
built
- invokebuild
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 fromENV['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
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:
Lines 12 to 15 in 04ee729