Clarify autoload_paths and eager_load in guides per current usage. [CI SKIP]

2 files changed, 31 insertions, 12 deletions

diff --git a/guides/source/autoloading_and_reloading_constants.md b/guides/source/autoloading_and_reloading_constants.md
index dea87a18f8..8d28007671 100644
--- a/guides/source/autoloading_and_reloading_constants.md
+++ b/guides/source/autoloading_and_reloading_constants.md
@@ -8,7 +8,7 @@ This guide documents how constant autoloading and reloading works.
 After reading this guide, you will know:
 
 * Key aspects of Ruby constants
-* What is `autoload_paths`
+* What are the `autoload_paths` and how does eager loading work in production?
 * How constant autoloading works
 * What is `require_dependency`
 * How constant reloading works
@@ -430,8 +430,8 @@ if `House` is still unknown when `app/models/beach_house.rb` is being eager
 loaded, Rails autoloads it.
 
 
-autoload_paths
---------------
+autoload_paths and eager_load_paths
+-----------------------------------
 
 As you probably know, when `require` gets a relative file name:
 
@@ -451,7 +451,7 @@ the idea is that when a constant like `Post` is hit and missing, if there's a
 `post.rb` file for example in `app/models` Rails is going to find it, evaluate
 it, and have `Post` defined as a side-effect.
 
-Alright, Rails has a collection of directories similar to `$LOAD_PATH` in which
+All right, Rails has a collection of directories similar to `$LOAD_PATH` in which
 to look up `post.rb`. That collection is called `autoload_paths` and by
 default it contains:
 
@@ -465,17 +465,22 @@ default it contains:
 
 * The directory `test/mailers/previews`.
 
-Also, this collection is configurable via `config.autoload_paths`. For example,
-`lib` was in the list years ago, but no longer is. An application can opt-in
-by adding this to `config/application.rb`:
+`eager_load_paths` is initially the `app` paths above
 
-```ruby
-config.autoload_paths << "#{Rails.root}/lib"
-```
+How files are autoloaded depends on `eager_load` and `cache_classes` config settings which typically vary in development, production, and test modes:
+ 
+ * In **development**, you want quicker startup with incremental loading of application code.  So `eager_load` should be set to `false`, and rails will autoload files as needed (see [Autoloading Algorithms](#autoloading-algorithms) below) -- and then reload them when they change (see [Constant Reloading](#constant-reloading) below).
+ * In **production**, however you want consistency and thread-safety and can live with a longer boot time. So `eager_load` is set to `true`, and then during boot (before the app is ready to receive requests) rails loads all files in the `eager_load_paths`  and then turns off auto loading (NB: autoloading may be needed during eager loading). Not autoloading after boot is a `good thing`, as autoloading can cause the app to be have thread-safety problems. 
+ * In **test**, for speed of execution (of individual tests) `eager_load` is `false`, so rails follows development behaviour. 
+
+What is described above are the defaults with a newly generated rails app. There are multiple ways this can be configured differently (see [Configuring Rails Applications](configuring.html#rails-general-configuration).
+). But using `autoload_paths` on its own  in the past (pre-rails 5) developers might configure `autoload_paths` to add in extra locations (e.g. `lib` which used to be an autoload path list years ago, but no longer is).  However this is now discouraged for most purposes, as it is likely to lead to production-only errors. It is possible to add new locations to both `config.eager_load_paths` and `config.autoload_paths` but use at your own risk.
+
+See also ([Autoloading in the Test Environment](#autoloading-in-the-test-environment).
 
 `config.autoload_paths` is not changeable from environment-specific configuration files.
 
-The value of `autoload_paths` can be inspected. In a just generated application
+The value of `autoload_paths` can be inspected. In a just-generated application
 it is (edited):
 
 ```
@@ -1329,3 +1334,17 @@ class C < BasicObject
   end
 end
 ```
+
+### Autoloading in the Test Environment
+ 
+When configuring the `test` environment for autoloading you might consider multiple factors. 
+
+For example it might be worth running your tests with an identical setup to production (`config.eager_load = true`, `config.cache_classes = true`) in order to catch any problems before they hit production (this is compensation for the lack of dev-prod parity). However this will slow down the boot time for individual tests on a dev machine (and is not immediately compatible with spring see below). So one possibility is to do this on a 
+[CI](https://en.wikipedia.org/wiki/Continuous_integration) machine only (which should run without spring). 
+
+On a development machine you can then have your tests running with whatever is fastest (ideally `config.eager_load = false`). 
+
+With the [Spring](https://github.com/rails/spring) pre-loader (included with new rails apps), you ideally keep `config.eager_load = false` as per development. Sometimes you may end up with a hybrid configuration (`config.eager_load = true`, `config.cache_classes = true` AND `config.enable_dependency_loading = true`), see [spring issue](https://github.com/rails/spring/issues/519#issuecomment-348324369). However it might be simpler to keep the same configuration as development, and work out whatever it is that is causing autoloading to fail (perhaps by the results of your CI test results). 
+
+Occasionally you may need to explictly eager_load by using `Rails
+.application.eager_load!` in the setup of your tests -- this might occur if your [tests involve multithreading](https://stackoverflow.com/questions/25796409/in-rails-how-can-i-eager-load-all-code-before-a-specific-rspec-test). 
diff --git a/guides/source/configuring.md b/guides/source/configuring.md
index 98cd5e8fe5..36c2fdb0b8 100644
--- a/guides/source/configuring.md
+++ b/guides/source/configuring.md
@@ -62,7 +62,7 @@ These configuration methods are to be called on a `Rails::Railtie` object, such
 
 * `config.autoload_once_paths` accepts an array of paths from which Rails will autoload constants that won't be wiped per request. Relevant if `config.cache_classes` is `false`, which is the case in development mode by default. Otherwise, all autoloading happens only once. All elements of this array must also be in `autoload_paths`. Default is an empty array.
 
-* `config.autoload_paths` accepts an array of paths from which Rails will autoload constants. Default is all directories under `app`.
+* `config.autoload_paths` accepts an array of paths from which Rails will autoload constants. Default is all directories under `app`. It is no longer recommended to adjust this. See [Autoloading and Reloading Constants](autoloading_and_reloading_constants.html#autoload-paths-and-eager-load-paths)
 
 * `config.cache_classes` controls whether or not application classes and modules should be reloaded on each request. Defaults to `false` in development mode, and `true` in test and production modes.