Update the migration guide for 2.0

4 files changed, 132 insertions, 53 deletions

diff --git a/doc/src/guide/book.asciidoc b/doc/src/guide/book.asciidoc
index e87e7b3..1c8d78a 100644
--- a/doc/src/guide/book.asciidoc
+++ b/doc/src/guide/book.asciidoc
@@ -29,9 +29,7 @@ include::internals.asciidoc[Internals]
 
 = Additional information
 
-include::upcoming_2.0_changes.asciidoc[Upcoming changes in Ranch 2.0]
-
-include::migrating_from_1.7.asciidoc[Changes since Ranch 1.7]
+include::migrating_from_1.7.asciidoc[Migrating from Ranch 1.7 to 2.0]
 
 include::migrating_from_1.6.asciidoc[Migrating from Ranch 1.6 to 1.7]
 
diff --git a/doc/src/guide/introduction.asciidoc b/doc/src/guide/introduction.asciidoc
index 1644921..d904c65 100644
--- a/doc/src/guide/introduction.asciidoc
+++ b/doc/src/guide/introduction.asciidoc
@@ -13,9 +13,9 @@ with socket programming and TCP protocols.
 
 === Supported platforms
 
-Ranch is tested and supported on Linux, FreeBSD, OSX and Windows.
+Ranch is tested and supported on Linux, FreeBSD, macOS and Windows.
 
-Ranch is developed for Erlang/OTP 19+.
+Ranch is developed for Erlang/OTP 21+.
 
 Ranch may be compiled on earlier Erlang versions with small source code
 modifications but there is no guarantee that it will work as expected.
diff --git a/doc/src/guide/migrating_from_1.7.asciidoc b/doc/src/guide/migrating_from_1.7.asciidoc
index a4ce981..3724246 100644
--- a/doc/src/guide/migrating_from_1.7.asciidoc
+++ b/doc/src/guide/migrating_from_1.7.asciidoc
@@ -1,14 +1,134 @@
 [appendix]
-== Changes since Ranch 1.7
+== Migrating from Ranch 1.7 to Ranch 2.0
 
-The following patch versions were released since Ranch 1.7:
+Ranch 2.0 adds support for multiple connection supervisors.
 
-=== Ranch 1.7.1
+Ranch 1.x had a bottleneck because it used only a single
+connection supervisor. This was more evident when many
+connections were dropped at once as the supervisor couldn't
+keep up and failed to accept new connections while cleaning
+up the old ones. Ranch 2.0 behaves much better in this scenario
+by default. Multiple connection supervisors also helps with
+concurrently accepting new connections.
 
-This release fixes an issue with the PROXY protocol where
-the wrong CRC32 algorithm was used and would cause checksum
-verification to fail.
+Ranch 2.0 also adds experimental support for opening more
+than one listening socket on a single port.
 
-Because the plain `crc32` checksum is not supported by the
-PROXY protocol, the configuration value when building PROXY
-headers has been changed to `crc32c`.
+Starting with Ranch 2.0 we are also providing a Prometheus
+collector as a separate project as well as a Grafana
+dashboard.
+
+Ranch 2.0 is compatible with Erlang/OTP 21.0 onward. Support
+for Erlang/OTP 19 and 20 has been removed.
+
+=== Features added
+
+* The `num_conns_sup` option has been added. It allows
+  configuring the number of connection supervisors. It
+  now defaults to `num_accceptors`. The old behavior can
+  be obtained by setting this value to 1.
+
+* The `logger` option is no longer experimental. It now
+  defaults to `logger` instead of `error_logger`.
+
+* UNIX domain sockets are now supported.
+
+* The active N socket option is now supported. It requires
+  Erlang/OTP 21.3 or above for TLS, however.
+
+* Embedded listeners are now failing in a predictable
+  manner when `ranch_server` goes down. It is no longer
+  necessary to embed `ranch_sup` and the recommendation
+  is now to just start Ranch normally when using embedded
+  listeners.
+
+=== Experimental features added
+
+* The experimental `num_listen_sockets` option has been
+  added. It allows opening more than one listening socket
+  per listener. It can only be used alongside the Linux
+  `SO_REUSEPORT` socket option or equivalent. It allows
+  working around a bottleneck in the kernel and maximizes
+  resource usage, leading to increased rates for accepting
+  new connections.
+
+=== Features removed
+
+* The `socket` option was removed. A more viable solution
+  is to define a custom transport module that returns a fresh
+  socket when `Transport:listen/1` is called.
+
+=== Changed behaviors
+
+* The callback function `Transport:listen/1` and its
+  implementations in `ranch_tcp` and `ranch_ssl` have changed
+  to accept a map of transport options instead of only
+  socket options.
+
+* The callback function `Transport:messages/0` return value
+  now include the tag used for passive messages.
+
+* The `Socket` argument was removed from `Protocol:start_link/3`.
+  The socket must now be obtained by calling `ranch:handshake/1,2`.
+
+=== Changed functions
+
+* The `NumAcceptors` argument was removed from `ranch:start_listener/5``
+  and `ranch:child_spec/5` and moved to the transport options.
+
+* Ranch options can no longer be passed along with socket options
+  as a proplist. The only forms allowed are now the `ranch:opts()`
+  map or only socket options as-is. Individual transport options
+  are now validated as well. The `ranch:opts()` map must
+  be used when socket options also use a map. This applies to the
+  `ranch:start_listener/5`, `ranch:child_spec/5` and
+  `ranch:set_transport_options/2` functions.
+
+* The function `ranch:info/1,2` now returns a map containing
+  each listener's information rather than a list of key/values.
+  The key `num_acceptors` was removed as it can be found in the
+  transport options.
+
+* The function `ranch:set_transport_options/2` no longer requires
+  the listener to be suspended. Which options apply immediately,
+  on suspend/resume or on restart has been documented. Some work
+  has also been done to make these option changes more predictable.
+
+=== Removed functions
+
+* The function `ranch:accept_ack/1` has been removed in favor
+  of `ranch:handshake/1,2`.
+
+=== Bugs fixed
+
+* Repeatedly calling `ranch:remove_connection/1` from a connection
+  process would crash the respective connection supervisor. This has
+  now been fixed.
+
+* When a connection process was failing to start, the socket was
+  not closed and this lead to leaking sockets. This is now corrected.
+
+=== Other changes
+
+* Connection draining has now been documented in the guide
+  following user feedback and discussions.
+
+* Ranch is now tested against `havoc`, a chaos monkey style
+  testing tool. Currently includes three scenarios: normal
+  TCP and TLS listeners and embedded TCP listener. This new
+  test suite helped uncover a misplaced `monitor/2` call
+  added during the development of Ranch 2.0.
+
+* The supervisor for acceptors and the parent supervisor for
+  connection supervisors now have an adaptive restart
+  intensity limit set to `1 + ceil(math:log2(NumChildren))`
+  to allow room for errors when they have many children.
+
+* Ranch now uses stricter compiler options. Missing function
+  specs were added to internal modules.
+
+* Ranch now calls `ssl:handshake/1,2,3` instead of
+  `ssl:ssl_accept/1,2`.
+
+* The `ranch_ssl:ssl_opt()` type has been updated to conform
+  with Erlang/OTP 22.0.
diff --git a/doc/src/guide/upcoming_2.0_changes.asciidoc b/doc/src/guide/upcoming_2.0_changes.asciidoc
deleted file mode 100644
index 378d0a6..0000000
--- a/doc/src/guide/upcoming_2.0_changes.asciidoc
+++ /dev/null
@@ -1,39 +0,0 @@
-[appendix]
-== Upcoming changes in Ranch 2.0
-
-The following changes will be done in Ranch 2.0. In most
-cases an alternative is already available in the most
-recent Ranch version.
-
-* The callback function `ranch_transport:listen/1` and its
-  implementations in `ranch_tcp` and `ranch_ssl` have changed
-  to accept a map of transport options instead of socket
-  options.
-
-* The function `ranch:start_listener/6` has been deprecated
-  in favor of `ranch:start_listener/5`. The number of acceptors
-  was removed and will be taken from the transport options.
-
-* The function `ranch:child_spec/6` has also been deprecated,
-  in favor of `ranch:child_spec/5`.
-
-* The function `ranch:accept_ack/1` has been deprecated in
-  favor of `ranch:handshake/1,2`.
-
-* The function `ranch:info/1,2` will return a map containing
-  each listener's information rather than a list of key/values.
-  The `num_acceptors` key will be removed.
-
-* The socket will no longer be passed to the protocol when
-  starting it. It will be available as a return value from
-  `ranch:handshake/1,2` only.
-
-* Starting from Ranch 2.0 it will no longer be allowed to
-  pass Ranch options along with socket options as a proplist.
-  The only forms allowed will be the `ranch:opts()` map or socket
-  options as-is. The `ranch:opts()` map must be used in case socket
-  options also use a map.
-
-* The `socket` option will be removed. A more viable solution
-  is to define a custom transport module that returns a fresh
-  socket when `Transport:listen/1` is called.