1 files changed, 163 insertions, 0 deletions
diff --git a/docs/en/ranch/2.1/guide/migrating_from_1.7.asciidoc b/docs/en/ranch/2.1/guide/migrating_from_1.7.asciidoc
new file mode 100644
index 00000000..e9b1c96e
--- /dev/null
+++ b/docs/en/ranch/2.1/guide/migrating_from_1.7.asciidoc
@@ -0,0 +1,163 @@
+[appendix]
+== Migrating from Ranch 1.7+ to Ranch 2.0
+
+Ranch 2.0 adds support for multiple connection supervisors.
+
+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.
+
+Ranch 2.0 also adds experimental support for opening more
+than one listening socket on a single port.
+
+Starting with Ranch 2.0 we are also providing a
+https://github.com/juhlig/prometheus_ranch[Prometheus collector]
+as a separate project as well as a
+https://github.com/juhlig/prometheus_ranch/blob/master/dashboards/ranch-dashboard.json[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
+
+* Ranch now comes with a `ranch.appup` file necessary for
+  performing release upgrades. A test suite has been added
+  to confirm release upgrades work from one tag to the next.
+  Numerous fixes were made that will also improve error recovery.
+  Release upgrades will only be supported from Ranch 2.0
+  onward.
+
+* The `num_conns_sups` 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.
+
+* Two steps handshake is now supported. This allows
+  obtaining TLS extensions and updating options before
+  resuming the handshake. The handshake can also be
+  canceled.
+
+=== 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 includes 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`.
+
+=== Added functions
+
+* The functions `ranch:handshake_continue/1,2` and
+  `ranch:handshake_cancel/1` can be used to perform
+  a two steps handshake. These functions may not be
+  supported by all transports.
+
+=== 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
+
+* Calling `ranch:remove_connection/1` will now resume a sleeping
+  acceptor process when applicable.
+
+* 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 https://concuerror.com/[Concuerror],
+  a model checking tool for debugging, testing and verifying
+  concurrent Erlang programs. Two tests have been added in this
+  release and more will follow in the future.
+
+* Ranch is now tested against `stampede`, 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 (we were using a
+  similar tool, `havoc`, at the time of finding that issue).
+
+* 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 23.0.