Money Forward Developers Blog

How to Approach new_framework_defaults in Rails

This article is a translated version of a Japanese blog post originally written by the author.

Hello, I’m pocke, an engineer working on Money Forward Cloud Accounting Plus.

In this post, I’ll explain how to deal with new_framework_defaults in Rails. I’ve recently been working on upgrading Rails, and through that process, I had the opportunity to think about how to handle this setting. This article is a summary of what I learned.

What is new_framework_defaults?

Let’s first look at what  new_framework_defaults actually refers to.

In this article, the term “ new_framework_defaults” collectively refers to the following two elements:

  • The  Rails::Application::Configuration#load_defaults method
  • The  config/initializers/new_framework_defaults_*.rb files

These are provided to help make Rails upgrades smoother.

Let’s go into more detail about each.

Rails::Application::Configuration#load_defaults

The  load_defaults method loads the default settings for a specified Rails version. You’ll typically see it written like this in  config/application.rb:

module AppName
  class Application < Rails::Application
    # Initialize configuration defaults for originally generated Rails version.
    config.load_defaults 7.0

This ensures that, regardless of the Rails gem version installed, the default settings for Rails 7.0 will apply to this application.

The version specified here corresponds to the Rails version used when you originally ran  rails new. Even when you update the Rails gem and run  bin/rails app:update, this value does not change automatically. You must update it manually if needed.

config/initializers/new_framework_defaults_*.rb

These files are generated every time you upgrade to a new minor (or major) Rails version. For example, upgrading from Rails 6.1 to 7.0 will generate a file called  config/initializers/new_framework_defaults_7_0.rb via  bin/rails app:update.

Initially, all contents in this file are commented out—so loading the file as-is has no effect.

The file contains all the configuration items whose default values have changed in the new version. Uncommenting a line will apply the new version’s default for that setting.

How these two elements work together

By combining these two elements, you can perform Rails upgrades more smoothly. Let’s walk through an example of upgrading from Rails 6.1 to 7.0.

First, update your Rails version from 6.1 to 7.0 and run  bin/rails app:update. This will generate the  new_framework_defaults_7_0.rb file. At this point, all default settings remain as they were in Rails 6.1. That’s because  config.load_defaults still points to 6.1, and the initializer file is fully commented out.

To actually apply the new defaults from Rails 7.0, you need to either pass  7.0 to  load_defaults, or uncomment lines in the  new_framework_defaults_7_0.rb file.

This separation allows you to update the Rails version and apply new defaults at different times, minimizing the changes introduced at once.

How to handle new_framework_defaults

So, how should you manage these settings? Here’s my recommended process after upgrading Rails:

  1. Complete the version upgrade (e.g., upgrade from Rails 6.1 to 7.0).
    • Do not modify the new_framework_defaults_X_Y.rb file during the upgrade.
  2. Carefully go through each item in new_framework_defaults_X_Y.rb and do one of the following:
    • If you can enable the new setting: uncomment the line.
    • If not: remove the line from the initializer and explicitly configure the current behavior in config/application.rb or another initializer.
  3. Once all items have been handled: delete the initializer and update the  load_defaults version in  config/application.rb.

Let’s go into each step in more detail.

1. Complete the Rails upgrade

First, get your application running on the new Rails version. This article does not cover the specifics of how to perform a Rails upgrade.

At this point, you don’t need to touch load_defaults or the new_framework_defaults_X_Y.rb file. You can make changes now, but deferring them helps limit the scope of changes per step.

2. Review and handle each item in new_framework_defaults_X_Y.rb

Once the upgrade is complete, review each setting in the new_framework_defaults_X_Y.rb file. There are two options depending on whether you can adopt the new default.

Each item is usually accompanied by comments and often includes links for more information. Use these to understand what the new setting does and whether it fits your app.

Settings can be applied individually. If you want to minimize risk, you can deploy changes one setting at a time.

If you can enable the new setting

Uncomment the line in new_framework_defaults_X_Y.rb to apply the new default. These lines are the new defaults, so uncommenting them aligns your app with the new Rails behavior.

If you can’t enable the new setting

In some cases, your application may not be compatible with a new default. If so, explicitly configure the existing behavior.

First, find the current value in your app, then write it out explicitly in config/application.rb (below the load_defaults line) or in another initializer under config/initializers/.

Once written out, remove the commented-out line from new_framework_defaults_X_Y.rb.

This doesn’t change the behavior of your application—it simply makes the configuration explicit. This is important for the next step.

While this approach may be necessary in some cases, it is generally recommended to enable the new setting whenever possible to keep your application aligned with the latest Rails defaults.

3. Once all settings are handled, delete the file and update load_defaults

After all items in new_framework_defaults_X_Y.rb are either enabled or moved elsewhere, you’re ready to finish the migration.

Delete the new_framework_defaults_X_Y.rb file and update the version argument in config.load_defaults in config/application.rb to the target Rails version.

This step doesn’t change behavior because you’ve already prepared for the version update in earlier steps. Therefore, this final step is relatively safe.

Goals of this approach

Here’s a brief summary of why I recommend this method:

Fine-grained upgrade process

It separates the Rails version upgrade from the default setting changes. You can also apply each configuration change independently.

This keeps each deployment or pull request small and focused. As a result, it becomes easier to review changes and to roll them back safely if necessary.

No leftover files

I treat new_framework_defaults_X_Y.rb as a temporary migration file. Once all items are addressed, I delete it.

This keeps your codebase clean and avoids leaving behind outdated migration artifacts.

Easy to understand status

While making changes, new_framework_defaults_X_Y.rb contains only the settings that still need attention. This makes it easy to track your progress.

Once there are no commented-out lines left, the migration is done.

Treating the file like a TODO list has made the process clearer.

Conclusion

This article explained how to handle configuration changes during a Rails upgrade. I hope it proves helpful the next time you upgrade Rails. If your load_defaults is still set to an old version, this guide can also help you modernize your app’s configuration.

References

Published-date