Yesterday I was at an open house for Code for America as the organization prepared to send off teams to help ten municipalities improve government services. It’s a great organization with an admirable mission and I was reminded how our skills as coders give us tools to make an impact on so many ordinary lives. The Code for America Fellows are all doing a service year so they can write apps that help citizens report potholes, monitor the status of neglected homes in blighted areas, and streamline the process of opening new businesses.

Something similar, improving the ordinary lives of Rails developers, was on my mind as I connected with several Rails developers, including some I met at the SF Rails Girls workshop last weekend. You see, I’d spent most of the afternoon tracking down an issue with FactoryGirl that had resulted in a storm of GitHub issues for the RailsApps example applications that I maintain. Four days ago, the FactoryGirl maintainers released factory_girl_rails version 4.2.0 and suddenly every application was broken immediately after being generated by the Rails Composer tool.

The error reports showed that the problem was related to FactoryGirl and I knew that the new version of FactoryGirl had just been released. I saw that several new and inexperienced Rails developers had tried to build applications using the RailsApps examples and were overwhelmed and frustrated, not sure why things were broken and unsure how to proceed. One of my most helpful volunteer contributors stepped up and tried to help but there was nothing in the FactoryGirl changelog or recent commits that offered any clues. It took me a few hours of hunting to determine that factory_girl_rails default behavior when used with RSpec had changed from version 4.1.0 to 4.2.0. See the issue; I don’t know whether the change was intentional or just an oversight. I’m now in the process of updating all the example applications and accompanying tutorials to accommodate the change.

If you work with Rails every day you’re used to dealing with similar situations. We get used to it. Less than two weeks ago I faced a similar issue. Devise version 2.2.0 changed a default password length. All the example applications broke because the example passwords in database initialization files and tests were too short. I spent a day updating example applications and accompanying tutorials to use longer passwords to accommodate the new Devise default. There are (usually) good reasons that our favorite gems change. As experienced Rails developers, we just deal with it. It goes with the territory. It’s not so easy for inexperienced developers, hobbyists and people who only work with Rails part-time or occasionally (I’m thinking particularly of the attendees at last weekend’s SF Rails Girls workshop).

Stand back if you are allergic to rhetorical figures because here comes the metaphor from the title of this post. We’re dealing with Rails potholes every day. Inevitably there will be potholes when every day we run the big trucks down Main Street. We get used to potholes and drive around them when we commute to work every day. It’s the out-of-towners who notice all the potholes on their first visit and see the blight we barely notice.

Appropriately, that was the topic of a conversation at the Code for America open house. I’d just met Moncef Belyamani, a Rails developer (and now a 2013 Code for America Fellow) who is an enthusiastic supporter of the RailsApps project. I was telling him that I had just launched the RailsApps Tutorials membership site to support the project but I was doubtful that people would see the benefit of spending $19/month to support the project by paying for access to periodically updated tutorials. He happily convinced me that I was underestimating the value of the project. The project is not fundamentally about delivering tutorials (though they are important). What is more important is the work that goes into keeping the example applications up to date. The real value for the community, both full-time developers and part-timers, is the availability of a reference implementation that uses the gems we use most often.

Steve Klabnik recently pointed out that “Rails has Two Default Stacks”. Chances are, if you are building a Rails application, you are going to be using ERB or Haml, MiniTest or RSpec, perhaps Cucumber, Twitter Bootstrap, likely Devise and maybe CanCan. Wouldn’t it be nice to know they all worked together? They do, on most days. And on the days they don’t, you can check the RailsApps example applications to see if anyone else is having the same problem. And hopefully find that someone worked out a fix if something is broken. Sometimes the problem is a gem in isolation, in which case the gem’s repo is the best place to report a problem. But sometimes, like the combination of factory_girl_rails and RSpec, there’s an integration issue that’s easiest to identify with a reference implementation.

That’s what it takes to fix the Rails potholes. We’ve got an app to report the potholes; it’s called GitHub issues. We’ve got a crew to fill the potholes; it’s the entire community but especially the people who are helping out with the RailsApps project.

And this is where another metaphor is appropriate: Fresh is not just for milk. Ultimately the utility of any reference implementation depends on how fresh it is. A blog post from 2009 can show you how to set up FactoryGirl and RSpec but is it still current? I’m doing all I can to keep the RailsApps example applications up to date. I don’t always hunt down bugs myself (I prefer to accept pull requests!) but as the project maintainer I’ve taken on the responsibility to keep the applications current.

That’s where the RailsApps Tutorials come in. Developers won’t pay to maintain an up-to-date reference implementation they find on GitHub (it is open source). But people will pay for comprehensive and up-to-date tutorials. By keeping the RailsApps Tutorials up to date, which are supported by the $19/month Pro subscription, I’m keeping the example applications up to date. Fresh is not just for milk; tutorials and example applications are valuable when they are fresh.

For more about subscription program, see the post RailsApps Tutorials Launches.