Hidden gems: suspenders

Have you seen our suspenders? It is a Rails app generator that includes a set of Ruby gems and common code that we use on every project.

Install it

gem install suspenders

This will install gems with C code, which means you need your OS set up for that. On Debian you need rubygems and build-essential; on OS X you can use the laptop script.

Suspenders will also install capybara-webkit by default. Read the instructions for setting up your OS for it, or use the --webkit false option with the following command.

Create a Rails app

suspenders demo

This makes a demo app. See the difference between it and a bare Rails app.

Gems

The gems are a mix of production libraries like newrelic, development libraries like foreman, and testing libraries like timecop. The full list often changes, so see templates/Gemfile_additions for the exact list.

We selected these gems because we use them on most apps, they have tests, and they are maintained. Some of them are ours but most are from others in the community.

Common code

Suspenders includes a Guardfile, flash and Javascript partials, configuration for Heroku, Factory Girl, Bourbon, Postgres, and more:

• An email address validator so you can do validates :login, email: true
• A list of HTTP and SMTP exceptions that we have gathered through trial and error.

• Prefilled form inputs using JavaScript for a nice user experience:

  <input type="text" class="prefilled" title="Email" name="user[email]" />

Even better Suspenders

Create Heroku staging and production apps with the --heroku option:

suspenders demo --heroku true

Create a Github project with the --github option:

suspenders demo --github organization/project

Use a different authentication library or no auth at all with the --clearance option:

suspenders demo --clearance false

Opt out of the capybara-webkit dependencies with the --webkit option:

suspenders demo --webkit false

Or, combine options:

 suspenders demo --heroku true --github organization/project --webkit false

That was easy

Suspenders should make your life easier. Reduce the tedious decisions, add the one-liners you wish you had, and set up the infrastructure common to every codebase.

Use suspenders for your next Rails app!

8 (new) steps for fixing other people’s code

Way back in mid-2007, when Rails 1.2 was the new hotness and GitHub was still a year away from crawling out of the primordial internet soup, prolific open source contributor Dr Nic wrote an article titled “8 steps for fixing other people’s code”. It offers excellent general advice, but the workflow details are clearly a product of their time: RubyForge, SVN, and .patch files feature heavily.

Here in the fantastical future world of 2012, while we still don’t have hoverboards or household nuclear fusion, we do have some great tools that make fixing other people’s code a lot easier. Join me as we rewrite “8 steps” for the modern age!

1. Get annoyed by a bug or missing feature

Open source projects are usually far from perfect. In many cases they started as something the author threw together to solve a problem, then released into the wild just in case it could be useful to someone else. Open source contributions come from regular people — just like you! — who start using the project and run into a bug that annoys them, or get an idea for a feature that would make their life easier.

The experience that prompted me to write this post started with finding a bug in Chronic, a date-parsing library. The issue is described in the pull request I submitted to fix it (pull requests are the final step in this process; we’ll get to them in a bit).

2. Locate the repository and read up

In recent years git and GitHub have emerged as the de facto standard, if not for open source projects in general, then at least for open source Ruby projects. Lucky you! In Dr Nic’s time it was all SVN, uphill both ways.

If your target project has a web site, it will probably link to the official GitHub repository. Failing that, you can search GitHub for the name of the project. This may also turn up other people’s forks of the project — if you’re not sure which one is the original, just pick one and follow the “forked from” links.

Once you’ve found the repository, scroll down to the README and scan it for “How to Contribute” directions. Some projects have a particular process they want contributors to follow, and it might be different from the steps outlined here. Chronic’s instructions are typical and straightforward.

3. Fork the repository

Forking a project creates your own personal copy of the repository that you’re free to modify however you want. It’s integral to the GitHub workflow, and is therefore stupidly easy: Just hit the Fork button.

Copy the Read+Write link from your newly-forked repo and clone it down:

$ git clone git@github.com:grantovich/chronic.git
Cloning into 'chronic'...

Then copy the Read-Only link from the original repository (mojombo/chronic in my case) and add it as a “remote” like so:

$ cd chronic
$ git remote add upstream git://github.com/mojombo/chronic.git

4. Run the tests

Many projects use automated tests to ensure that bugs stay fixed and new features don’t introduce new bugs. Running a project’s tests is also a useful sanity check, since no tests should fail on an unmodified clone of the master branch.

Before doing this, you’ll need to install the project’s dependencies — if it has any, it should include a Gemfile. Use gem install bundler to install Bundler if you haven’t already, then simply bundle install.

In most Ruby projects, running “rake” with no arguments will execute the full test suite. Ensure this doesn’t give you any failures before proceeding.

5. Make your changes

Come up with a short, descriptive name for a branch that will contain your changes. Here’s my Chronic branch:

$ git checkout -b handle-sm-sd-with-time

Now you’re ready to start coding! Assuming the project has tests, you can do some TDD and start by writing a failing test. Poke around the existing test suite — it likely involves Minitest or Rspec — then write one or more new tests that would succeed if your feature existed or your bug was fixed.

Re-run the test suite to ensure your tests fail (and you didn’t somehow break any other tests). Then, write the code to make them pass! Follow the style of the existing code as much as possible, and resist the temptation to “clean up” or reformat things that aren’t relevant to your change.

Many libraries have Rake tasks applicable to this step. rake console is a common task that opens an IRB shell with your in-development copy of the library loaded into it. If the library is made available as a gem, there will be a task that builds the gem (e.g. rake build), and you’ll want to make sure this still works after you change things.

Note that while the changes I made to Chronic were in multiple commits, you should really put both the tests and the code that passes them into a single commit. Any given commit should pass all the tests that exist within it. You can still make multiple commits locally — just squash them later using git rebase -i origin/master.

6. Document your changes

If you’ve added a new feature or changed how something works, and the project’s documentation lives in the repository (this is usually true for at least the README file), update it to be consistent with your changes. Documentation never gets enough love, and the owner will probably appreciate your thoughtfulness.

7. Get up-to-date

Pull down any changes made to the original repository since you started working, and replay your commits onto the updated code. This ensures that your changes can still be successfully applied to the latest version. It sounds complicated, but the commands are quite simple:

$ git fetch upstream
$ git rebase upstream/master

8. Submit a pull request

Here’s the other half of the fork-based GitHub workflow. After making changes in your fork, you request that the original author pull those changes into their repository.

First push the branch containing your commits up to GitHub…

$ git push -u

…then hit the Pull Request button on your forked repository.

Set the “head branch” on the right side of the pull request to your new branch.

You’ll be prompted to give your pull request a title (e.g. “Add support for XYZ”) and detailed description. Fill these in, and hit the Send pull request button!

Now comes the hardest part: Waiting. The owners of the repository will be notified of your pull request, and at some point — hopefully — will get around to reviewing it. They might suggest some changes: Make them in your branch and git push, and the pull request will automatically update with your new commits. If your changes look good, they’ll be officially merged into the project. Success!

Final thoughts

After you’ve done this once for a given project, the process is simplified: When you’re ready to contribute again, git pull upstream master so you’re working with the latest code, and start again from step 4.

While the GitHub web interface is more accessible if you’re not used to the workflow yet, it’s actually possible to do all this without leaving your terminal. Check out the hub tool, and more specifically the commands dealing with forks and pull requests. In fact, my Chronic pull request was originally a bug report that I later “converted” using hub.

Remember these steps are more like guidelines than actual rules. Every project is different, and the owners of the one you’re working on might prefer you do things a bit (or a lot) differently. Be receptive to the feedback you get on your pull requests, even if it seems nitpicky. You’ll be hailed as a model open source citizen in no time!

Hidden gems: paul_revere

There are times when you must proclaim from the rooftops, for all to hear, that your Web site has something to say! “Hear ye! Hear ye! The Swedish are coming!”, just like Paul Reveresson said.

Thus we have the paul_revere gem.

Install it

To start, toss the gem in your Gemfile:

gem 'paul_revere'

There is an included generator, so be sure to run it:

rails g paul_revere

This will generate a migration to add an annoucements table, so run that:

rake db:migrate

Users of older versions of Rails will see a generated JavaScript file too.

We’re almost there. Next up modify your layout to have a place for announcements. In app/views/layouts/application.html.erb:

<%= render 'announcements/announcement_for_all' %>

And finally add the JavaScript to the asset pipeline. In app/assets/javascripts/application.js:

//= require announcements

Whew! A simple process that will only become easier with improvements to Rails.

Use it

% rails c
> Announcement.create!(body: "I'm as mad as hell and that's OK!")

That was easy

As you just saw, using it is straightforward. This builds on an old RailsCast dealing with this topic. With these pieces you can build more complex tools into your app: an admin section that can make announcements, a dashboard where users can see prior announcements, a record of how many announcements you make per month, and so on.

Don’t re-invent the wheel; use the paul_revere gem today!

Hidden gems: fake_braintree

The fake_braintree gem makes your life easier when testing code that charges credit cards. It is a fake Braintree server that can be manipulated as you see fit.

Start by installing fake_braintree. In your Gemfile:

gem 'braintree'

group :test do
  gem 'fake_braintree'
end

And in your spec/spec_helper.rb:

require 'fake_braintree'

RSpec.configure do |config|
  config.before do
    FakeBraintree.clear!
  end
end

That RSpec configuration clears the fake data between test runs.

Now we can write a quick spec for Purchase#transact:

require 'spec_helper'

describe Purchase do
  it 'charges successfully' do
    transact.should be_true
  end

  it 'fails when the card is declined' do
    FakeBraintree.decline_all_cards!
    expect { transact }.to raise_error
  end

  def transact
    Purchase.new.transact
  end
end

You can see fake_braintree peeking through there in the second spec, where we decline all credit card transactions. Since we clear fake data between test runs, this does not affect other tests.

We can make this pass as normal:

class Purchase
  def transact
    result = Braintree::Transaction.sale(
      amount: '1000.00',
      credit_card:  {
        number: '5105105105105100',
        expiration_date: '05/12'
      }
    )

    result.success? or raise result.errors.inspect
  end
end

That was easy

The fake_braintree gem is basically invisible until you need it. The Braintree implementation code is unchanged, and the success paths are the default.

You can set fake_braintree to verify or outright decline credit cards (as above), and you can also generate transactions as if the user really did buy something.

So stop being so hands-on with your credit card mocking and stubbing and give fake_braintree a try today!