Upgrade Rails from 3.0 to 3.1

This is part of our Upgrade Rails series opens a new window . We will be covering the most important aspects that you need to know to update your Ruby on Rails opens a new window application from version 3.0 opens a new window to 3.1 opens a new window . If you are in an older version, you can take a look at our previous article opens a new window .

1. Preparations
2. Ruby version
3. Tools
4. Config files
5. jQuery
6. Asset Pipeline
7. Next steps

1. Preparations

Before beginning with the upgrade process, we have some recommended preparations:

• Your Rails app should have the latest patch version opens a new window before you move to the next major/minor version.
• You should have at least 80% test coverage unless you have a dedicated QA team.
• Follow a Git flow workflow to actively manage at least two environments: staging and production.
• Check your Gemfile.lock for incompatibilities by using RailsBump opens a new window .
• Create a dual boot mechanism, the fastest way to do this is installing the handy gem next_rails opens a new window .

For full details check out our article on How to Prepare Your App for a Rails Upgrade opens a new window .

2. Ruby version

Rails 3.1 requires Ruby 1.8.7 opens a new window or higher, but no more than 1.9.3 opens a new window . If you want to use Ruby 1.9.x, we recommend you skip directly to 1.9.3. Also Ruby 1.9.1 opens a new window is not usable because it has segmentation faults on Rails 3.1. That means that the compatible Ruby versions opens a new window for Rails 3.1 are 1.8.7, 1.9.2 opens a new window , or 1.9.3. Keep in mind that the next Rails version (3.2) will be the last one that supports Ruby 1.8.7 and 1.9.2.

3. Tools

Rails 3.1 comes with a generator that helps the upgrade process. You just need to run rake rails:update to see a guide opens a new window that details how to upgrade your application.

Sometimes it’s also useful to check which files changed between two specific versions of Rails. Fortunately Rails Diff opens a new window makes that easy.

4. Config files

• You should remove any references to ActionView::Base.debug_rjs in your project.

# (config/environments/development.rb)

config.action_view.debug_rjs = true

• If you want to wrap parameters into a nested hash add a config/initializers/wrap_parameters.rb file with the following contents. This file comes by default in new applications.

# Be sure to restart your server when you modify this file.
# This file contains settings for ActionController::ParamsWrapper which
# is enabled by default.

# Enable parameter wrapping for JSON. You can disable this by setting :format to an empty array.
ActiveSupport.on_load(:action_controller) do
  wrap_parameters :format => [:json]
end

# Disable root element in JSON by default.
ActiveSupport.on_load(:active_record) do
  self.include_root_in_json = false
end

5. jQuery

jQuery opens a new window is the default JavaScript library that comes with Rails 3.1.

To add this you need to include the jquery-rails opens a new window gem in your Gemfile opens a new window

gem 'jquery-rails'

And then include the libraries in your app/assets/javascripts/application.js

//= require jquery
//= require jquery_ujs

So now you can get rid of your jQuery assets like jquery.js or jquery.min.js.

6. Asset Pipeline

Asset Pipeline opens a new window is an optional feature in Rails 3.1, but we recommend to include it to take advantage of it. In order to do that, you should apply the following changes:

• Add to your Gemfile:

group :assets do
  gem 'sass-rails',   "~> 3.1.5"
  gem 'coffee-rails', "~> 3.1.1"
  gem 'uglifier',     ">= 1.0.3"
end

• Update your config/application.rb

config.assets.enabled = true
config.assets.version = '1.0'

# Defaults to '/assets'
config.assets.prefix = '/asset-files'

• Update your config/environments/development.rb

# Do not compress assets
config.assets.compress = false

# Expands the lines which load the assets
config.assets.debug = true

• Update your config/environments/production.rb

# Compress JavaScripts and CSS
config.assets.compress = true

# Don't fallback to assets pipeline if a precompiled asset is missed
config.assets.compile = false

# Generate digests for assets URLs
config.assets.digest = true

# Defaults to Rails.root.join("public/assets")
# config.assets.manifest = YOUR_PATH

# Precompile additional assets (application.js, application.css, and all non-JS/CSS are already added)
# config.assets.precompile = %w( admin.js admin.css )

• Update your config/environments/test.rb

# Configure static asset server for tests with Cache-Control for performance
config.serve_static_assets = true
config.static_cache_control = "public, max-age=3600"

7. Next steps

After you get your application properly running in Rails 3.1, you will probably want to keep working on this Rails upgrade journey. So don’t forget to check our complete Rails upgrade series opens a new window to make that easy.

If you’re not on Rails 3.1 yet, we can help! Download our free eBook: The Complete Guide to Upgrade Rails opens a new window .