Upgrading a Rails 3.0 project to Rails 3.1

I’ve just upgraded an old Ruby on Rails 3.0 project to the current 3.1 build.  Having expected ours of pain I was very pleased to discover that it’s all terribly easy.  Here’s the step by step (as ever YMMV depending on gems you have installed).

1. Open your gemfile and replace gem ‘rails’, ‘3.0.0’ with  gem ‘rails’, ‘3.1.3’.  3.1.3 being the latest build at the time of writing.
2. If you want to use the new asset pipeline hotness in 3.1 (and why wouldn’t you?) you need to add a new section at the bottom of the file:

   group :assets do
     gem 'sass-rails', "  ~> 3.1.0"
     gem 'coffee-rails', "~> 3.1.0"
     gem 'uglifier'
   end

3. Now open up your command line and run a bundle install. You may need to delete gemfile.lock.
4. The next step is to run rake rails:update.  The first time I did this I got the error “uninitialized constant ActionView::Helpers::JavaScriptProxy”.  To resolve this I removed jrails from my gemfile as Rails 3.1 uses jQuery anyway.  I then re-ran the rake command.
5. The Rails update will generate a bunch of conflicts.  I did the following (make sure you use the diff option to check for yourself!):
   • boot.rb – overwrite.
   • routes.rb – do not overwrite.
   • application.rb – do not overwrite. We’ll patch this up manually next.
   • development.rb – do not overwrite. You might be able to get away with overwriting this, but I have settings I need in here.
   • production.rb – do no overwrite. Again, I have settings I need in here.
   • test.rb – overwrite. I didn’t have any special settings here, but use the diff to check yours!
   • secret_token.rb – overwrite.
   • session_store.rb – overwrite.
   • en.yml – do not overwrite.
6. Now we need to make a few changes that would have been made if we let Rails overwrite our files. Open up config/application.rb and add the following:

   # Enable the asset pipeline
   config.assets.enabled = true
   
   # Version of your assets, change this if you want to expire all your assets
   config.assets.version = '1.0'

7. Open up config/environments/development.rb, remove “config.action_view.debug_rjs = true”and add the following:

   # Do not compress assets
   config.assets.compress = false
   
   # Expands the lines which load the assets
   config.assets.debug = true

8. Open up config/environments/production.rb and add:

   # 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

9. Create a new assets folder in app and then add images, javascripts and stylesheets and sub-directories.  Move your CSS, JS and image files into these directories.
10. You’ll have to do some work to cleanup your assets and how they are included in your layouts – but that’s very much an exercise for the reader :)