3 files changed, 121 insertions, 1 deletions
diff --git a/doc/src/guide/book.asciidoc b/doc/src/guide/book.asciidoc
index 76557a6..0b01b22 100644
--- a/doc/src/guide/book.asciidoc
+++ b/doc/src/guide/book.asciidoc
@@ -75,6 +75,8 @@ include::performance.asciidoc[Performance]
 
 = Additional information
 
+include::migrating_from_2.7.asciidoc[Migrating from Cowboy 2.7 to 2.8]
+
 include::migrating_from_2.6.asciidoc[Migrating from Cowboy 2.6 to 2.7]
 
 include::migrating_from_2.5.asciidoc[Migrating from Cowboy 2.5 to 2.6]
diff --git a/doc/src/guide/getting_started.asciidoc b/doc/src/guide/getting_started.asciidoc
index 574a050..7bf97e3 100644
--- a/doc/src/guide/getting_started.asciidoc
+++ b/doc/src/guide/getting_started.asciidoc
@@ -69,7 +69,7 @@ fetch and compile Cowboy:
 PROJECT = hello_erlang
 
 DEPS = cowboy
-dep_cowboy_commit = 2.7.0
+dep_cowboy_commit = 2.8.0
 
 DEP_PLUGINS = cowboy
 
diff --git a/doc/src/guide/migrating_from_2.7.asciidoc b/doc/src/guide/migrating_from_2.7.asciidoc
new file mode 100644
index 0000000..1e52130
--- /dev/null
+++ b/doc/src/guide/migrating_from_2.7.asciidoc
@@ -0,0 +1,118 @@
+[appendix]
+== Migrating from Cowboy 2.7 to 2.8
+
+Cowboy 2.8 contains many optimizations for all
+protocols. HTTP/1.1 has received the largest
+improvements and Cowboy will now be able to
+handle noticeably more requests. Thanks to
+the folks at Stressgrid for helping identify that
+the performance was lower than it should have been
+and for benchmarking my many changes and experiments.
+
+Cowboy 2.8 also contains a small number of tweaks
+and bug fixes. Cowboy 2.8 is the first Cowboy release,
+ever, to be consistently green on all tested platforms.
+This is mostly due to the reworking of some test cases,
+but a few bugs were discovered and fixed in the process.
+
+Cowboy 2.8 requires Erlang/OTP 22.0 or greater. It may
+also work out of the box with Erlang/OTP 21.3 but this
+was not tested and is not supported.
+
+=== Features added
+
+* Cowboy will now use `active,N` instead of `active,once`
+  to receive data from the socket. This greatly improves
+  the performance and allows Cowboy to process more
+  requests, especially for HTTP/1.1. The `active_n`
+  protocol option can be configured to change the
+  `active,N` value. The default is 100 for all protocols.
+
+* Add a `linger_timeout` option for HTTP/2. The default
+  is 1000, or one second. This helps ensure that the
+  final GOAWAY frame will be properly received by clients.
+
+* The function `cowboy_req:parse_header/2,3` will now
+  parse the headers `access-control-request-headers`,
+  `access-control-request-method`, `content-encoding`,
+  `content-language`, `max-forwards`, `origin`,
+  `proxy-authorization` and `trailer`.
+
+* A Performance chapter has been added to the guide.
+  More content will be added in future releases.
+
+* Update Cowlib to 2.9.1.
+
+=== Experimental features added
+
+* A `protocols` protocol option allows configuring which
+  protocol will be used for clear listeners. Setting it
+  to `[http2]` will disable HTTP/1.1 entirely. This feature
+  will be extended in a future release.
+
+=== Features modified
+
+* The default value for HTTP/1.1's `max_keepalive` option
+  has been increased. It now allows 1000 requests before
+  gracefully closing the connection.
+
+* The default value for HTTP/2's `max_received_frame_rate`
+  option has been increased. It now allows 10000 frames every
+  10 seconds.
+
+* Cowboy will now accept whitespace in cookie names. This
+  is in line with the recommended parsing algorithm for the
+  upcoming cookie RFC update, and corresponds to what browsers
+  are doing.
+
+=== Bugs fixed
+
+* The number of Transport:send/2 calls has been optimized
+  for HTTP/2. Reducing the number of calls has a noticeable
+  impact on the number of requests that can be processed.
+
+* Trying to use `cowboy_req:reply/4` with a status code of
+  204 or 304 and a non-empty response body will now result
+  in a crash. Using `cowboy_req:stream_reply/2,3` with 204
+  or 304 and then attempting to send a body will also result
+  in a crash. These status codes disallow response bodies
+  and trying to send one will break HTTP/1.1 framing.
+
+* A crash has been fixed related to HTTP/1.1 pipelining.
+  The bug was most likely introduced in Cowboy 2.6 when
+  flow control was added for HTTP/1.1 request bodies.
+
+* The HTTP/1.1 protocol code could get stuck because of flow
+  control. This has been corrected.
+
+* A crash has been fixed for HTTP/1.1. It occurred when
+  a flow control update was requested (such as reading
+  the request body) after the body was fully read.
+
+* The timeout was incorrectly reset sometimes when a stream
+  (a pair of request/response) terminated. This has been
+  corrected.
+
+* Handling of hibernation for Websocket has been improved.
+  Websocket over HTTP/2 now supports hibernating. Stray
+  messages no longer cancel hibernation.
+
+* The `cowboy_compress_h` stream handler will now ignore
+  malformed accept-encoding headers instead of crashing.
+
+* The manual pages for `cowboy:start_clear(3)` and
+  `cowboy:start_tls(3)` now mentions that some protocol
+  options may be documented in the releevant stream
+  handler.
+
+* The manual page for `cowboy_req:parse_header(3)` was
+  corrected. When an unsupported header is given the
+  function crashes, it does not return an `undefined` tuple.
+
+* The routing algorithm description in the user guide has
+  been improved.
+
+* The test suites are now consistently green on all tested
+  platforms. Most of the test failures were caused by flaky
+  tests. Avoiding the use of timeouts fixed most of them.
+  A small number of tests had to be reworked.