Upgrading to Rails 1.0

Rails 1.0 introduces several changes which affect your 0.13.1 applications. We’ll examine each of them then walk through the upgrade.

We won’t need this guide next time: with 1.0 your apps are easier to configure, have a host of plugins available, and much of the “glue” code that makes up a new application has been pushed down into Rails itself. Future updates will end at gem install rails.

For the patient: read the release notes to learn more about what’s cooking in 1.0.

Upgrading to Rails 1.0

Getting Started

Rails 1.0 introduces several changes which affect your 0.13.1 applications. We’ll examine each of them then walk through the upgrade.

We won’t need this guide next time: with 1.0 your apps are easier to configure, have a host of plugins available, and much of the “glue” code that makes up a new application has been pushed down into Rails itself. Future updates will end at gem install rails.

For the patient: read the release notes to learn more about what’s cooking in 1.0.

Changes

Configuration

Application configuration is more friendly. config/environment.rb and config/environments/* are no longer littered with obscure options and Rails-specific initialization code. They are purely for your configuration.

The new config/environment.rb has about a dozen lines of configuration options with their defaults commented out. These config.option lines are specified within the Rails initializer, a new class which manages your application’s configuration, loading, and startup.

The new config/environments/*.rb follow this lead: each is a handful of configuration options which are evaluated within the Rails initializer.

Some utilities, such as Rake, don’t always need your entire application and the Rails framework to perform their tasks, so loading the heavyweight config/environment.rb is unnecessary. Enter config/boot.rb, just the barest essentials to set your app’s load path and load the Rails initializer. You should never need to edit boot.rb (it’s only 8 lines), but it’s worth knowing that it’s there.

Rakefile

Like config/environment.rb, the heavyweight Rakefile has been refactored into smaller sets of tasks which are built in to Rails, paring the old 180 lines down to a svelte 6.

The new Rakefile automatically includes lib/tasks/*.rake. If you have modified your Rakefile, move your changes to a file with the .rake extension in the lib/tasks directory.

Testing

Two defaults which affect the way your tests are run have changed in Rails 1.0: transactional fixtures have switched on and instantiated fixtures have switched off. These settings vastly improve test speed, particularly if your tests use many fixtures.

However, if your application relies on the old defaults, upgrading to 1.0 will break your tests. Test methods which use fixture instance variables like @jamis must use the fixture reader method people(:jamis).

Thankfully, you can get a head start on 1.0 by preparing your 0.13.1 application now. Set self.use_instantiated_fixtures = false and self.use_transactional_fixtures = true in test/test_helper.rb, get your tests passing, and you’re one step closer to a painless upgrade.

Mike Clark has written an excellent article on how and why these changes affect you.

Scripts

The executable scripts in your application’s scripts directory are now stubs which delegate to Rails, so the next time you upgrade Rails you’ll get the new scripts without modifying your application at all.

Almost Ready

Gotchas

• ActiveRecord::Base.find options are strictly validated, so calls to Account.find(:all, :condition => ...) will raise an exception on :condition, which should be :conditions.

• The :conditions finder option is wrapped in parentheses in the generated SQL to ensure correct precedence. If you rely on e.g. :conditions => 'foo > 1 order by foo desc' being passed directly into the SQL query, your app will break in 1.0. Use :conditions => 'foo > 1', :order => 'foo desc' instead.

• link_to :controller => nil, :action => 'join' will fail since you are specifically saying that you don’t want a controller, which usually doesn’t make any sense. Instead, omit the :controller option to use the current controller. Also, you may prefer the tidiness of named routes for your linking needs.

• 0.blank? is now false instead of true, so validates_presence_of now works as you expect for checkboxes using 0/1 and text fields where 0 is a valid entry. However, any code that relies on 0.blank? == true now needs to check whether number.zero? as well.

Performing the Upgrade

Getting Started

Make a backup or use version control. Upgrading is simple, but simple mistakes hurt.

• Rakefile
• config/environment.rb
• config/environments/*
• scripts/*

For a quick look at how the upgrade will affect your app, run the rails command on your application directory with the --pretend option:

$ cd /path/to/my/app
$ rails --pretend .

Without Version Control

Make a backup, run the rails command, and reapply any customizations you made:

$ cd /path/to/myapp
$ cd ..
$ cp -r myapp myapp_backup
$ rails myapp

You can use a diff tool to examine the differences between myapp and myapp_backup. On Windows, use a graphical diff/merge tool. On Mac, Linux, *BSD, and others:

$ diff -Naur myapp_backup myapp

You’re done when your tests pass:

$ rake test

With Subversion

$ cd /path/to/my/apps/svn/checkout
$ svn commit -m "Before Rails 1.0" 
$ rails .
$ svn diff

$ rake test
[...]
$ svn commit -m "Woohoo, upgraded to Rails 1.0"

That’s All, Folks

Congratulations, you’ve upgraded your app to Rails 1.0!

Read the release notes to start working with Migrations, SwitchTower, plugins, and more.

If you’re having trouble upgrading your application, we can help! Post to the Rails mailing list or ask in the Rails IRC channel.