When upgrading an app to a new version of Rails, it’s not always enough to update the gem versions in the Gemfile. The files created by the application generator—config files, default asset files, and so on—can also change from version to version. As part of the upgrade process, you generally want to update all those generated files to bring them in step with the newer versions.

To do that, you need a way to see the precise differences between the files generated by the version of Rails your app is currently using and the version of Rails to which you’re upgrading. We’ve done that in the past by generating apps using two different versions of Rails and running diffs between them. But lately we’ve been using railsdiff.org, which makes it much easier to compare the differences between any two Rails versions.

Here’s a quick set of steps for upgrading an app to any version of Rails:

  1. First, before changing anything, run all your tests and make sure they all pass. That way you know you’re starting with a good, solid baseline.

  2. When upgrading an app, it’s a good practice to make changes on a new code branch. Doing that insulates your changes from what’s going on in the master (production-ready) branch. And branching is just so easy with git that it’s hard to justify not doing it. So create a separate update-rails branch (call it whatever you like) and switch to it:

    $ git checkout -b upgrade-rails
    
  3. Now you’re ready to update the gem version numbers in your Gemfile and update all the generated files as necessary. Start by going to railsdiff.org and plugging in the version of Rails you’re currently using and the version you’re upgrading to. The site then generates a convenient report of all the file differences. For example, here are the diffs between Rails 4.0.0 and 4.0.5.

  4. Back in your application, apply the differences to each of the listed files by removing the red lines and adding the green lines. The differences between minor Rails versions are usually trivial and can be applied line by line. If a file has more than a couple lines changed and no app-specific customization, I typically just copy the newer version of the file in place of the older version. Either way, make sure to actually inspect each change and use it as an opportunity to understand how Rails is evolving.

  5. Since you’ve updated the gem versions in the Gemfile, next you need to install the updated gem dependencies:

    $ bundle update
    

    Bundler will install each of the gems listed in the Gemfile and the Gemfile.lock file will be updated with the specific gem versions required by the application.

  6. It’s also a good idea to update the generated scripts in the bin directory:

    $ rake rails:update:bin
    
  7. Now for the moment of truth. Re-run all your tests to make sure the update didn’t break anything! This would also be a good time to fire up the server and browse to http://localhost:3000/rails/info/properties to verify that the app is running the upgraded version of Rails.

  8. With the changes made and tested, add any new files and commit all the changes to the upgrade-rails branch:

    $ git add .
    $ git commit -m "Update generated files"
    

    If you want to review what you’ve changed, the differences between the upgrade-rails and master branches, use

    $ git diff master
    
  9. At this point you may need to resolve any deprecation warnings or update application-specific code to jibe with the new version of Rails. Just remember to commit any necessary changes to the upgrade-rails branch.

  10. Finally, when you’re all done making changes to the upgrade-rails branch, merge all the changes back into your master branch:

    $ git checkout master
    $ git merge upgrade-rails
    

Here’s hoping this helps you stay on top of new Rails versions, and update with confidence!