next_rails

Using next_rails... or How to Stay Sane While Upgrading Rails to the Next Major/Minor Version

With the help of next_rails, a toolkit to upgrade Rails application, we can easily upgrade Rails to the next major/minor version. In Rails version upgrades, issues are often arising due to upstream changes like the removal of deprecated features. Instead of addressing issues in a single pull request, next_rails allows us to do so in multiple pull requests. It makes the whole upgrade process easier to review and more approachable.

How next_rails Works

next_rails is just like any other gem in the Gemfile. Once installed, we set it up with next --init and this command slightly changed the Gemfile while also creating a new file Gemfile.next. This new file is a symlink to Gemfile. The following changes were introduced:

def next?
  File.basename(__FILE__) == 'Gemfile.next'
end

if next?
  gem 'rails', '~> 6.1'
else
  gem 'rails', '~> 6.0'
end

To run Bundler with the next Rails version, you can prefix any Bundler call with next like next bundle install or next bundle exec rails s. This will use the gems defined in Gemfile.next.lock, not in Gemfile.lock.

How to Write Code for the Next Rails Version

In the RailsVersion module, we define a module method for the next Rails version:

# Example for Rails 6.1.x
def self.is_6_1?
  Rails::VERSION::MAJOR == 6 && Rails::VERSION::MINOR == 1
end

With this module, we can then check in a guard clause if the application is currently running with the next Rails version:

if RailsVersion.is_6_1?
  # code for the next Rails version
else
  # code for the current Rails version
end

While we are tackling the various issues arising from the next Rails version upgrade, we keep those guard clauses around and everything will keep working as usual in the current Rails version.

To have the continuous integration test your changes, be sure to prefix your branch name with next_rails-. This branch has to be upstream, so pushed directly to https://github.com/openSUSE/open-build-service, not to your fork.

How to Roll Out the Next Rails Version

We can safely upgrade the Rails version in the Gemfile once all issues arising from the next Rails version have been addressed. The code for the newly upgraded Rails version is kept and the guard clauses with its code for the previous Rails version can then be removed.

How to Keep Gemfile.next.lock Up-to-Date

The version of Rails and other gems tracked in Gemfile.next.lock have to be updated from time to time to follow the dependency updates happening on the default Gemfile.lock. This is how you can achieve this:

1. Overwrite Gemfile.next.lock with a copy of Gemfile.lock:

cp src/api/Gemfile.lock src/api/Gemfile.next.lock

2. Inside your development environment, update the Rails version:

next bundle update rails

3. Cache the new gems from Gemfile.next.lock:

This is needed for the CI since we use bundler install --local.

next bundle cache

4. Commit and push the changes to an upstream branch with the next_rails- prefix, then submit a pull request.