This Week in Open Source

High Voltage

High Voltage is a Rails engine for static pages.

You can now use it with Rails 4 thanks to Arvid Andersson (arvida) in 176895f.

Capybara Webkit

Capybara Webkit is a Capybara driver for headless WebKit so you can test Javascript web apps.

You can expect fewer bugs in it thanks to Matthew Horan (mhoran) in 7289a8e and f20d32d.

You can use it with Qt 4.8 thanks to Matthew and Joe Ferris (jferris) in 67b8a33, cbb58d0, f95e4eb, ecfa783, e9a4b77, and e531c1a, and cae5119.

You can expect nodes hidden with css rule visibility: hidden to correctly return false on visible? thanks to Timur Vafin (timurvafin) in 3bab97d.

Dotfiles

Dotfiles are a set of Vim, zsh, git, and tmux configuration files.

You can now tab complete in Vim even faster thanks to Dan Croak in c7efed4.

You can do some awesome git things in Vim thanks to fugitive.vim in d836af8:

• :Gblame for interactive vertical split with git blame output.
• :Ggrep to search the work tree (or any arbitrary commit) with git grep.
• :Glog to load all previous revisions of a file into the quickfix list so you can iterate over them and watch the file evolve.
• :Gbrowse to open the current file on GitHub, with optional line range (try it in visual mode) .

You can safely ignore certain files in git repositories machine-wide thanks to Dan in 0060e0a.

You also now have a clear strategy for managing files with personal information like ~/.gitconfig in a shared dotfiles repo thanks to Joe and Dan in 52b2ee1.

Bourbon

Bourbon is a lightweight mixin library for Sass.

You can now optionally use Rails’ asset pipeline in the font-face mixin thanks to Phil LaPier (plapier) in f93cf9e.

Suspenders

Suspenders is a CLI for creating Rails apps with thoughtbot defaults.

When you use Suspenders-generated Rails apps, you’ll now automatically track your slowest-running specs thanks to Dan Croak (croaky) in 69c7fdd.

You will also automatically track your test coverage thanks to Joe Ferris (jferris) in 2787281 44c51c1.

The validity of your factories will always be tested first thanks to Dan in 52444eb.

Your Ruby version will be determined by your Gemfile thanks to Dan in 389ceda.

You will bundle using binstubs and the 37signals’ bin/stubs directory convention thanks to Dan in 4b7e40a.

You can format time through localization thanks to Dan in fbf3fcd.

Your Postgres database will automatically be configured to encode using UTF-8 thanks to Yi-Ting Cheng (xdite) in c2c46a7.

You can use these new features in Suspenders version 1.1.5.

Factory Girl

Factory Girl is a library for setting up Ruby objects as test data.

You can now use a block with build_list and create_list so you can call methods on each instance of the array thanks to bbugh in 488e42d.

Bourne

Bourne adds test spies to mocha.

You can now see the master Travis CI build thanks to Harlow Ward (harlow) in 74dd8f4.

Paul Revere

Paul Revere is a library for “one off” announcements in Rails apps.

Support for Rails 2 apps will be dropped in Paul Revere versions greater than 1.1 thanks to Gabe Berke-Williams (gabebw) in e8ae883.

This week in open source

laptop

I was reminded that I’ve been missing out on our sweet laptop script, which is a program we maintain to get a Rails environment set up on OS X as quickly as possible. So over the past week, Antonio Salazar Cardozo (Shadowfiend) fixed our capitalization of Qt (b667280), Prem Sichanugrist (sikachu) fixed our capitalization of JavaScript (87fe88f), and Dan Croak (croaky) removed the deprecated Heroku Labs plugin (842cd0d) and gave instructions on installing the command-line XCode tools (a177cca).

suspenders

The suspenders gem, which has helped many people start a Rails app, now shows that the build is broken. Gabe Berke-Williams (gabebw) added that (76e42eb).

shoulda-matchers

The shoulda-matchers gem is a collection of RSpec matchers for various Rails things. Gabe Berke-Williams (gabebw) went to town on it this week, cleaning everything up in an effort to make it more pleasant to hack on (2b98e49, 09544fa, 7b3d6d0, 96df0b1, 36006d8, 4ff1344, 3b3181b, 4574f51, 1c517d2, bd52483, e70e1bf, 41bccc8). Having done that, he added a :primary option to the have_db_column matcher (68e65b2). Matthew Daubert (MDaubs) fixed a JRuby failure and also added support for Rails 3.0 (d85503f).

bourne

Due to my complaining last week, the bourne gem now has a NEWS file (8dfb077), thanks to Gabe Berke-Williams (gabebw).

paperclip

So we have this gem named paperclip. You might have heard of it. This week, Tony Brewerio (tony-brewerio) fixed the :content_type validator (c4c22f8).

Prem Sichanugrist (sikachu) released version 3.0.1, which breaks backward compatibility (d61ddd5, 51bb0f9, 7088f5b, e1951ed, 9ea4a9b, 36d1289, 8390516, b3f9690, 8e80310, ee4107a, b3a63ed, 8a758c2, 84d2d08, fe706c6, b54904e, d3a7427, da5d716, ee42b19, e83f88f, 03f777f, 5232b19, 19aedbc).

Jon Yurek (jyurek) merged in something he has been working on: adapters for different types of I/O (6c5fe19, e10edcd, f4b6d48, 78cfebd, 89c8d11). Adding new file-like things is now easier, including URLs that act like files. Yeah, that’s right.

Jon is so going to write a blog post about this with more explanations, after he updates the README.

factory_girl

A bunch of fun commits to factory_girl this week. Chris Griego (cgriego) used pull requests as a forum to promote his ActiveAttr gem (81c9f2c and 4e2a672). Joshua Clayton (joshuaclayton) added a before_create callback (24d417d).

Vasiliy Ermolovich (nashby) used ActiveSupport for deprecation warnings (bca13f1 and 28e3c25) and also made use of the singleton_class method in Ruby 1.9 (08d01c1).

Mike Subelsky (subelsky) fixed a typo in the docs around the name FactoryGirl::Syntax::Methods (266b1d6), Dan Croak (croaky) mentioned the supported Ruby versions in the README (bed50ec), Josh renamed Changelog to NEWS because that’s exactly what it is (4f5b775) and also renamed *rb files to *erb to handle yardoc better (a6ccbcb).

capybara-webkit

I totally dropped the ball on releasing a new version of capybara-webkit this week. Sorry about that! Joe Ferris (jferris), however, refactored some of the C++, which is very welcome (c2a2bd0 and 4531f65).

appraisal

Some news in our appraisal gem this week: Gabe Berke-Williams (gabebw) added a contribution guideline (fd05fdf), then osheroff fixed appraisal to handle weird filenames (1d4fa93, b21220a, and 75a4970).

Appraisal: find out what your gems are worth

Since the introduction of bundler to the Ruby community, dealing with dependencies has gotten much easier. Almost every library now has a Gemfile that looks like this:

source "http://rubygems.org"
gemspec

This pulls runtime and development dependencies from your project’s gemspec and finds versions that can all agree with each other. Requiring any of your dependencies will always get the expected version regardless of order, and updating dependencies can be performed with a single command.

However, there’s still one piece missing from this puzzle: how do you make sure that your library works with all supported versions of your dependencies? A common example is Rails: now that Rails 3.1 is out, how can you make sure that your library works with both Rails 3.0.x and Rails 3.1.x?

One side effect of using bundler is that all dependencies are “locked.” This essentially means that, whether you’re running your tests on your home computer, work computer, or continuous integration server, your dependencies are always the same exact versions. This obviously means that you’ll only ever test against one version of Rails; Yehuda Katz, one of the authors of bundler, has a partial answer to this problem:

“When developing a gem, use the gemspec method in your Gemfile to avoid duplication. In general, a gem’s Gemfile should contain the Rubygems source and a single gemspec line. Do not check your Gemfile.lock into version control, since it enforces precision that does not exist in the gem command, which is used to install gems in practice. Even if the precision could be enforced, you wouldn’t want it, since it would prevent people from using your library with versions of its dependencies that are different from the ones you used to develop the gem.”

Unfortunately, there are some holes in this practice.

For one, this means that tests that pass on one machine may not pass on another, even if the library code hasn’t changed at all. This can be frustrating, as it breaks the general expectation that a fresh checkout of any master branch should have passing tests.

For another, this doesn’t reliably exercise your library across versions of your dependencies; rather, it hopes that you happen to run the tests on enough varied environments between each release that you happen to catch any regressions.

If locking your dependencies hides errors, and not locking your dependencies creates them, how can you reliably run your tests on different versions of your dependencies without creating an unstable development environment? The answer is appraisal.

Appraisal runs your tests across configurable, reproducible scenarios that describe variations in dependencies. As an example, if you need to test compatibility with several versions of Rails, you can use an Appraisals file like this:

appraise "3.0" do
  gem "rails", "~> 3.0.11"
end

appraise "3.1" do
  gem "rails", "~> 3.1.1"
end

You can include as many appraise blocks as you want, and you can be as specific or loose with requirements as you like. Running rake appraisal:install will generate separate bundler-compatible Gemfiles for each scenario, combining the base requirements from your main Gemfile with the changes in each scenario. You can run any rake task across every scenario using the “appraisal” task:

# Run your specs on Rails 3.0 and 3.1
rake appraisal spec

When using Appraisal, we recommend that you check your Gemfile.lock into version control, as well as the gemfiles directory generated by Appraisal. This will ensure that your tests are always green when you check out a fresh copy. It also allows you to create reproducible regression tests for version-specific bugs.

We’ve successfully used Appraisal on numerous projects this year. If you’d like to see real world examples, read the Appraisals files for Clearance, Factory Girl, Capybara Webkit, Copycopter Client, and Paperclip.

Do you have a gem that supports multiple version of Rails or any other library? Find out what your gem is worth: install appraisal.