Add note to avoid requiring config/initializers

[ci skip]

Closes #40021

I began this commit by adding an additional note about explicitly
requiring initializers. `config/intializers` are loaded with `load`
rather than `require` (and always have been, since they were introduced
way back in c6d6082562). So explicitly requiring them can be problematic
if they are not idempotent.

But @p8 pointed out that it is a bit awkward to have 3 notes and one tip
larger than the actual text in this section.

This commit now also reworks 2 of the notes and the tip into additional
paragraphs in the main text. The benefits of the new version I see:

- We now explicitly say that the initializers are loaded by sort order
- We now start with the ideal way to deal with dependent initializers,
  then follow with a couple warnings. We used to lead with what not to
  do, which I think was a bit confusing.
- The language around subdirectories is much simpler (mentioning that
  subdirectories can be used for organizing seemed unnecessary to me -
  that is true of subdirectories in general, and doesn't have any
  specific connection to initializers)

This commit does not change the opening paragraph or the note about when
to use `after_initialize` instead, although it does reformat them.
This commit is contained in:
Daniel Colson 2020-08-25 20:15:25 -04:00
parent 7066f08cd8
commit f976dec24b
No known key found for this signature in database
GPG Key ID: 88A364BBE77B1353
1 changed files with 17 additions and 4 deletions

View File

@ -1431,13 +1431,26 @@ Some parts of Rails can also be configured externally by supplying environment v
Using Initializer Files
-----------------------
After loading the framework and any gems in your application, Rails turns to loading initializers. An initializer is any Ruby file stored under `config/initializers` in your application. You can use initializers to hold configuration settings that should be made after all of the frameworks and gems are loaded, such as options to configure settings for these parts.
After loading the framework and any gems in your application, Rails turns to
loading initializers. An initializer is any Ruby file stored under
`config/initializers` in your application. You can use initializers to hold
configuration settings that should be made after all of the frameworks and gems
are loaded, such as options to configure settings for these parts.
NOTE: There is no guarantee that your initializers will run after all the gem initializers, so any initialization code that depends on a given gem having been initialized should go into a `config.after_initialize` block.
The files in `config/initializers` (and any subdirectories of
`config/initializers`) are sorted and loaded one by one as part of
the `load_config_initializers` initializer.
NOTE: You can use subfolders to organize your initializers if you like, because Rails will look into the whole file hierarchy from the initializers folder on down.
If an initializer has code that relies on code in another initializer, you can
combine them into a single initializer instead. This makes the dependencies more
explicit, and can help surface new concepts within your application. Rails also
supports numbering of initializer file names, but this can lead to file name
churn. Explicitly loading initializers with `require` is not recommended, since
it will cause the initializer to get loaded twice.
TIP: While Rails supports numbering of initializer file names for load ordering purposes, a better technique is to place any code that needs to load in a specific order within the same file. This reduces file name churn, makes dependencies more explicit, and can help surface new concepts within your application.
NOTE: There is no guarantee that your initializers will run after all the gem
initializers, so any initialization code that depends on a given gem having been
initialized should go into a `config.after_initialize` block.
Initialization events
---------------------