From f976dec24b497311af7f08c8924dcff34c3f1446 Mon Sep 17 00:00:00 2001 From: Daniel Colson Date: Tue, 25 Aug 2020 20:15:25 -0400 Subject: [PATCH] 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. --- guides/source/configuring.md | 21 +++++++++++++++++---- 1 file changed, 17 insertions(+), 4 deletions(-) diff --git a/guides/source/configuring.md b/guides/source/configuring.md index ebaf7476c1..5b49fd4a26 100644 --- a/guides/source/configuring.md +++ b/guides/source/configuring.md @@ -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 ---------------------