Finish upgrade doc and provide default value for busy wait time

5.0-Upgrade.md

@@ -4,25 +4,66 @@ Puma 5 brings new experimental performance features, a few quality-of-life featu
 
 ## What's New
 
-* **Better throughput and lower latency via new experimental option**
-* **Better memory usage via new experimental option**
-* **Better copy-on-write performance via new experimental option**
-* **Loads of bugfixes**
-* Faster phased restarts and worker timeouts 
+### Lower latency, better throughput
+
+From our friends at GitLab, the new experimental `wait_for_less_busy_worker` config option may reduce latency and improve throughput for high-load Puma apps on MRI. See the [pull request](https://github.com/puma/puma/pull/2079) for more discussion.
+
+Users of this option should see reduced request queue latency and possibly less overall latency.
+
+Add the following to your `puma.rb` to try it:
+
+```ruby 
+wait_for_less_busy_worker
+# or 
+wait_for_less_busy_worker 0.001
+```
+
+Production testing at GitLab suggests values between `0.001` and `0.010` are best.
+
+### Better memory usage
+
+5.0 brings two new options to your config which may improve memory usage.
+
+`nakayoshi_fork` calls GC a handful of times and compacts the heap on Ruby 2.7+ before forking. This may reduce memory usage on Pumas on MRI with preload enabled.
+
+To use it, you can add this to your `puma.rb`:
+
+```ruby 
+nakayoshi_fork
+```
+
+Puma 5 introduces an experimental new cluster-mode configuration option, `fork_worker` (`--fork-worker` from the CLI). This mode causes Puma to fork additional workers from worker 0, instead of directly from the master process:
+
+```
+10000   \_ puma 4.3.3 (tcp://0.0.0.0:9292) [puma]
+10001       \_ puma: cluster worker 0: 10000 [puma]
+10002           \_ puma: cluster worker 1: 10000 [puma]
+10003           \_ puma: cluster worker 2: 10000 [puma]
+10004           \_ puma: cluster worker 3: 10000 [puma]
+```
+
+This allows the usage of `preload` with `phased_restart`. It also may improve memory usage because the worker process loads additional code after processing requests.
+
+To learn more about using `refork` and `fork_worker`, see [the documentation](https://github.com/puma/puma/blob/master/docs/fork_worker.md).
+
+### What else is new?
+
+* **Loads of bugfixes**.
+* Faster phased restarts and worker timeouts.
 * pumactl now has a `thread-backtraces` command to print thread backtraces, bringing thread backtrace printing to all platforms, not just *BSD and Mac. (#2053)
 * Added incrementing `requests_count` to `Puma.stats`. (#2106)
-* Faster phased restart and worker timeout (#2220)
+* Faster phased restart and worker timeout. (#2220)
 * Added `state_permission` to config DSL to set state file permissions (#2238)
 * Ruby 2.2 support will be dropped in Puma 6. This is the final major release series for Ruby 2.2.
 
 ## Upgrade
 
-* If you did not explicitly set `environment` before, we now check `RAILS_ENV` and use that, if available. This may effect which config file Puma attempts to load.
+* 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 production. 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.
-* tcp mode and daemonization have been removed without replacement.
+* 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.
+* 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.
 
 Then, update your Gemfile:

History.md

@@ -1,7 +1,7 @@
 ## 5.0.0
 
 * Features
-  * EXPERIMENTAL: Add `fork_worker` option and `refork` command for reduced memory usage by forking from a worker process and eliminating the master process. (#2099)
+  * EXPERIMENTAL: Add `fork_worker` option and `refork` command for reduced memory usage by forking from a worker process instead of the master process. (#2099)
   * EXPERIMENTAL: Added `wait_for_less_busy_worker` config. This may reduce latency on MRI through inserting a small delay before re-listening on the socket if worker is busy (#2079).
   * EXPERIMENTAL: Added `nakayoshi_fork` option. Reduce memory usage in preloaded cluster-mode apps by GCing before fork and compacting, where available. (#2093, #2256)
   * Added pumactl `thread-backtraces` command to print thread backtraces (#2054)

lib/puma/dsl.rb

@@ -700,7 +700,7 @@ module Puma
     # requests to pick up new requests first.
     #
     # Only works on MRI. For all other interpreters, this setting does nothing.
-    def wait_for_less_busy_worker(val)
+    def wait_for_less_busy_worker(val=0.005)
       @options[:wait_for_less_busy_worker] = val.to_f
     end