Upgrading Rails 2 from 2.3.8 through 2.3.18 to Rails LTS

This card shows how to upgrade a Rails 2 application from Rails 2.3.8 through every single patch level up to 2.3.18, and then, hopefully, Rails LTS.

2.3.8 to 2.3.9

This release has many minor changes and fixes to prepare your application for Rails 3.

Step-by-step upgrade instructions:

0. Upgrade rails gem
1. Change your environment.rb so it says RAILS_GEM_VERSION = '2.3.9'
2. Change your environment.rb so all invocations of config.load_paths become config.autoload_paths
3. If you are using rails_xss Show archive.org snapshot , you need to upgrade by deleting the existing plugin directory and calling script/plugin install https://github.com/rails/rails_xss.git
4. If you are using the native Rails I18n API, open all your config/locales/*.yml files and change the old placeholder style 'Delete {{count}} users?' to the new style 'Delete %{count} users?' -- When using VIM you can use this command: :%s/{{\([^\}]*\)}}/%{\1}/cg
5. Fix deprecation warnings with :overwrite_params
6. Run tests
7. Deploy

See the commit log Show archive.org snapshot for a detailed list of changes.

2.3.9 to 2.3.10

Fixes Vulnerability in Nested Attributes code Show archive.org snapshot .

Step-by-step upgrade instructions:

0. Upgrade rails gem
1. Change your environment.rb so it says RAILS_GEM_VERSION = '2.3.10'
2. Run tests
3. Deploy

Also see commit log Show archive.org snapshot .

From 2.3.10 to 2.3.11

Fixes multiple security issues.

Step-by-step upgrade instructions:

0. Upgrade rails gem

1. Change your environment.rb so it says RAILS_GEM_VERSION = '2.3.11'

2. Add <%= csrf_meta_tag %> into your layout's head

3. Put this into a JavaScript file that is always loaded (like your application.js -- or another file you add to the javascript_include_tag):

   • For Prototype: \
     ^
     Ajax.Responders.register({
     onCreate: function(request) {
     var csrf_meta_tag = $$('meta[name=csrf-token]')[0];
     if (csrf_meta_tag) {
     var header = 'X-CSRF-Token',
     token = csrf_meta_tag.readAttribute('content');
     if (!request.options.requestHeaders) {
     request.options.requestHeaders = {};
     }
     request.options.requestHeaders[header] = token;
     }
     }
     });
   • For jQuery: \
     ^
     $(document).ajaxSend(function(e, xhr, options) {
     var token = $("meta[name='csrf-token']").attr("content");
     xhr.setRequestHeader("X-CSRF-Token", token);
     });

4. Any invalid requests will cause a reset_session. So if your application provides any "remember me" feature that does not store its information in the session you also need to take care that users are signed out when Rails does not receive a valid token. Rails 2.3.11 calls handle_unverified_request for this which you need to overwrite with your logic, like this:

Copy       def handle_unverified_request
         super # call the default behaviour which resets the session 
         cookies.delete :remember_token
       end

5. Run tests

6. If you have non-GET Ajax parts that are not tested via selenium (or alike) toy around with the application to see if they still work and that you do not get signed out.

7. If you want to check if you get signed out when omitting the CSRF token for a non-GET request, you could remove the csrf_meta_tag from the head and call something like this (Prototype example here):

   Copynew Ajax.Request('/admin/users', { method: 'POST', onComplete: function() { alert('complete'); } });
   

8. Until Rails 2.3.12 is out, you will need to copy this initializer into your project, in order to fix a bug in Rails 2.3.11.

9. Run tests

10. Deploy

See the commit log Show archive.org snapshot for a detailed list of changes.

From 2.3.11 to 2.3.12

Fixes security issues with the rails_xss plugin.

Step-by-step upgrade instructions:

0. Upgrade rails gem
1. Change your environment.rb so it says RAILS_GEM_VERSION = '2.3.12'
2. Upgrade rails_xss plugin (if you are using that)
3. Run tests
4. Deploy

See the commit log Show archive.org snapshot for a detailed list of changes.

From 2.3.12 to 2.3.13

Version 2.3.13 has been yanked Show archive.org snapshot . Please upgrade directly to 2.3.14.

See the commit log Show archive.org snapshot for a detailed list of changes.

From 2.3.12 to 2.3.14

Fixes many critical vulnerabilities.

Step-by-step upgrade instructions:

0. Upgrade rails gem

1. Change your environment.rb so it says RAILS_GEM_VERSION = '2.3.14'

2. Run tests

3. Deploy

4. Add <%= csrf_meta_tag %> into your layout's head

5. Put this into a JavaScript file that is always loaded (like your application.js -- or another file you add to the javascript_include_tag):

   • For Prototype: \
     ^
     Ajax.Responders.register({
     onCreate: function(request) {
     var csrf_meta_tag = $$('meta[name=csrf-token]')[0];
     if (csrf_meta_tag) {
     var header = 'X-CSRF-Token',
     token = csrf_meta_tag.readAttribute('content');
     if (!request.options.requestHeaders) {
     request.options.requestHeaders = {};
     }
     request.options.requestHeaders[header] = token;
     }
     }
     });
   • For jQuery: \
     ^
     $(document).ajaxSend(function(e, xhr, options) {
     var token = $("meta[name='csrf-token']").attr("content");
     xhr.setRequestHeader("X-CSRF-Token", token);
     });

6. Any invalid requests will cause a reset_session. So if your application provides any "remember me" feature that does not store its information in the session you also need to take care that users are signed out when Rails does not receive a valid token. Rails 2.3.11 calls handle_unverified_request for this which you need to overwrite with your logic, like this: \
   def handle_unverified_request
   super # call the default behaviour which resets the session
   cookies.delete :remember_token
   end

7. Run tests

8. If you have non-GET Ajax parts that are not tested via selenium (or alike) toy around with the application to see if they still work and that you do not get signed out.

9. If you want to check if you get signed out when omitting the CSRF token for a non-GET request, you could remove the csrf_meta_tag from the head and call something like this (Prototype example here):

   Copynew Ajax.Request('/admin/users', { method: 'POST', onComplete: function() { alert('complete'); } });
   

10. Until Rails 2.3.12 is out, you will need to copy this initializer into your project, in order to fix a bug in Rails 2.3.11.
    See the commit log Show archive.org snapshot for a detailed list of changes (Diff starts with 2.3.12 because 2.3.13 was yanked, see above).

From 2.3.14 to 2.3.15

Fixes many extremely critical vulnerabilities.

Step-by-step upgrade instructions:

0. Upgrade rails gem
1. Change your environment.rb so it says RAILS_GEM_VERSION = '2.3.15'
2. Run tests
3. Deploy

See the commit log Show archive.org snapshot for a detailed list of changes.

From 2.3.15 to 2.3.16

Fixes an extremely critical vulnerability.

Step-by-step upgrade instructions:

0. Upgrade rails gem
1. Change your environment.rb so it says RAILS_GEM_VERSION = '2.3.16'
2. Run tests
3. Deploy

See the commit log Show archive.org snapshot for a detailed list of changes.

From 2.3.16 to 2.3.17

Fixes several serious vulnerabilities.

Step-by-step upgrade instructions:

0. Upgrade json gem to atleast 1.7.7, 1.6.8, or 1.5.5
1. Upgrade rails gem
2. Change your environment.rb so it says RAILS_GEM_VERSION = '2.3.17'
3. Run tests
4. Deploy

See the commit log for a detailed list of changes.

From 2.3.17 to 2.3.18

Fixes several important security fixes.

Step-by-step upgrade instructions:

1. Upgrade rails gem
2. Change your environment.rb so it says RAILS_GEM_VERSION = '2.3.18'
3. Run tests
4. Deploy

See the commit log Show archive.org snapshot for a detailed list of changes.

From 2.3.18 to Rails LTS

Support for Rails 2 has ended. You should switch to Rails LTS.

See Rails LTS installation instructions.