Improve docs around preload_app! and phased restart (#2481)

* Correct test name

* Update preload_app! comment in dsl.rb

The default changed in Puma 5 with #2143.

* Upgrade guide: make it more clear about preload and phased restart

* Clarify when preload_app! is on by default

* Remove trailing whitespace

* Upgrade guide: what setting WEB_CONCURRENCY does

This is what happened in #2143.

Co-authored-by: Nate Berkopec <nate.berkopec@gmail.com>

5.0-Upgrade.md

@@ -84,12 +84,12 @@ To learn more about using `refork` and `fork_worker`, see ['Fork Worker'](docs/f
 
 ## Upgrade
 
-* Setting the `WEB_CONCURRENCY` environment variable will now configure the number of workers (processes) that Puma will boot.
+* Setting the `WEB_CONCURRENCY` environment variable will now configure the number of workers (processes) that Puma will boot and enable preloading of the application.
 * If you did not explicitly set `environment` before, Puma now checks `RAILS_ENV` and will use that, if available in addition to `RACK_ENV`.
 * If you have been using the `--control` CLI option, update your scripts to use `--control-url`.
 * If you are using `worker_directory` in your config file, change it to `directory`.
 * If you are running MRI, default thread count on Puma is now 5, not 16. This may change the amount of threads running in your threadpool. We believe 5 is a better default for most Ruby web applications on MRI. Higher settings increase latency by causing GVL contention.
-* If you are using a worker count of more than 1 and you are not using phased_restart, Puma will now `preload` by default. We believe this is a better default, but may cause issues in non-Rails applications if you do not have the proper `before` and `after` fork hooks configured. See documentation for your framework. Rails users do not need to change anything.
+* If you are using a worker count of more than 1, set using `WEB_CONCURRENCY`, Puma will now preload the application by default (disable with `preload_app! false`). We believe this is a better default, but may cause issues in non-Rails applications if you do not have the proper `before` and `after` fork hooks configured. See documentation for your framework. Rails users do not need to change anything. **Please note that it is not possible to use [the phased restart](docs/restart.md) with preloading.**
 * tcp mode and daemonization have been removed without replacement. For daemonization, please use a modern process management solution, such as systemd or monit.
 * `connected_port` was renamed to `connected_ports` and now returns an Array, not an Integer.
 

History.md

@@ -81,8 +81,7 @@
   * min_threads now set by environment variables PUMA_MIN_THREADS and MIN_THREADS. ([#2143])
   * max_threads now set by environment variables PUMA_MAX_THREADS and MAX_THREADS. ([#2143])
   * max_threads default to 5 in MRI or 16 for all other interpreters. ([#2143])
-  * Configuration: number of workers is read from `WEB_CONCURRENCY` if `workers` isn't set ([#2143])
-  * preload by default if workers > 1 ([#2143])
+  * `preload_app!` is on by default if number of workers > 1 and set via `WEB_CONCURRENCY` ([#2143])
   * Puma::Plugin.workers_supported? has been removed. Use Puma.forkable? instead. ([#2143])
   * `tcp_mode` has been removed without replacement. ([#2169])
   * Daemonization has been removed without replacement. ([#2170])

README.md

@@ -75,7 +75,7 @@ run Sinatra::Application
 You can then start your application using:
 
 ```
-$ bundle exec puma 
+$ bundle exec puma
 ```
 
 ## Configuration
@@ -146,7 +146,7 @@ before_fork do
 end
 ```
 
-Preloading can’t be used with phased restart, since phased restart kills and restarts workers one-by-one, and preload_app copies the code of master into the workers.
+Preloading can’t be used with phased restart, since phased restart kills and restarts workers one-by-one, and `preload_app!` copies the code of master into the workers.
 
 ### Error handling
 

lib/puma/dsl.rb

@@ -561,7 +561,7 @@ def directory(dir)
     end
 
     # Preload the application before starting the workers; this conflicts with
-    # phased restart feature. This is off by default.
+    # phased restart feature. On by default if your app uses more than 1 worker.
     #
     # @note Cluster mode only.
     # @example

test/test_config.rb

@@ -343,7 +343,7 @@ def test_config_loads_workers_from_env
     end
   end
 
-  def test_config_does_not_preload_app_if_using_workers
+  def test_config_does_not_preload_app_if_not_using_workers
     with_env("WEB_CONCURRENCY" => "0") do
       conf = Puma::Configuration.new
       assert_equal false, conf.options.default_options[:preload_app]