Add latest changes from gitlab-org/gitlab@master

1 files changed, 16 insertions, 0 deletions

diff --git a/doc/development/rails_initializers.md b/doc/development/rails_initializers.md
new file mode 100644
index 00000000000..6473baf58d4
--- /dev/null
+++ b/doc/development/rails_initializers.md
@@ -0,0 +1,16 @@
+# Rails initializers
+
+By default, Rails loads Zeitwerk after the initializers in `config/initializers` are loaded.
+Autoloading before Zeitwerk is loaded is now deprecated but because we use a lot of autoloaded
+constants in our initializers, we had to move the loading of Zeitwerk earlier than these
+initializers.
+
+A side-effect of this is that in the initializers, `config.autoload_paths` is already frozen.
+
+To run an initializer before Zeitwerk is loaded, you need put them in `config/initializers_before_autoloader`.
+Ruby files in this folder are loaded in alphabetical order just like the default Rails initializers.
+
+Some examples where you would need to do this are:
+
+1. Modifying Rails' `config.autoload_paths`
+1. Changing configuration that Zeitwerk uses, e.g. inflections