Overview

In the talk "Rails Framework Defaults: Defusing the Time Bomb in Your Upgraded App" from RailsConf 2025, Josh Puetz explains a crucial but often overlooked step in the Rails upgrade process: handling and upgrading Rails framework defaults. While most tutorials focus on getting a new version running, Puetz advocates completing the process by addressing framework defaults to prevent future issues.

Main Topic

The core theme is that upgrading your Rails version is not truly finished until you've updated your app's framework defaults, which helps avoid potential breakages and keeps the app aligned with best practices and security standards.

Key Points

• What Are Rails Framework Defaults?

  • Defaults are suggested configuration settings provided by the Rails team.
  • They control Rails’ behavior across various components like ActiveRecord and ActionView.
  • Unlike custom config values, defaults regularly change between Rails versions to encourage best practices, reduce boilerplate, and prepare for deprecations.

• Examples of Defaults Changing:

  • config.active_record.belongs_to_required_by_default switched from false (pre-Rails 5) to true (Rails 5+), enforcing presence on associations.
  • action_dispatch.cookies_same_site_protection became lax by default in Rails 6.1, improving cookie security.
  • action_view.button_to_generates_button_tag in Rails 7 now yields a proper <button>, instead of an <input>.

• The Role of Defaults Files:

  • Two main files manage defaults:
  • application.rb with config.load_defaults, locking in a version’s default settings.
  • config/initializers/new_framework_defaults_X.rb files, where each new default is listed (commented-out) for incremental opt-in by developers after upgrades.
  • The upgrade process does not automatically change these values, preventing sudden breakage but leaving apps on outdated settings if unaddressed.

• Risks of Ignoring Defaults:

  • Keeping old defaults is likened to a “time bomb,” creating technical debt.
  • Security, performance, and compatibility improvements in newer Rails versions can be missed.
  • Third-party gems and tutorials often assume current defaults, and mismatches can cause issues.

• Best Practices for Upgrading Defaults:

  • Preparation:
  • Audit current test coverage and pass all tests before changing defaults.
  • Research:
  • Review all relevant new_framework_defaults files and related Rails guides/documentation.
  • Investigate each default—its purpose, impact, and any migration work needed (e.g., cookie rotation for security changes).
  • Upgrade Approaches:
  • Fast method: Change everything at once (discouraged unless necessary).
  • Slow, incremental method: Uncomment each default one by one, test, deploy, and monitor stability before proceeding to the next. Consider using feature flags for safer rollouts.
  • Finalize:
  • Once all new defaults are adopted and stable, update config.load_defaults to the latest version and remove override files.

• Suggestions for Rails Team:

  • Improve documentation in upgrade guides and new_framework_defaults files, ideally linking to the relevant pull requests or issues for context.

Conclusion and Takeaways

• A Rails upgrade is incomplete without updating framework defaults: failing to do so can lead to technical debt and future emergencies.
• Developers are encouraged to review and update defaults methodically and collaboratively, preparing the codebase for continued health and maintainability.
• Proactive management of framework defaults is a "future kindness" to the app and the team, preventing last-minute crises and ensuring ongoing Rails compatibility.