h2. A Guide for Upgrading Ruby on Rails

This guide provides steps to be followed when you upgrade your applications to a newer version of Ruby on Rails. These steps are also available in individual release guides.

endprologue.

h3. Rails Upgrades

When you're upgrading an existing application, it's always a great idea to have good test coverage before going in. Rails 3 and above requires Ruby 1.8.7 or higher. Support for all of the previous Ruby versions has been dropped officially and you should upgrade as early as possible. Rails 3.2.x will be the last branch to support 1.8.7 and Rails 4 (current edge) will support only Ruby 1.9.3.

TIP: Note that Ruby 1.8.7 p248 and p249 have marshaling bugs that crash Rails. Ruby Enterprise Edition has these fixed since the release of 1.8.7-2010.02. On the 1.9 front, Ruby 1.9.1 is not usable because it outright segfaults, so if you want to use 1.9.x, jump on to 1.9.2 or 1.9.3 for smooth sailing.

h3. Upgrading from Rails 3.1 to Rails 3.2

We recommend that you first upgrade to Rails 3.1 in case you haven't and make sure your application still runs as expected before attempting an update to Rails 3.2. 

The following changes are meant for upgrading your application to Rails 3.2.1, the latest 3.2.x version of Rails.

h4(#gemfile3_2). Gemfile

Make the following changes to your +Gemfile+.

<ruby>
gem 'rails', '= 3.2.1'

group :assets do
  gem 'sass-rails',   '~> 3.2.3'
  gem 'coffee-rails', '~> 3.2.1'
  gem 'uglifier',     '>= 1.0.3'
end
</ruby>

h4(#config_dev3_2). config/environments/development.rb

* There are a couple of new configuration changes you'd want to add:

<ruby>
# Raise exception on mass assignment protection for Active Record models
config.active_record.mass_assignment_sanitizer = :strict

# Log the query plan for queries taking more than this (works
# with SQLite, MySQL, and PostgreSQL)
config.active_record.auto_explain_threshold_in_seconds = 0.5
</ruby>

h4(#config_test3_2). config/environments/test.rb

The <tt>mass_assignment_sanitizer</tt> config also needs to be added in <tt>config/environments/test.rb</tt>:

<ruby>
# Raise exception on mass assignment protection for Active Record models
config.active_record.mass_assignment_sanitizer = :strict
</ruby>

h4(#plugins3_2). vendor/plugins

* Rails 3.2 deprecates <tt>vendor/plugins</tt> and Rails 4.0 will remove them completely. You can start replacing these plugins by extracting them as gems and adding them in your Gemfile. If you choose not to make them gems, you can move them into, say, <tt>lib/my_plugin/*</tt> and add an appropriate initializer in <tt>config/initializers/my_plugin.rb</tt>.

h3. Upgrading from Rails 3.0 to Rails 3.1

We recommend that you first upgrade to Rails 3.0 in case you haven't and make sure your application still runs as expected before attempting an update to Rails 3.1. 

The following changes are meant for upgrading your application to Rails 3.1.3, the latest 3.1.x version of Rails.

h4(#gemfile3_1). Gemfile

Make the following changes to your +Gemfile+.

<ruby>
gem 'rails', '= 3.1.3'
gem 'mysql2'

# Needed for the new asset pipeline
group :assets do
  gem 'sass-rails',   "~> 3.1.5"
  gem 'coffee-rails', "~> 3.1.1"
  gem 'uglifier',     ">= 1.0.3"
end

# jQuery is the default JavaScript library in Rails 3.1
gem 'jquery-rails'
</ruby>

h4(#config_app3_1). config/application.rb

* The asset pipeline requires the following additions:

<ruby>
config.assets.enabled = true
config.assets.version = '1.0'
</ruby>

* If your application is using the "/assets" route for a resource you may want change the prefix used for assets to avoid conflicts:

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

h4(#config_dev3_1). config/environments/development.rb

* Remove the RJS setting <tt>config.action_view.debug_rjs = true</tt>.

* Add the following, if you enable the asset pipeline.

<ruby>
# Do not compress assets
config.assets.compress = false

# Expands the lines which load the assets
config.assets.debug = true
</ruby>

h4(#config_prod3_1). config/environments/production.rb

* Again, most of the changes below are for the asset pipeline. You can read more about these in the "Asset Pipeline":asset_pipeline.html guide.

<ruby>
# 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( search.js )

# Force all access to the app over SSL, use Strict-Transport-Security, and use secure cookies.
# config.force_ssl = true
</ruby>

h4(#config_test3_1). config/environments/test.rb

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

h4(#config_wp3_1). config/initializers/wrap_parameters.rb

* Add this file with the following contents, if you wish to wrap parameters into a nested hash. This is on by default in new applications.

<ruby>
# 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
</ruby>