A Rails 6 app stuck before 7.0: run the Zeitwerk check and read what it reports

What changed in Rails 7.0

The Rails upgrade guide lists for 6.1 to 7.0 that Zeitwerk autoloading is mandatory, that the setting that chose the autoloader is gone and that the private classic-loader API is removed. It also says autoloading reloadable constants while the app initialises now raises an error. An app still in classic mode has to switch while it is on Rails 6, because the option disappears at the version you are trying to reach.

• Check whether the app sets the classic autoloader anywhere in its configuration.
• Look for initialisers that refer to application classes, which the new rule may reject.

What the check does

Running the Zeitwerk check from the Rails command line eager loads the app and verifies that its file names follow the loader's conventions. A successful run ends with the message 'All is good!'. The conventions are simple: a file must define the constant its name implies, and directories act as namespaces, so app/controllers/admin/payments_controller.rb must define Admin::PaymentsController. Names are derived by camelising the file name, so acronyms need an inflection rule.

• Run it on a copy, not on production.
• Read every line of output, not only the last: other messages can appear depending on configuration.

Typical failures and what they mean

A file that defines a constant with a different name from its path is reported, and so is a directory whose namespace does not match. An acronym in a file name, such as an HTML parser class, needs an inflection so the file name maps to the intended constant. A constant referred to during initialisation that is reloadable will raise. These are code-structure problems, not typing mistakes, and each fix changes how names resolve, so each is covered by a test or a manual check of the code path that uses the class.

• Fix naming mismatches by renaming the file or the constant, whichever matches the rest of the code.
• Add inflection rules for acronyms instead of renaming widely used classes.
• Record each change in a list so a reviewer can follow it.

Eager loading is the real test

Production-like environments load all application code at boot, and the guide recommends testing that the project eager loads correctly. Because the setting is on only in production by default, a development run can pass while production fails on a file nobody touched. Add a test that eager loads the app, and run the check in CI.

• Rake tasks eager load only if configured; do not assume they do.
• A passing check does not prove business behaviour unchanged.

What does not fit, and how the paid route is accepted

This guide covers one cause of a blocked Rails 7 upgrade. It does not replace the inventory of everything else the app depends on: the Ruby version, gems, the JavaScript build and the test baseline. Rails 6 apps are outside the fixed Rails 7 to 8.1 job, so the route is an inventory and ranked plan first, which records the autoloader state, then a programme if several steps are needed. The plan is accepted when every dependency is listed with its support status and the path is ranked with prerequisites. Prices are untested proposals; send versions, not code.