docrails, back to the roots

A bit of history

docrails is a branch of Ruby on Rails thought for quick doc fixes that gets cross-merged with master regularly, please have a look at What is docrails? for more on docrails.

When Pratik Naik created docrails back in 2008, he offered commit bit to anyone interested (this is the original announcement). Let me express my admiration for this idea. You know, in open source the commit bit is seen as the precious treasure only given to a few, and Pratik goes and puts this upside down to encourage contributions to the documentation. Genius!

And it went even further. GitHub was very kind to flip a private backend flag for docrails that enabled public write access, you didn't even have to ask for commit bit, you could clone and push without asking for permission.

The idea proved to work, trust people and you'll get trust back. Tons of people, including yours truly, have been able to contribute and improve the API and the guides with a workflow that is trivial compared to the friction of pull requests. Is about the same effort for Rails committers, patches have to be equally reviewed, but much less for contributors, which is fantastic.

Back to the roots

GitHub had to change their infrastructure recently and they needed to get rid of that hackish flag (only used by three projects). We are very grateful to them for providing it all this time. Thanks guys!

With the flag out now we are back to the roots. docrails is now owned by the Rails organization and has thus moved from lifo/docrails to rails/docrails. You can either ask for commit bit if you'd like to contribute to docrails regularly (please contact anyone from the core team), or else propose documentation changes to Rails itself via pull requests to rails/rails.

Please, do not open pull requests in docrails, documentation belongs to Rails and is maintained and evolved alongside the source code, the purpose of docrails is precisely to give you a way to bypass pull requests altogether.

The Ruby on Rails API Switches to SDoc

The Ruby on Rails API is switching to SDoc starting with 3.1.

SDoc is a RDoc format created by Володя Колесников (@voloko) that has been powering for a long time.

Among other things, SDoc provides a search box with fuzzy match completion, tree browsing, keyboard navigation, and a really nice template.

You can already see the upgrade in the edge API.

We'd like to thank very much Володя for his work updating SDoc for the official API. Thanks man!

News from the Documentation Front

New Configuration Guide

Rails 3.1 will come with a new comprehensive guide about configuring Rails applications written by Ryan Bigg (@ryanbigg). The current draft is already available in the edge guides.

Rails Documentation Team

The documentation team, which was created some three years ago and consisted of Pratik Naik (@lifo), Mike Gunderloy (@MikeG1), and me, played a key role at bootstrapping docrails. Together with lots of API contributors and guides authors. Kudos to Pratik and Mike, their effort was outstanding and gave a definitive push to this aspect of the project.

After all these years, documentation maintenance happens regularly in master. Because of that, we are no longer going to have a separate documentation team. The same way we do not have a separate testing team. Tests and docs are an integral part of Ruby on Rails and complete patches have or should have proper tests and docs coverage.

Rails Guides Reviewers

Reviewing guides needs a special profile and dedication that has its own standards and pace. There's going to be a team of guides reviewers that will take care of new material. I am very glad to announce that Vijay Dev (@vijay_dev) is going to be the first member of this team. Vijay has done an awesome work in docrails in the last months. Welcome aboard :).

Next Steps

The Rails documentation has improved a lot in the last years, it has more content, and it has better editorial quality. But there's still a lot to do. Here are some ideas to work on:

  • A new documentation generator that evaluates the source tree and introspects to generate the API, mixed with a parser to extract documentation snippets.

  • Methods in the API have a link that toggles the visibility of their source code. Wouldn't it be awesome if there was a toggler that disclosed their tests?

  • Test coverage for the guides.

  • What about a gorgeus template design?

If you'd like to hack on any of them please go ahead!

Rails Has Great Documentation

To this day I still hear people complain that Rails has poor documentation. From where I’m sitting this seems far from the truth. Let me lay out the evidence piece by piece:

To learn Rails from scratch Michael Hartl recently finished his book Ruby on Rails Tutorial: Learn Rails by Example. The book teaches Rails 3 from the ground up and it’s available for FREE online. If you’d rather have a PDF or a book you can grab that as well (and he’s even working on some screencasts).

The source for the finalized book will be pushed to GitHub and released under a Creative Commons License shortly after Rails 3 is done. If you’d like to help translate the book to your language of choice, feel free to contact Michael and he’ll get in touch when it’s time to make it happen.

Rails Guides

If you’re not a Rails newbie don’t forget about the Rails Guides, which have been updated for Rails 3.

Rails API Docs

There are two main websites I use to do API lookups. The first is Rails Searchable API Doc, which has online and offline searchable documentation. The second is APIdock which is online only, but has the ability to comment and easily compare different versions of documentation.

Rails 3 Free Screencasts

If you’re more of a visual learner (like me) then there are plenty of free screencasts to teach you about Rails 3. About 2 months ago I produced the Rails 3 Screencasts, which will get you started.

Ryan Bates has also produced an incredible amount of Rails 3 screencasts over on Ryan has been producing Railscasts for over 3 1/2 years, isn’t that crazy?

There’s also a few good free screencasts over on Teach me to Code by Charles Max Wood.

Keeping on the Edge

If you find yourself wondering how to keep up with all of the newest features / libraries for Rails 3, both the Ruby5 Podcast and the Ruby Show are going strong. Don’t listen to audio? It doesn’t matter, just subscribe to the Ruby5 RSS feed and get links with descriptions to all the newest libraries, tutorials, and more. You might also want to checkout Peter Cooper’s new Ruby Weekly, a Ruby email newsletter.

Need to upgrade a big app to Rails 3?

Jeremy McAnally’s Rails 3 Upgrade Handbook PDF is just $12. There’s also a few paid screencasts for the upgrade over on and BDDCasts.

Need a Book?

There’s a bunch of books that will be coming out after the release, most of which you can start reading now. The Rails 3 Way by Obie Fernandez, Rails 3 In Action by Ryan Bigg and Yehuda Katz, Beginning Rails by Cloves Carneiro Jr and Rida Al Barazi, and of course the Agile Web Development with Rails:fourth edition by Sam Ruby, Dave Thomas, and David Heinemeier Hansson.

In conclusion

No more complaining about lack of good documentation! Seriously. If you want even more Rails 3 content, check out the blog post by Kevin Faustino on 34 Ruby on Rails 3 resources to get you started.

Update on Rails Guides and Documentation

We have been working on the Rails guides for some months now. With substantial contributions from a variety of authors, things are looking even better in the next version of the guides. That makes this the right time to take the overall documentation efforts to the next level.

Announcing the Documentation Team
We’re very happy to announce a formal documentation team – consisting of Xavier Noria, Mike Gunderloy and myself. However, eventually Mike and I will be just acting as advisors to the documentation team. So we’re definitely looking to empower some new faces here. If you’ve been working on improving the documentation and guides, keep up the good work and you’ll be on the team soon enough!

The documentation team will be to responsible for keeping the guides and API documentation up-to-date, working to improve the Rails documentation, and also helping more people contribute to the documentation efforts.

Documentation Mailing List and IRC
As part of the renewed documentation effort, we’re launching a mailing list. So go ahead and subscribe to rubyonrails-docs. The mailing list will be the main point of communication with the documentation team. If you have any suggestions or need any help, please post it to the mailing list. For quick questions, you can also find some of the team in the #docrails room on IRC most hours of the day.

How to Contribute
If you’re new to the Rails documentation process (or want to get involved for the first time!), you might want to have a look at the Contributing to the Rails Documentation section of the Contributing to Rails guide.

Rails Guides Gets a Facelift

There’s a brand new version of Rails coming, as you already know. What better time for a new version of some of the Rails documentation? So the Rails Guides team is pleased to announce a refresh of the Ruby on Rails Guides site, just in time for the Rails 2.3 release.

The most obvious change you’ll see is a new look, thanks to some awesome design work from Jason Zimdars. But the visual refresh isn’t all that’s going on here. We’ve also been working to update the Guides for Rails 2.3, as well as to add new guides to the list.

And there’s good news if you want to get involved too. Behind the scenes, Tore and Pratik switched our markup engine from AsciiDoc to Textile. This makes the Guides easier to write and edit and easier to build into a Rails project. If you’ve got some spare time to help out, join us in the #docrails room on, and help make the Rails Guides into a great resource in time for the 2.3 release.

Introducing Rails Metal

Rails Edge adopted Rack a while back and we’ve been exploring ways to expose that better. The first thing we did was to make it really easy to hook up any piece of Rack middleware in front of a Rails request. In your config/environment.rb file, you can do:

config.middlewares.use(Rack::Cache, :verbose => true)

This will make your application use Ryan Tomayko’s excellent Rack::Cache middleware for better HTTP caching. There are lots of other great generic, reusable Rack middleware pieces. Do go shopping.

But there’s another use case where Rack also comes in handy. If you have a Rails application that has service end points that need to be really, really fast. So fast that the few milliseconds that a trip through the Rails router and Action Controller path is too much.

For this scenario, we’ve built a thin wrapper around the generic Rack middleware and given it a place in the hierarchy along with the name “Metal”. Rails Metal is meant for things like the Campfire poller service, which is doing hundreds of requests per second and needs to be really fast and is at the same time really simple (2 database calls and returning a string). This service is currently written in C, but we’ll look into converting it to Rails Metal instead.

Rails Metal is a subset of Rack middleware
Think of Rails Metal as a subset of middleware intended for application-specific end points that need the extra speed (“write to the metal”, hence the name). Thanks to recent adoption of Rack sessions, these pieces of metal even have access to the same session as Rails. You can either run them as part of the Rails process or run them as individual services through rackup.

We’ve even included a generator for Metal, which by default will create a stub ala:

class Poller def if env[“PATH_INFO”] =~ /^\/poller/ [200, {"Content-Type" => “text/html”}, “Hello, World!”] else [404, {"Content-Type" => “text/html”}, “Not Found”] end end end

As you can see, all this does is capture requests to /poller and return “Hello, World!” (and the request is not for /poller, it’ll let the Rails router handle it — that’s what the 404 return does). It will do that just about as fast as is technically possible in Rack (cue useless metric of how Rails now has the fastest, most meaningless “hello world” stat!!).

Note that this is a pretty specialized tool. While you could write an entire Rails application using just metal, it would be a terrible idea in most cases. The vast majority of applications out there will never do what they do so fast that the overhead of the already heavily optimized Rails router and Action Controller execution path will matter one bit (pick up Michael Koziarski’s talk on Rails Performance through torrent for more on this).

Also, if you’re writing a generic filter in the vein of Rack::Cache, Metal is not the right choice either. You should just be creating regular middleware which can be shared across all Rack applications.

But for those few, specialized cases where you just need as much raw speed as possible, Metal can be exactly what the doctor ordered. It allows you to have the best of both worlds in one package. The lowest possible overhead for a Rack application when that matters and the full-featured goodness of Action Controller when it doesn’t.

We hope you like this. Josh Peek has putting tireless hours into getting Rails on Rack and this is just the latest product of his efforts. Thanks a bunch, Josh!

Update: Jesse Newland wrote up a great introduction to Metal as well. It includes benchmarks and even more examples!

Update 2: Changed code example to match latest style.

New 15-minute blog video on Rails 2.2

The old 15-minute blog video was getting really long in the tooth, so it’s with great pleasure that I can present the new video made with Rails 2.2 and done by Ryan Bates. It really takes it all up a notch by showing the creation of a blog with comments, ajax, feed, api, admin interface, and more.

Ryan Bates is also the author of the wonderful site that features video explanations on Rails features. It’s a fantastic resource and now properly recognized on the screencasting page.

I’ve also linked up the commercial Rails screencasters. The amount of material available for people interested in learning by video is simply staggering.

New Rails 2.2 i18n defaults

I just reduced the housework needed to setup a new Rails application with i18n. All new applications will ship with a config/locales directory that’s automatically wired up in the load path for i18n. So you can just drop .yml or .rb locale files in there and they’ll be instantly available for translation.

There’s also a sample config/locales/en.yml file in there to give you a starting point. In addition, the initializer is now wired up through the Rails config. The new default environment.rb provides these pointers:

# The internationalization framework can be changed 
# to have another default locale (standard is :en) or more load paths.
# All files from config/locales/*.rb,yml are added automatically.
# config.i18n.load_path << Dir[File.join(RAILS_ROOT, 'my', 'locales', '*.{rb,yml}')]
# config.i18n.default_locale = :de

So on a fresh Rails 2.2 application, you’ll be able to do see it all wired up out of the box (the :hello key is from the config/locales/en.yml demo file):

$ ./script/console
>> I18n.t :hello
=> "Hello world"

Rails 2.2 final is just around the corner. We’ve been ironing out the last bugs and added the last amount of polish to make this a kick ass release. Also, work on 2.3 / 3.0 has already begun in master as well since we’ve branched for 2.2 a while back.

Rails Guides Wants You

If you haven’t looked at the state of Rails documentation lately, it’s time to look again. The new Ruby on Rails Guides page includes 14 separate guides for Rails developers, with topics ranging from “Getting Started” to routing, security, testing, and debugging. That’s over 70,000 words of help content for Rails users that didn’t exist two months ago when we launched the Rails Guides project.

But we’re not done yet! We’re starting phase 2 of the Guides project, and planning a fresh batch of content to add to what’s already there. Our goal is to have a single page where you can find all of the information you need to be an effective Rails developer. Remember, though: this is open source. That means we want your help too!

Here’s what you can do to get involved:

  • Read about the process of and rewards for contributing on the Hackfest page.
  • Check the list of available tickets in our Lighthouse project, and sign up to write a guide.
  • Submit corrections, suggestion, bugs, or patches for the existing guides. You’ll find a link to the relevant Lighthouse ticket at the bottom of each guide.
  • Let us know what other guides you think should be added – whether you want to write them, or just hope that someone else will. Just leave a note in the comments here and we’ll get your idea into the process.

You’ll usually find some of the documentation team hanging around in #docrails on IRC. Come join us and help the community!

Guides Hackfest

I’m pleased to finally announce the Rails Guides Hackfests. And we got really exciting prizes too! There is a list of guides available at Lighthouse You can select one of those, update the ticket and start writing the guide straight away.

For each completed guide, the author will receive all of the following prizes :

You can find more details at

Special thanks to GitHub, Newrelic & Caboose documentation project for making the hackfest a lot more exciting!

Free Rails 2.1 Book

If you’re eager to learn how to use all the new features in Rails 2.1, Carlos Brando just released a free book titled Ruby on Rails 2.1, What’s New?. You can download the PDF in its original Portuguese, or its very recent English translation. This 120 page book covers everything you need to know about Rails 2.1 with many step by step examples.

You might also know Carlos Brando from the Ruby on Rails Podcast Brazil he does with Fabio Akita. If you’re a Rails developer and you speak Portuguese, definitely check out their podcast.

Help improve Rails documentation on Git branch

Pratik’s documentation branch for Rails has moved to This branch is open for all to contribute to directly. Just send Pratik a note on Github asking for access and it shall be granted. There’s even a page for the conventions used on the branch.

This makes it easier than ever to help improve the documentation for Rails and harder than ever to just sit back and whine about it. Make something great!

Agile Web Development with Rails, 3rd Edition

You asked for, heck, you demanded it, and now it’s becoming a reality. The original Rails book, Agile Web Development with Rails, is getting a facelift and the 3rd edition is now available as a beta book.

The book will be targeting Rails 2 and thus cover the many improvements in features and idioms that Rails have seen since the last edition of the book.

We also have a new author on board with the project: Sam Ruby. Sam co-authored the wonderful RESTful Web Services and have been involved with the Ruby and Rails communities for quite some time now. It’s fantastic to have him involved with the book.

Passenger (mod_rails for Apache) launches

The guys at Phusion has finally wrapped up Passenger, their mod_rails-like module for Apache. It’s looking like a great, easy solution for people who want a more PHP-like deployment story. Just dump your files in a directory setup with a vhost and off you go. Touch tmp/restart.txt and the application is restarted. Doesn’t get much simpler than that.

A taste of what's coming in Rails 2.1

Rails 2.1 is not far off the horizon and we’ve been adding a ton of extra deliciously nice goodies in preparation of its release lately. As always, the good Ryan Daigle has been keeping a watchful eye on the changelog and has been documenting some of the new features. The latest stars are:

The Rails Way and Advanced Rails Recipes

The flow of new Rails books seems unstoppable these days and it’s hard to keep up with all of the new releases. But there are two books that I’ve recently have had a chance to taste that I’d like to highlight.

The first is The Rails Way by Obie Fernandez, which I wrote the foreword for. It’s a big whooper of a book (900+ pages!), but also a very comprehensive walk-through for the Rails developer who already has his feet wet. It also includes a good dose of community commentary on the how’s and why’s, which I rather like.

The second is Mike Clark’s Advanced Rails Recipes, which is still not finished, but there’s a beta book available. It takes up from Chad Fowler’s original Rails Recipes book and gives you another 72 how-tos on more in-depth topics, such as REST, deployment, and testing. I’ve had a chance to taste a few of the recipes already and it’s good stuff.

If there’s a new Rails book that you really like, write a note in the comments and point people to it.

Trouble installing new gems? (Part II)

A number of users have reported problems installing the latest Rails gems, especially on Windows. The solution is to upgrade RubyGems to version 0.9.5 1.0.0 before upgrading. You can check your RubyGems version by:

gem —version

If 0.9.5 1.0.0 is not the answer, do (you may not need to prefix with sudo, on OS X you do, some ’nix distributions too, but not Windows):

sudo gem update —system

Then do:

sudo gem install rails

And while this should no longer be an issue, you can always install Rails from the Rails gem repository if the official one is having issues for whatever reason (such as right after a new release where the mirrors have some times not caught up and are spewing 404 errors):

sudo gem install rails —source

If you want to use SQLite3 for a new application, first make sure that you have SQLite3 itself installed. If not, you can get it from the SQLite download page. Then make sure you have the Ruby bindings installed (the gem is called sqlite3-ruby). If you don’t, just:

sudo gem install sqlite3-ruby

If you don’t want to use SQLite3, that’s fine. Just do “rails -d mysql myapp” when creating your new application to get MySQL preconfigured. Or “rails -d postgresql myapp”. Or any other adapter you might want to use that you have installed, like Oracle, SQL Server, or what have you. The only thing we changed was which database adapter would be preconfigured if you didn’t explicitly set which to use.

UPDATE: RubyGems 1.0.0 is now out, which should fix the problems with Mongrel and Windows.

Give your Rails 2.0 application an iPhone UI

Multi-view development is a big deal in Rails 2.0. We’ve made it much simpler to allow the same action to serve many different formats. From HTML to XML to JSON to RSS and ATOM to CSV to whatever.

But did you know that you can use the same multi-view system to trout out different flavors of the same basic types? Say, give iPhone users a custom HTML interface while serving regular HTML users with the standard feast.

Slash Dot Dash teaches you how to do exactly that: Give a Rails 2.0 application an iPhone UI.

Prototype 1.6.0 and 1.8.0 released

New versions of the JavaScript libraries that ship with Rails, Prototype 1.6.0 and 1.8.0, have been released. You can find out about the numerous changes on the Prototype blog and on If you’re running Edge Rails, just svn up and run rake rails:update:javascripts to install the latest versions into your application automatically.

Also of note: Christophe Porteneuve’s Prototype & book is now out of beta and available for purchase from the Pragmatic Programmers. It’s up-to-date with all of the new features in both libraries, so be sure to check it out if you’re using Prototype and in your applications.

Free Rails PDF Book

Sitepoint is currently giving away free PDF copies of Patrick Lenz’s “Build Your Own Ruby on Rails Web Applications” book. Want a copy? Just head on over to and download it. This offer is only good for the next 60 days, so get while the gettin’ is good!


Looking for a good way to browse the Rails API documentation? Alex Gorbatchev has recently created Noobkit, a documentation browser for Rails, Ruby core, and over 20 other useful libraries. It also supports searching, comments (with your OpenID), and bookmarks.

Writing Google Maps Applications with Rails and Ajax

Andre Lewis is rolling out a duo of resources for those of you creating mashups and Google Maps-based applications.

Andre's book, Beginning Google Maps Applications with Rails and Ajax: from Novice to Professional will be available Feb 26 from Apress. The book covers the basics (getting a Google map up and running, interacting with the the Google maps API in JavaScript), as well as more advanced topics. For example, later chapters show you how to use RMagick to display hundreds of thousands of points on a map by generating custom map tiles, and how to create your own geocoder from US TIGER/Line census data. The book also touches on screen scaping and bulk data manipulation -- for example, processing large text files from the command line using Ruby, and the performance implications of a pure ActiveRecord database import vs MySqlImport.

Also related to mapping, Andre recently released GeoKit. GeoKit provides a bundle of tools to make maps-based applications easier:

  • Distance calculations in miles or kilometers: distance = first_location.distance_to(second_location, :units => :miles)
  • ActiveRecord distance-based finders: Store.find(:all, :origin=>[37.792,-122.393], :conditions=>'distance < 10')
  • . . . and directly from an address: Store.find_closest(:origin=>'100 Spear St, San Francisco, CA')
  • Geocoding from Google, Yahoo,, and geocoding services. It provides a uniform response structure from all the geocoders, and also has a configurable fail-over mechanism in case one geocoder fails.
  • IP-based location lookup. Provide an IP address, and get a city name and latitude/longitude in return.

Andre's announcement on GeoKit is here. Bill Eisenhauer, the co-author of GeoKit, has also put up some live demos. GeoKit's home at RubyForge is

New Feature for Rails 2.0: Multiple Controller View Paths

Thanks to John Long, Rails now supports multiple view paths for each controller. For 90% of the apps, this probably won’t make a huge difference. But, for those of you wanting to productize various open source apps, you can now do this:

/beast/trunk$ mkdir vendor/plugins/test_view_paths
/beast/trunk$ cd vendor/plugins/test_view_paths
/beast/trunk/vendor/plugins/test_view_paths$ mkdir views
/beast/trunk/vendor/plugins/test_view_paths$ echo “ActionController::Base.view_paths.unshift File.join(directory, ‘views’)” > init.rb

What you’ve done is created a minimal rails plugin that inserts a ‘views’ directory in the plugin to the beginning of the #view_paths array. Now, copy a view from the rails app into the plugin’s ‘views’ directory, make a noticeable change, and start your app. You’ll notice that it picked your plugin’s view over the application’s view.

Rails Cookbook

Rob Orsini released the new Rails Cookbook from O’Reilly, just in time for Rails 1.2. Just from looking at the table of contents, it looks like there’s a lot of good information packed in this book.

This book is packed with the solutions you need to be proficient
developer with Rails, the leading framework for building the new
generation of Web 2.0 applications. Recipes range from the basics,
like installing Rails and setting up your development environment, to
the latest techniques, such as developing RESTful web services. Each
recipe includes a tested solution, plus a discussion of how and why
it works. — from the book’s Full Description

A brief introduction to Active Resource

Rick Olson is getting jiggy with Active Resource these days and decided to spread the love with a brief introduction to the newest member of the Rails framework family. He takes you through how to use ARes as a client for the Beast forum in a few simple steps. Get your REST face on and enjoy.

Agile Web Development with Rails, 2nd Edition

How fitting. Just as we’re wrapping up Rails 1.2, the book that covers it all has gone into print. I’m talking about Agile Web Development with Rails, 2nd Edition, of course. The book that has taught the vast majority of all Rails developers the ropes.

Yes, yes, it’ll be available in all its paper glory around December 15th. But you can actually get the final PDF now. Dave Thomas just released the same version as was shipped off to the printers. If you’d like to get access to the information now, but still enjoy reading long sections from paper, there’s the combo pack.

The timing is great and so are the sections on RJS, migrations, resources, respond_to, polymorphic associations, and all the other new-fangled wonders that has been introduced to Rails since the last version of the book. Go get it.

Filtered parameter logging

Now that the hubbub about the recent security issues has died down, I think it's worth pointing out a little jewel that was snuck into the 1.1.6 security release of Rails that most people missed.

ActionController#filter_parameter_logging lets you filter form data that you don't want saved in the log. This is useful for preventing sensitive data like passwords and credit card numbers from being logged in the clear, for keeping huge pieces of data from clogging the log file, and so on.

If your application accepts passwords, paste this line into your ApplicationController class:

filter_parameter_logging "password"

That will prevent any field with a name matching the pattern /password/i from being logged, so both [user][password] and [user][password_confirmation] will be filtered out. If you care about preventing exposure of passwords, go do that right now.

Credit to Jeremy Evans for his patch!

Rails Conference slides coming soon

Jay Zimmerman just wrote to say that next Wednesday, July 26th, the presentation media for RailsConf 2006 will go on sale to the general public. So if you didn't get to the conference, you can pick up all the slides with synced audio for $100. Surf on over to the ScribeStudio site for more information. And remember, videos of the seven keynote presentations are being made available for free download too.

RailsConf keynotes on video

If you missed RailsConf 2006, you'll be glad to know that videos of the keynote presentations are being made available for online viewing and (coming soon) download. A collection of slides synchronized with recorded audio for all presentations will also be available soon. Videos and information about audio and slides can be found at ScribeMedia at the RailsConf 2006 Keynote Series page.

The first two keynotes by Dave Thomas and Martin Fowler are already available. The other five will trickle out over the next few weeks. Next up, David Heinemeier Hansson's keynote on "A World of Resources".

Tips on how to improve application efficiency

Rails performance specialist Stefan Kaes, who writes extensively about optimizing Rails over at Rails Express has a lengthy article at the new InfoQ site called A Look at Common Performance Problems in Rails.

Kaes identifies various development practices that will slow down your Rails applications, such as repeating computations that only need to be run once and then cached. If you’ve located some slowness in your application, Kaes may have already identified some of the likely culprits.

Collaborative Rails API Documentation

With Rails in a constant state of evolution, it’s important for its users to help each other stay in step with what’s current. To that end, Conor Hunt has created Rannotate, a system for collaboratively annotating RDoc-generated documentation.

He’s gone a step further and posted Rannotate instances for both Rails and Ruby.

Read, post, learn, and teach. At critical mass, Conor’s service could provide a huge benefit to the community. Coupled with Kevin Clark’s Rails documentation crusade, things are looking better and better on the documentation front.

These guys deserve our appreciation and our support. Now go post some annotations!

All about Rails Trac keywords

Keywords in the Rails Trac get used in two ways. The first is a standard tagging system, where users tag tickets with whatever keywords they think describe the topic of the ticket. To give you an idea of what people use this type of tag for, here are the 25 most commonly used ones:

postgresql, performance, ajax, test, routes, sqlserver, activerecord, mysql, rake, documentation, form, prototype, generator, fixtures, error, helper, migration, patch, scaffold, webrick, oracle, adapter, session, has_many, tested, inflector, date.

Using keywords as tags is fine, but by no means required. It may make it easier for someone to find your ticket if they encounter a similar issue, but it's not a big deal if you don't use any tags at all.

The second way keywords are used is to help manage how tickets are processed. As of this writing there are 20 standard reports in the Rails Trac, and nine of them filter tickets based on specific keywords. A couple of the reports are only used during a push towards a release. One is being used for managing documentation updates. And six are about the life-cycle and categorization of patches. Those six are the ones that are interesting to us here.

A patch is just a ticket that has .diff file attached that contains a bug-fix or enhancement of some sort. The summary line for patch tickets should always start with the text [PATCH]. You don't need to use a patch keyword - it's redundant and no one pays attention to it. There are just five keywords that are used to manage patches during regular (non-push) development:

verified, unverified, needy, risky, tiny

Here's how to use these keywords on your patch: Don't. You should not use any of these keywords when creating a patch ticket. They are used by the core team to indicate the processing state of a patch, and if you add the keywords yourself it can confuse matters and might make it harder for someone to sort out what to do with the patch.

As I'm sure you're curious (or you wouldn't be reading this article), here's a summary of what the keywords are used for. Verified and unverified indicate whether someone from the core team (or designated helper) has checked out the patch to see if it operates as claimed, tests pass, etc. Needy, risky, and tiny indicate the patch's potential impact to stability and if extra work might be involved in getting it working. Full explanations can be found on the report pages in Trac. Look at reports 3, 4, 11, 12, 16 and 17, if you really want to know.

There isn't a rigid process the core team uses to process patch submissions. The patch life-cycle reports get used sometimes, and other times people just watch the Trac RSS feed for new patches. Marcel Molina Jr says, "I use the reports but not religiously. I use them once-in-a-whilely. On the occasion when I do, though, it is appreciated and allows me to quickly process a lot of tickets." So if you want your patch to be processed quickly, it's probably best to leave off the five patch-state keywords and let the core team use them without confusion.

Rails Views

Bruce Williams has started a new article series he calls Rails Views. Bruce is a long-time Rubyist and Rails early adopter and is the UI lead on development of a very large and complex Rails system. If it’s Rails and UI-related, Bruce is the man.

Now he’s chosen to share some of his Rails UI wisdom with the rest of us. If you’re doing complex user interface work in Rails, check it out.

Testing RJS with ARTS

An Achilles’ heal of Rails is no good way to test your RJS. As the presentation behavior gets more and more sophisticated, the inability to test it becomes a real problem. Not anymore.

Kevin Clark has released ARTS, a mechanism to test RJS. His API is simple yet flexible. A single point of entry let’s you test a considerable amount of the RJS you can generate. Here’s an idea of what you can do:

  assert_rjs :alert, 'Hi!'                                                     
  assert_rjs :assign, 'a', '2'                                                 
  assert_rjs :call, 'foo', 'bar', 'baz'                                        
  assert_rjs :draggable, 'draggable_item'                                      
  assert_rjs :drop_receiving, 'receiving_item'                                 
  assert_rjs :hide, "post_1", "post_2", "post_3"                               
  assert_rjs :insert_html, :bottom, 'posts'                                    
  assert_rjs :redirect_to, :action => 'list'                                   
  assert_rjs :remove, "post_1", "post_2", "post_3"                             
  assert_rjs :replace, 'completely_replaced_div', '<p>This replaced the        
  assert_rjs :replace_html, 'replaceable_div', "This goes inside the           
  assert_rjs :show, "post_1", "post_2", "post_3"                               
  assert_rjs :sortable, 'sortable_item'                                        
  assert_rjs :toggle, "post_1", "post_2", "post_3"                             
  assert_rjs :visual_effect, :highlight, "posts", :duration => '1.0'           

He’s written up an extensive tutorial to get you up and running.

Guide: Environments in Rails 1.1

As mentioned last week, Kevin Clark is taking your suggestions and developing weekly guides that cover the ins and outs of Rails.

He’s delivered on his first guide: Environments in Rails 1.1. The accompaying Cheat Sheet is particularly noteworthy. It lists all the various configuration options available to you, with a brief description of the purpose they serve.

To have your say on what Kevin covers next, send him your suggestion at kevin dot clark at gmail dot com with [idea] in the subject.

Weekly interactive guides with Kevin Clark

Kevin Clark, the guy whose recently taken on the documentation cleanup project, is diversifying his documentation work. His latest idea: weekly interactive guides.

Write into Kevin with requests on a specific Rails related topic that you’d like to understand better. He chooses a topic from your requests each week and builds a guide around that topic.

Get your submissions in by Monday to kevin dot clark at gmail dot com. Include [idea] at the start of the Subject. He’ll have the guide ready by the following Monday.

A gentle reminder about pluralizations

Watching the RSS feed from the Ruby on Rails trac is a great way to keep up on what's happening in Rails development. If you're doing any development on the Ruby on Rails project it's required reading. Even if you just are using Rails for a web app, it's useful to keep up on what bugs people are reporting.

Lately I've noticed a slew of bugs being opened against the Inflector, the class in Rails that transforms words from one form to another: singular to plural, classname to tablename, etc. The bugs all complain that Inflector is getting a pluralization or singularization wrong. But this isn't a bug in Inflector, it is just an inherent limitation of how it works. But fear not, there is a better solution than opening a bug against the Inflector.

I guess this has been a constant thing over the history of Rails, but since it's still going on, it deserves a rehash.

Rails Recipes is out of beta

Chad Fowler’s excellent Rails Recipes, quickly becoming the de facto companion to the canonical Agile Web Development with Rails, is out of beta and off to the printers. Now that you, the community, put it through its beta paces, it’s been cleaned up and deemed ready for prime time. If you’ve been holding off til now, your time has come: order it here.

For those who couldn’t wait and jumped on board during the beta, you can get a free update here.

A big thanks to Chad for the months of work he’s put into this.

UPDATE: Chad shares his take on What Makes a Good Recipe Book.

Deploying Rails on Windows servers

Most Rails applications are deployed in a Unix server environment. Tools like Capistrano make this dead easy. For those working in a Windows environment, deployment can get considerably harder. The good news is that it’s still possible and just got a lot easier.

Brian Hogan has developed a series of articles with instructions for various methods of deploying Rails applications in a Windows server environment. Broken up across four articles, the topics covered are as follows:

Cheers to Brian for sharing the fruits of his labor.

Laying Tracks: How to Contribute to Rails

Josh Susser is at it again. He’s whiped up a PDF presentation called Laying Tracks which details the hows and the whys of contributing patches to Rails.

At just 16 slides, it’s short but meaty. He sums up the patch making and contributing workflow succinctly. This should be required reading for anyone looking to submit code to Rails core.

Documentation push

We’ve recently decided to put some work into Rails documentation. We’d like to flesh out the existing docs, add documentation for the corners that are lacking and update what may have gone stale.

Kevin Clark is leading up this campaign and would like to get the help of the community at large.

He’s got a write up that goes over how you can help Documenting Rails . It summarizes what we are looking for and gives basic instructions to get those who are interested in helping up and running. The main guidelines are:

  • Write to teach
  • Provide examples
  • Don’t restate the obvious

Good documentation patches are right up there with good code patches. If you’d like to help out Rails while gaining a deeper understanding of how it works, taking part in this documentation project would be a great start.

The Complete Guide to Rails Plugins

Plugins are the official way to bend Rails to do your bidding. Creating a plugin is a great way to share your Rails extensions with others who may find them useful. Until recently though, resources on plugins have been scattered around various blog articles and mailing list posts.

Mr. Rails Podcast Geoffrey Grosenbach has pulled together these various resources and done the homework for you. Presented in several parts, here is Part I of The Complete Guide to Rails Plugins.

This first installment is an introductory overview. He covers how to find and install plugins, lists the various points of entry into your Rails app that plugins can hook into as well as summarizing the parts they generally consist of. He’s got an explanation for each default file and directory that gets generated for a new plugin.

With this primer you’ll be all set for making your own plugin when Part II comes around.

Agile Web Development with Rails goes second edition

It’s back. Agile Web Development with Rails is now available in a 50%-done beta version of its second edition. Pretty much everything is getting a major overhaul. All the cool stuff we’ve added in Rails 1.1 is covered in the same structure that people so liked from the first version.

It’s wonderful to be able to present a version two of the primary title that has helped so many people get into Rails. And through the wonders of PDFs and agile publishing, to have it available so soon.

So if you’re interested in getting the latest scoop on everything from RJS, to join models, to migrations, to RESTful interfaces, to Capistrano, this is most definitely the book to get.

P.S.: Just so you don’t feel buyers remorse two days after getting a PDF of the first edition, anyone that bought that PDF on or after April 1st gets a free upgrade to the second edition.

Both Dave Thomas and I covered the announcement in additional detail.

Associations aren't :dependent => true anymore

Up until the 1.1 release, the way to automatically destroy has_many associations when the owner was itself destroyed was to either use the :dependent or :exclusively_dependent option when declaring the has_many.

class Account < ActiveRecord::Base
  has_many :members, :dependent => true


class Brand < ActiveRecord::Base
  has_many :products, :exclusively_dependent => true

The :dependent option instantiated all the associated objects and called destroy on each one. Destroy in turn triggers the callbacks defined on that associated model, such as those declared with before_destroy and after_destroy.

The :exclusively_dependent option, on the other hand, did not instantiate all the associated objects. Rather, it just generated a single SQL statement which deleted the associated records without first creating objects for each one. This buys you efficiency when you have no need for the flexibility of triggering model callbacks.

Since 1.1, the API for garbage collecting associated records has been consolidated into the :dependent option. Rather than saying :dependent => true, you now pass one of several symbols to the :dependent option which describes how the association is dependent on the owner.

Declaring the has many as :dependent => :destroy is the same as what used to be declared as :dependent => true. When the owner is destroyed, all the associated records are instantiated and destroyed.

class Account < ActiveRecord::Base
  # Deprecated
  # has_many :members, :dependent => true
  # In favor of
  has_many :members, :dependent => :destroy

The new way to achieve the now deprecated :exclusively_dependent configuration is to use :dependent => :delete_all rather than :dependent => :destroy.

class Brand < ActiveRecord::Base
  # Deprecated
  # has_many :products, :exclusively_dependent => true

  # In favor of
  has_many :products, :dependent => :delete_all

The :destroy and :delete_all option symbols are so named because they correspond with the behavior achieved by calling destroy versus delete on a model object. One triggers callbacks, the other just generates the delete SQL statement.

As an aside, another valid option is :dependent => :nullify which is similar to :dependent => :delete_all except rather than deleting the associated records, it just sets their foreign keys to NULL. This effectively removes the association, without removing the associated records from the database table.

As always, the semantics of :dependent => :destroy and :dependent => :delete_all are mutually exclusive, which this new API makes a bit more apparent.

It should be noted that declaring dependencies is not required when setting up has many associations. It is simply an option for when you desire such functionality.

Keep in mind that for now :dependent => true and :exclusively_dependent => true will still be supported, but they have been marked as deprecated and could be taken out in the future.

Use params, not @params

I still frequently see people in the #rubyonrails channel using @params in their code. For a while now @params has been deprecated in favor of simply params. For those who just skim these blog posts:

Use params, not @params

Why? When you use the params method, it allows for the implementation details of the parameter hash to be changed without breaking existing code. If the implementation of params changed you wouldn’t have to change your code at all because the single point of access for the parameters would just remain the params method. So, the details of what is happening behind the scenes don’t matter. If, though, you use the @params instance variable directly, you’ve broken encapsulation and consequently the ability for the implementation to be easily modified. Methods can be refactored, but instance variables can’t. Today the params method just wraps the @params instance variable, so still using @params works, but that’s not guaranteed to always remain the case.

Same goes for request, response, session, headers, template, cookies and flash.

Basically, a good rule of thumb here is don’t use an instance variable in your controller or view unless you created that instance variable.

Even the old @content_for_layout in the layout is deprecated in favor of just using yield in its place. Also content_for('some_fragment') is now accessed with yield :some_fragment rather than @content_for_some_fragment.

habtm vs has_many :through

Of late the ActiveRecord association code has been getting a lot of love. One of the high profile additions are polymorphic associations which turned into one of the big features of the 1.1 release. Amongst all the commotion, some may not have noticed that there is an enhanced way to do many to many associations other than with has_and_belongs_to_many.

For some time people have been skipping out on has_and_belongs_to_many in favor of setting up two has_many associations so that they get the benefits of a full join model and what that brings with it. With 1.1’s new :through association option, a two way has_many just got even sweeter. So if there are two ways to do a many to many relationship, what are the differences, and which approach should you take?

Josh Susser has been digging deep into the association code lately and has emerged from the thicket with a point by point comparison of habtm and has_many :through, a dance-off if you will, between the two approaches. This would be a good time to add him to your RSS reader if you haven’t already.

Writing Domain Specific Languages

If you’ve been in the Ruby community for any time, you will likely have heard about “Domain Specific Languages”. Rails uses the concept extensively with its macro style methods for setting up associations, callbacks and validations in models, as well as layouts and filters in controllers. Indeed, Ruby provides great support for creating your own DSLs. It may have become easier to spot domain specific languages, but how does one actually implement them?

Rails core team member Jamis Buck has taken the time to guide you toward understanding the fundamental mechanisms used to create domain specific languages. Get up to speed with his tutorial, Writing Domain Specific Languages, and you’ll be creating elegant abstractions sooner rather than later. What a treat.

Rails Recipes release candidate now available

Dave Thomas has just announced that the first release-candidate of Rails Recipes is now available. What that means is that the book is essentially in its finished form. It’s had a great beta run, with a lot of praise and good feedback. Now that it’s been put through its passes, it’s pretty much ready for primetime, sporting 70 solutions to your real world programming challenges. If you’ve been holding off, now is a great time to get in on what is shaping up to be the de facto companion to Agile Web Development with Rails.

If you already bought the PDF, you can get the latest copy for free.

If you haven’t, what are you waiting for? Order it here.

Rails training for a good cause

Here’s a good idea: Use a hot new technology to help kids prepare to create the next hot new technology.

Amy Hoy, Ezra Zygmuntowicz and Jeff Casimir are doing just that and calling it Workshop for Good. On Saturday, May 20th and Sunday, May 21st, in Washington, D.C. Amy, Ezra and Jeff will be teaching an intensive Rails workshop. All (i.e. 100%) of the proceeds from attendance fees ($400 regular, $200 for students) will go towards buying stuff like computers for the students of César Chávez Public Charter School.

Amy Hoy has been giving back to the Rails community with education almost since day one. You may have gotten over the initial hurdles yourself with one of her accessible tutorials or clarifying visual aids. Ezra Zygmuntowicz singlehandedly built one of the first substantial real world Rails applications, the Yakima Herald Website and is currently working on a Rails book for the Pragmatic Programmers. Both bring substantial experience with Rails to the workshop.

Last I heard there were 23 spots left so get on the list while you still can. Take this opportunity to both learn Rails and promote a great cause. Killing two birds with one stone is seriously agile.

Sign up here

UPDATE: There are only 8 seats left! If you were thinking of coming, now is your chance to get in.

Ruby for Rails book now available in full

David A. Black’s book Ruby for Rails is now available in full in PDF form (paper copy scheduled to follow the first week of May). The book covers the ins and outs of Ruby with a focus on Rails. It is aimed at Rails developers who want to gain a deeper understanding of Ruby beyond what Rails builds on top of it.

Taking a look at the table of contents you’ll get a sense of how much territory the book covers. There are two sample chapers for free. One is on Organizing objects with classes and the other on Scalar objects.

David Black is an ideal guide through Ruby, having been a member of the community for over 5 years and as the director of Ruby Central, the not for profit organization that brings you RubyConf every year.

It’s no secret that Ruby is one of the key ingredients in Rails’ special sauce. If you are a Rails developer, you owe it to yourself to be a Ruby master. Ruby for Rails is a great place to start.

Rails for designers

Kevin Clark has written up Rails for designers, an intro to Rails directed at designers which focuses on the parts and concepts of the framework that are of most immediate relevance to a designer. The tutorial gets designers oriented and ready to find, edit and use an application’s templates. From layouts, to ERb, to partials and instance variables, this tutorial will get designers up and running in no time. If you are thinking of doing a Rails project, you could do a lot worse than having your designers start with this tutorial. Thanks for the primer Kevin.

The Adventures of Scaling: A Case Study

Patrick Lenz has started in on a case study The adventures of scaling, in four instalments, on how he made scale, improving its performance by about 60%.

The online community site was ported from 50,000 lines of PHP to 5,000 lines of Rails. It serves up over 1 million dynamic page impressions on a “good day”. This first instalment goes through their unsuitable initial setup and explains why it didn’t work, including a diagram of their configuration. As one of the article’s commenters says, “Nothing beats a shiny chart”. Looks promising. Good start. Thanks for the write up Patrick. Stay tuned.

New in Rails: Enumerable#group_by and Array#in_groups_of

Changeset 3726 adds two little methods to ActiveSupport: Enumerable#group_by and @ Array#in_groups_of@.

Enumerable#group_by is for collecting an enumerable into sets, grouped by the result of a block. Useful, for example, for grouping records by date.

     latest_transcripts.group_by(&:day).each do |day, transcripts| 
       p "#{day} -> #{ * ', '}"
     "2006-03-01 -> Transcript"
     "2006-02-28 -> Transcript"
     "2006-02-27 -> Transcript, Transcript"
     "2006-02-26 -> Transcript, Transcript"

Enumerable#group_by will be baked right into Ruby in the future, and currently lives in the 1.9 branch.

Array#in_groups_of let’s you iterate over an array in groups of a certain size, optionally padding any remaining
slots with a specified value (nil by default).

     %w(1 2 3 4 5 6 7).in_groups_of(3) {|g| p g}
     ["1", "2", "3"]
     ["4", "5", "6"]
     ["7", nil, nil]

You gotta love the elegant encapsulation afforded by blocks! Yield.

Two Ruby articles in the latest ObjectiveView

ObjectiveView, a journal for software developers that focuses each issue on a specific topic, has two Ruby related articles in their latest issue, New Technologies Focus.

The first is an introduction to Ruby by Amy Hoy. She brings her quirky right-brained ebullience to bear, providing a thorough yet accessible tour of Ruby. She emphasizes that one of its most salient characteristics is that it makes you happy. If her writing style is any indication, she’s loving life.

ThoughtWorker Obie Fernandez serves up the other article which demonstrats what DHH’s often cited phrase “opinionated software” means and how it relates to Rails. Keep an eye out for Obie’s upcoming book, Extending Ruby on Rails (Into the Enterprise) which is expected out in Fall 2006 by Addison-Wesley.

These two tutorials provide a nice introduction to both Ruby and Rails.

Past issues of ObjectView which focus on such topics as agile development, use cases and componentized development, are also available, so check out the rest of the back issues on their website.

Using Ruby on Rails on Mac OS X at the Apple Developer Connection

The Apple Developer Connection has a nice Ruby on Rails tutorial called Using Ruby on Rails for Web Development on Mac OS X. As the title suggests, it is aimed at getting OS X users off the ground with Rails.

The Apple Developer Connection doesn’t supply any attribution for their articles, but this one was written by none other than Mike Clark, who along with Dave Thomas runs the always-sold-out Pragmatic Studio series of Ruby on Rails and Ajax training.

Cheers to Mike for taking the time out of his busy schedule to write up a great tutorial.

Book: Ruby for Rails available via Manning Early Access program

Long time resident mentor on ruby-talk and Ruby Central co-founder, David Black, is just finishing up a book that should be of special interest to those whose first Ruby experiences are coming by way of Rails: Ruby for Rails – Ruby techniques for Rails developers.

The book will be available in stores at the beginning of May. Meanwhile you can get chapters one at a time, as they’re completed, through the Manning Early Access Program.

Check it out.

Rails Recipes premieres in beta book form

Chad Fowler has completed the first draft of the initial 21 chapters for Rails Recipes and is now making the work available as a beta book for purchase. The final book is still a ways off, but this is an awesome opportunity to get at the very timely material right now. You need to strap on your edge shoes and get the latest Rails version off the repository for some of the recipes that rely on 1.1 features, but most of them is just about clever ways to do common things.

The great thing about Chad’s approach to these tutorials is that they are more like case studies than laundry lists of commands to input. Take the recipe to use Active Record with multiple databases. First, it sets up a complete sample mini-application to demonstrate (using best practices like migrations), then walks you through how the quick one-off hack would look like (so you understand the mechanics), then wraps everything up in a sweet External class hierarchy for ease of reuse. And then of course tops up with a recommendation that you shouldn’t really be using multiple databases unless you have no other choice and offers alternatives to avoid it.

This makes Rails Recipes useful for more than just looking up when you encounter a problem it has the solution for. It serves just as well as a teaching tool in the best practices of the framework in general and you’re likely to become a better Rails programmer by reading through all of the recipes one by one. Even if you don’t need to use multiple databases today.

So this is the perfect stepping stone after or as a companion with the Agile Web Development with Rails book. Get the first 21 recipes today and receive updates with additional recipes as they become ready. I’ll be working with Chad myself to ensure that these recipes offer as much of The Rails Way as possible and that it’ll discuss how to use all the goodies from the forthcoming Rails 1.1.

Now what are you waiting for? Go pick it up, yo.

O'Reilly's first Rails book premieres in beta form

O’Reilly has launched their Rough Cuts series with Ruby on Rails: Up and running as one of the first titles leading the charge. Rough Cuts is O’Reilly’s version of Beta Books or Early Access and gives you access to the content while it’s still being written.

Ruby on Rails: Up and running is written by Bruce Tate and Curt Hibbs. The final book is expected in May. Also of note for Railers on Rough Cut is Ruby Cookbook by Leonard Richardson and Lucas Carlson. That one is expected done in September. Not to be confused with the Rails Recipes by Chad Fowler (featuring recipes and secrets from the 37signals dome) that’ll be out in February.

So that marks four books currently available in final or beta form that focuses exclusively or partly on Rails: Agile Web Development with Rails (the original bible), Rapid Web Development mit Ruby on Rails, Ruby on Rails: Up and running, and Ruby Cookbook. That’s quite an achievement already!

And coming soon will be Chad Fowler’s Rails Recipes and David A. Black’s Ruby for Rails, which will bring us to a total of six books. And I believe there’s at least a good handful of additional books in the works. Rails is certainly on track to be the best documented web framework for the dynamic languages. Rock on.

Rapid Web Development mit Ruby on Rails

Ralf Wirdemann and Thomas Baustert have released Rapid Web Development mit Ruby on Rails. The first German book on Rails and published by Hanser. It should be available in stores from Monday, January 16th.

About the book, Ralf and Thomas write:

The book is a practice-oriented introduction into Rails and all of its sub-frameworks. The book focuses furthermore on some advanced topics as i18n with Rails or test-driven web development with Rails.

As a extra bonus, they’re even giving away a free introduction to Ruby that didn’t fit in the book. Congratulations, guys!

How to deploy a Rails application on lighttpd

James Duncan Davidson has started a great series of recipes on deploying Rails applications. In Real Lessons for Rails Deployment, he examined the different options you have and some of the pitfalls you should watch out for.

In Deploying Rails with LightTPD, James goes specific and tells you exactly how to get Rails going on lighttpd using SwitchTower for deployment.

This is great stuff and with more than a couple of deployed Rails applications under his belt, James is in a great position to share his knowledge. Can’t wait to read the further installments.

Ask your questions to the Rails Weenie

Rick Olson has a great service running for people with questions about Rails development. The site is called Rails Weenie and allows you to ask questions to the community in a weblog-style fashion and then receive responses as comments. There’s already a lot of good content on there.

New book: Rails Recipes by Chad Fowler

Chad Fowler threw off his Enterprise shackles a while back and ventured into a new and better life doing Ruby on Rails full time. As the co-founder of RubyCentral, co-creator of RubyGems, and co-organizer of RubyConf and RailsConf, Chad is seriously well positioned to teach you a thing or two about Ruby and Rails.

And that’s exactly what Rails Recipes is all about. Small, concrete guides to doing specific things with Ruby on Rails. And at projected 350 pages, it’s going to be packed with goodies for sure. I’ll be working together with Chad to ensure that the recipes include a good number of 37signals favorites, so you can benefit from all the tips and tricks that make Basecamp, Backpack, and the rest of the suite sing.

Chad is aiming to have Rails Recipes out as a beta book on February 1st.

Rails training in Atlanta, Los Angeles, and Seattle

Marcel Molina’s Ruby on Rails Bootcamp was a sell-out smash hit at the Big Nerd Ranch a while back, so they’ve reeled him back in for another show going March 6th through 10th. Last time, Marcel even showed off lots of fancy new 1.1 features even before the official 1.0 release was dry. So you know its bound to be good next time as well.

But if Atlanta or a whole week isn’t your game, Geoffrey Grosenbach is doing a 3-day Rails training course in Seattle on January 23rd and Los Angeles on January 30th. Geoffrey is the man behind the Rails Podcast, Nuby on Rails, and the wonderful sparklines package.

Ruby for Rails: Ruby techniques for Rails developers

David A. Black is a pillar in the Ruby community, a co-founder of RubyCentral, toastmaster at RubyConf, and an all-round awesome Ruby programmer and friend. I’m very pleased to see that Manning went ahead with his “Ruby for Rails” proposal and now advertises the book for release in April.

This is an important book for the growth of Ruby on Rails as a platform. Lots of people are learning Rails first and then diving into Ruby as they need to. This book will target exactly that kind of people. Someone who’s getting into Ruby because of Rails and then wants to know more about the language as they progress.

Manning puts the pitch like this:

A new level of programming power and versatility awaits Ruby on Rails developers who master not only the conventions of Rails but the workings of the Ruby language itself. Because Rails itself and all Rails applications are written in Ruby, the knowledge of Ruby this book gives you will dramatically improve your Rails programming. You’ll gain an intimate understanding of how familiar Rails idioms actually work. And you’ll find expanded possibilities for your applications using custom-written Ruby.

The other great thing about this book is that it’ll most likely be available as a PDF. Like the Pragmatic Bookshelf, Manning has long been pushing ebooks, which means its one of the only publishers I’ll actually pick up titles from on a regular basis. Hopefully “Ruby for Rails” marks just the beginning of a broader selection that goes beyond the almost Java-exclusive focus they’ve had in the past.

So if this sounds intriguing, please do sign up to be alerted of the books release. I’m sure Manning is using interest like that to determine how to proceed with further projects in the Ruby world.

Enterprise Integration with Ruby by Maik Schmidt

Maik Schmidt is the contributor and maintainer of the DB2 database adapter for Active Record. He’s now also an author of Enterprise Integration with Ruby, which has just been released as a beta book under the Pragmatic Bookshelf.

Learn all about how to wire enterprise and legacy systems together using Ruby, databases, LDAP, XML, sockets, HTTP, web services, Web Services™, and more. There’s a free chapter on LDAP available, you can checkout the table of contents, and of course buy the beta book in PDF for $20 or at $37.45 for a paper-when-ready + PDF combo.

Way to go Maik.

Learn how to make Rails fast from a master

Stefan Kaes has been untiringly pushing for optimizations of Rails. Since the release of Rails 0.12.1, Stefan has lead an effort that made his own sample application no less than 4 times faster with Rails 0.14.×. Pretty impressive stuff.

Now he’s blogging about Rails performance in general at So be sure to subscribe to that feed if you care about a faster Rails. He already has suggestions and benchmarks up on sessions and pagination.

Compiling the MySQL C-bindings under Tiger

OS X 10.4 Tiger ships with GCC 4.0, which not all software is ready to accept a compilation by. The MySQL C-bindings is such a piece of software, so before doing “sudo gem install mysql” be sure that you do a “sudo gcc_select 3.3” (you can switch back afterwards, if you fancy).

New Rails movie with sound and sugar

The original Rails movie left jaws hanging and had developers all over the world stepping through it in slow motion to take it all in. But that was then. Rails 0.5 looks almost primitive from the eyes of a developer working with Rails 0.13. It was high time to rectify both that, the lack of narration, and the notion that Rails is all about Scaffolding.

So allow me to present: The New Rails Movie! It’s 50% longer, but shows at least 150% more. And you get my enthusiastic whoops! speak from the Brazilian FISL 6.0 conference where the movie premiered:

Many thanks to Pablo for providing me with the sound from the conference and many thanks to Audacity for making it something you could listen to.

Agile Web Development with Rails leaves beta

Our very first book on Rails is leaving beta and is in the process of going into print. Agile Web Development with Rails is now ready in its final form as a PDF and it’ll be ready in paper in time for OSCON. That’s pretty damn rocking!

And Dave Thomas slipped in a special treat in the PDF version now available:

One of the things I really like about the new PDF is the code hyperlinks. The little [File nn] lozenges in the margins next to code extracts are now live hyperlinks to the corresponding source file up on our media server. If you want to see the full code corresponding to an example, click, and it appears in your browser. (And, of course, all the code is available as a tarball or zip file.)

So for the two of you out there reading that haven’t yet bought in, now is the time!

IBM developerWorks introduces Rails with high praise

The top story on IBM developerWorks is none other than Fast-track your Web apps with Ruby on Rails. It’s a very nice, quick overview by example of why “Ruby on Rails is taking Web development by storm”, as David Mertz writes. He also has a particularly pleasing conclusion:

The best thing about Rails is that it fosters a whole “Rails way of thinking,” since it comes complete with all the supporting code you need. This is a big plus over other toolkits and frameworks that just give raw materials to work with. Rails development offers you a clear path from a half-formed idea to a fully functioning Web application.

Those conventions are more than just a better solution to configuration, it’s also a path through the jungle. Or a highway. Ah, no. A rail road. Yes, a rail road.

Ajax on Rails from O'Reilly (and high five from Slashdot!)

Curt Hibbs just have keeps delivering the good stuff and O’Reilly wisely keeps serving it up. The new article is called Ajax on Rails. It builds upon his two earlier articles about getting rolling and puts the focus on introducing the sugar-coated sweetness that is the Ajax support of Rails. There’s even a good rundown of what Ajax is and where it came from.

As has become the norm, Hibbs also secured Rails its fifth Slashdotting. Keep ‘em coming, Curt (and O’Reilly editors!).

FCGI-powered Rails on Windows 2003

Just because you’re forced to run Windows at work shouldn’t preclude you from getting jiggy with Ruby on Rails. The Windows crowd on the Rails mailing list have been working over time putting the pieces of the puzzle together and Boris have made a very nice write-up of how to repeat it.

Nice work indeed! Now. Can we get Rails running on my Sony PSP :)?

Beta book: Agile Web Development with Rails

The first Rails book is out — in beta. Agile Web Development with Rails is not scheduled to hit hardcopy before early August, but people need the information now. What to do? Let people have a peak into the kitchen and get a taste of the messy reality of pre-editing. So if you can live with spelling mistakes, bad page numbering, and possibly technical errors, you can have a taste at the master tome of the first wave of Rails books.

It’s more than 500 pages of tutorial and reference on the Rails framework. We build a complete e-commerce application and go through all the sub-frameworks of Rails. There’s even a good 30-paged chapter on how to take your application online. Which web server to pick, how to install FastCGI, and all that jazz.

Buy the beta book now and you get the final polished copy “for free”. We’d be double happy if you bought the combo-pack, which also includes the final hardcopy book — but doesn’t hand all the cash to distributors and Amazon.

The Pragmatic Bookshelf has a lot more Rails books lurking under the surface. The success of this first title will be a good indicator for how many gets the “go”. I’m sure other publishers are watching this thing closely too in order to determine their involvement. So let’s make this the home run title that grows the market above and beyond.

Fixing Ruby on OS X Tiger

Apple has done a great thing by including Ruby 1.8.2 in OS X 10.4, but unfortunately they stumbled just as they were to cross the finish line. Tiger has some deficiency that prevents it from installing native extensions properly. But there is quick room for remedy.

You can either grab the cool new Ruby on Rails installer for Tiger that fixes Ruby itselfs and installs RubyGems, FCGI, and Rails in one fell swoop. Or if you already have stuff like RubyGems and the Rails installed, you can just grab this correction gem:

sudo gem install fixrbconfig
sudo fixrbconfig

Curtsey of the RubyGems team.

5th Rails book announced (2nd from O'Reilly)

Robby Russell has announced his authorship of an upcoming book that’ll provide “… an in-depth look at RoR, how it works inside and out”. The book is to be published by O’Reilly. This will then be their second Rails book (they’re already doing a Developer’s Notebook) and the fifth book in total announced for Rails. What awesome news!

Hopefully we can get a nice mesh of complimentary books out of all these announcements. We’ll want the imminent sea of uptake to acquire the entire shelve of Rails book at the book store. Not worry about choosing.

Exploring Ruby on Rails in a conversation

Ara Howard and Doug Fales has a great article on Linux Journal exploring Rails through a conversation. They talk about how thinks work building a small blog engine and touches on many of the Ruby facilities that Rails employ to do its magic. They also talk a bit about why some of the reactions to Rails have been so explosive and what kind of fears that are triggered when new tech hits the street. Great stuff.

4th book coming: Rails Developer Notebook

O’Reilly is getting on board the Rails too. Their first book is going to be the Rails Developer Notebook, which as the name suggests is part of their Developer’s Notebooks series:

The Developer’s Notebook series is for early adopters of leading-edge technologies who want to get up to speed quickly on what they can do now with emerging technologies. If you’re a coder down to your core, and just want to get on with the job, then you want a Developer’s Notebook. Coffee stains and all, these books are from the minds of developers to yours, barely cleaned up enough for print.

The book is being coauthored by Bruce Tate (Bitter Java, Bitter EJB, more) and David Geary (Core JavaServer Faces, Core JSTL, more). The writing is supposed to start in April and the book should be out by June. So the focus is definitely to get something short out early and quickly.

If you’ve been following Rails advocacy, you may remember the name David Geary. I ripped into him fiercely about a month ago as he quickly dismissed Rails as being nothing but a CRUD scaffolder and declared “…you take this ROR koolaid. I’ll stick with the JSF flavor”.

Luckily, it didn’t take much more than two weeks for Geary to reconsider the dismissal and commit to looking closer at Rails. And now just a month later, he has signed on with Bruce Tate and O’Reilly to write a book about Rails!

What a fantastic and inspiring transformation. Hopefully Geary can serve as a role model for other Java developers who are feeling “…a bit nervous about this ROR thing”. Despite being heavily vested with Struts, Tiles, JSF, and Shale, he was able to see that there was amble room for a competing stack and jumped on to it.

My warmest welcomes to the Rails world, Geary! I wish Bruce Tate and you the best of luck with the Rails Developer Notebook and can’t wait to read it.

New book coming: Pragmatic Rails Recipes

I’m incredibly proud to announce the third Rails book in the making. The title is “Pragmatic Rails Recipes: A Guide to Elegant Web Development” and the authors should be very familiar to the Rails community: Marcel Molina (noradio) and Scott Barron (htonl). They’ve been around since the first release and are both integral parts of the Rails community through their programs, writing, and help on IRC.

The publisher is Dave Thomas’ progressive Pragmatic Bookshelf. The same umbrella that’ll carry the first Rails book to be published, Agile Web Development with Rails. This will of course ensure that the two books will become very complimentary and that they’ll both be available in my favorite reference book format: PDF.

It’s still very early in the process, the signatures on the contract is hardly dry, so the release target is tentative at best. Never the less, Scott and Marcel are aiming at October of this year. That’ll give the three books current announced a nice spread. Dave’s book around July, this one around October, and the German book around December/January.

That’s of course not to say that we can’t fit more books into the calendar. Quite the contrary. And from the handful of offers I’ve been getting from various authors and publishers, I’d be quite surprised if we didn’t see at least a couple of more Rails book announced this year.

Exciting times indeed.

Scott also talks about the book today.

Rolling with Ruby on Rails, Part 2

Curt Hibbs has invaded O’Reilly’s once more to follow up on his hugely popular (and Slashdot linked) article Rolling with Ruby on Rails. In this second part, he expands on the recipe application by adding additional manipulation tools and categories. The end of the article also contains a summary of the many Rails success stories and a peek at the many features Curt doesn’t have time to go into.

While Curt took a lot of flak for claiming Rails to be a silver bullet, it doesn’t seem to slow him down. In the conclusion, he writes:

Rails is not your run-of-the-mill, proof-of-concept web framework. It is the next level in web programming, and the developers who use it will make web applications faster than those who don’t; single developers can be as productive as whole teams. Best of all, it’s available right now, under an MIT license.

I believe that there hasn’t been an improvement in productivity like this in recent programming history.

Rails 0.10 on lighttpd without scaffolding video

Matt Moriarity has managed to do something I’ve been pledging for a long time: Record an updated video for Rails 0.10 using lighttpd and not“cheating” by using scaffolding. Very cool. He builds a small weblog all by hand and even stops to comment on the approach in text throughout.

Check it out Moriarity’s excellent video: Site 1, Site 2

I mistakenly attributed this to Stian Grytøyr in the original post. Sorry about that, Matt

Another tale about Rails scaling

TJ Vanderpoel is currently preparing a case study on how he scaled his mortgage processing application with a single lighttpd web server powered by a cluster of FastCGI application servers. All using Ruby on Rails. But as a counterpoint to the latest round of FUD’ing, he posted this preliminary tale about how his company is scaling Rails:

As far as scalability, apache with fcgi certainly isn’t the best option, for rails. In our environment we have one lighttpd process serving requests in a round-robin fashion from 10 to 100 fastcgi rails listeners. We move anywhere from 300 req/second to 1000 req/second with a dual opteron webserver and the fastcgi listeners can be well in back of the webserver. The only feature i’d like to see added to lighttpd is to be able to add fastcgi listeners on the fly, currently you have to restart the webserver to add listeners. Nonetheless, if you’d talked to rails developers you’d have learned lighttpd is the recommended hosting platform for production applications, as it takes care of many of the speed, and all of the scalability issues.

Vanderpoel should be ready with the full case study on his scaling adventure later this week.

Four Days on Rails

John McCreesh has published a great new 30+ paged tutorials for getting started with Rails entitled Four Days on Rails.

Rails is well documented on-line; in fact, possibly too well documented for beginners, with over 30,000 words of on-line documentation in the format of a reference manual. What’s missing is a roadmap (railmap?) pointing to the key pages that you need to know to get up and running in Rails development… Four Days on Rails is designed to fill that gap.

McCreesh’s has his own site for the book, but I’ve also taken the liberty to do a mirror for the book.

RubyGems 0.8.6 fixes critical error

So now that you just upgraded to RubyGems 0.8.5, please do so again to 0.8.6. The 0.8.5 version contained a bad bug that would render the rails command to create a new skeleton setup useless. Thankfully, the process is even easier than last time. Just one command: gem update --system.

Rails 0.10.0 loves lighttpd

With the release of Rails 0.10.0, the reign of Apache has finally ended and equal opportunity for all web servers has been introduced. The most important beneficial of this is lighttpd. The server describes itself as “…a secure, fast, compliant and very flexible web-server which has been optimized for high-performance environments” and is catching the attention of a lot of people lately.

Personally, I’ve been most interested in its FastCGI implementation that includes a load balancer component. But whether you need that or not, you owe it to yourself to check out lighttpd. Here’s a sample minimal configuration file needed to setup lighttpd to run a Rails application under FastCGI:

server.port = 8080
server.bind = ""
# Needed on OS X: server.event-handler = "freebsd-kqueue"
server.modules = ( "mod_rewrite", "mod_fastcgi" )
url.rewrite = ( "^/$" =>"index.html", "^([^.]+)$" =>"$1.html" )
server.error-handler-404 = "/dispatch.fcgi"
server.document-root = "/path/application/public"
server.errorlog      = "/path/application/log/server.log"
fastcgi.server = ( ".fcgi" => ( "localhost" => (
 "min-procs" => 1,  "max-procs" => 5,
 "socket"   =>"/tmp/application.fcgi.socket",
 "bin-path" =>"/path/application/public/dispatch.fcgi",
 "bin-environment" => ( "RAILS_ENV" =>"development" )
) ) )

This configuration is also to be found in the README file of new Rails installations.

Rails 0.10.0 is a Ruby 1.8.2 framework

It’s time to upgrade to Ruby 1.8.2, folks. Rails 0.10.0 includes various bits that require this version of Ruby, so if you want to run the latest Rails, you’ll have to get on the latest Ruby too. You’ll be glad you updated anyway. Ruby 1.8.2 contains a year’s worth of fixes, additions, and goodies from the Ruby masters. It’s an insult to them if don’t get jiggy with the goods (and Rails developers have other things to worry about that testing across old Ruby versions). Oh, when you upgrade, be sure to patch test/unit.

Understanding Model-View-Control

Rails is built upon the foundation of a model-view-control split of responsibilities. The MVC pattern can be quite bewildering if you’re coming from procedural PHP, other non-OOP environments, or are just starting out with programming. But now you can learn it all. Amy Hoy has written a great introduction to the pattern and how it relates to Rails: MVC: The Most Vexing Conundrum.

Rails application walk-through by Scott Baron

Scott Baron is walking through the process of creating an application “…used by a university cable television station to manage and generate schedules for their movie channels”. He’s doing it in several installments and the first two are already available. The first installment describes the background and the freshly published second installment walks through the creation of all the models in the system.

Scott promises that the next installment will focus on validations and unit tests and that the whole thing will be packaged as both HTML and PDF when its done. Great work, Scott!

Address book tutorial in Portuguese

Learn how to build an address book using Rails. Or, learn to read Portuguese, then learn how to build that address book. Regardless of whether you need step two of that or not, I’m told that Ronaldo Ferraz has done a fantastic job to present Rails. The introduction bit:

Rails é uma nova biblioteca para aplicações Web que está conquistando as mentes e os corações de desenvolvedores em todo o mundo por causa da flexibiidade e poder da mesma. Este tutorial apresenta a tecnologia e mostra como a mesma pode ajudar a produtividade de qualquer desenvolvedor.

Amen. Oh, and the whole thing is available as a 47-page PDF complete with loads of screenshots. Great local stuff indeed!

Really Getting Started in Rails

Amy Hoy is a designer, programmer, and writer digging into Rails. She read Curt Hibbs’ great introduction article on Rails at O’Reilly’s OnLAMP, but decided she’d like to decorate it a bit with why’s:

The only thing is, like all tutorials, it doesn’t always explain why. Why is that the syntax? What does that line mean, exactly? Why is the application designed so it fits together that way? Me, I like to know why—in reality, because of my designer brain, I have to know why to really grok it and retain it.

That decoration turned into a whole article entilted Really Getting Started in Rails that works very well as a companion to Hibbs’ original article. Great work, Amy!

Speeding up CGI access to Gem Rails

Jamis has a nice article demonstrating how he decreased the reload time from 2.4 seconds to just 1.1 seconds on CGI access to his Gem Rails application:

Rails’ preferred installation method is RubyGems, a convenient, powerful utility for installing Ruby libraries and applications. Unfortunately, that convenience comes at a price—loading a library via RubyGems adds some overhead. Recent releases of RubyGems have made some good progress in reducing that overhead, but it still exists.

If you’re running WEBrick or FastCGI for development, this is not an issue, though.

Rails on Lighttpd with FastCGI

Although Apache is the default choice of web server for Rails, it is by now means tied to it. Any web server that’s capable of doing a wee bit of rewriting in front and handling FastCGI applications can run Rails. Lighttpd is just one such web server.

If you’re interested in trying that out, TJ Vanderpoel has written an extensive tutorial on how to get Rails running with Lighttpd using FastCGI on Debian.

Setting up EliteJournal on TextDrive without a vhost

TextDrive is the official host for Ruby on Rails and as such gets all the action for cool integration efforts. We have a bunch in store that’ll turn the current state of “easy to get going” into “ridiculously easy to get flying”.

While that is cooking, Scott Baron has written up an excellent guide on how to install Elite Journal on TextDrive without using another vhost. He even created a testing blog just to prove it.

For those of you that don’t have a TextDrive account yet, I’d like to reiterate the point that this is one of the best ways to support the development of Rails (short of contributing patches or documentation).

They have some incredibly reasonable plans, an excellent environment for Ruby on Rails development, a staff that actually cares deeply about Ruby and Rails, and they’re contributing 50% of the profits on Rails signups to further development of the framework.

So if you’re still stuck elsewhere, now is the time to think about migrating.

And that concludes this shameless plug for TextDrive hidding behind the appearance of a documentation announcement.

Running rake tests with Ruby 1.8.2

If you’re among the early adopters of Ruby 1.8.2, you will have noticed that rake chokes when attempting to run all the tests in a suite. Thankfully, Dave Halliday was quick to device a fix, which you can apply right away while we await a new release of Rake from Jim Weirich.

Securing your Rails: Keep it secret, keep it safe

Andreas Schwarz has long been one of the most vocal speakers for making sure Rails could be keep the data of its applications secret and safe. So what could be more natural than for him to share his knowledge in a new Rails manual entitled Securing your Rails.

It so far includes three chapters on SQL Injection, Cross Site Scripting, and Creating records directly from form parameters.

It’s still a work in progress, but already packed with useful information.

Collaboa and EliteJournal joins the Trac

Reading code written by veterans has always been one of the best ways to learn the way of the arts. And of course, so is it with Rails, which is why I’m particularly pleased to see the trend of sharing your code using the fantastic Trac application take hold. In addition to open repositories for Hieraki and RForum, I’ve just today added another two:

Are you working on open source Rails software? Why not do it in the open. Get ahold of Trac and start sharing. You’ll make the list at in a split second.