6 files changed, 132 insertions, 7 deletions
diff --git a/doc/src/guide/book.asciidoc b/doc/src/guide/book.asciidoc
index cf8c943..58eda34 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.12.asciidoc[Migrating from Cowboy 2.12 to 2.13]
+
 include::migrating_from_2.11.asciidoc[Migrating from Cowboy 2.11 to 2.12]
 
 include::migrating_from_2.10.asciidoc[Migrating from Cowboy 2.10 to 2.11]
diff --git a/doc/src/guide/constraints.asciidoc b/doc/src/guide/constraints.asciidoc
index 6cc1075..4eade8a 100644
--- a/doc/src/guide/constraints.asciidoc
+++ b/doc/src/guide/constraints.asciidoc
@@ -91,6 +91,11 @@ int(forward, Value) ->
 The value must be returned even if it is not converted
 by the constraint.
 
+The two other operations are currently experimental. They are
+meant to help implement HATEOAS type services, but proper
+support for HATEOAS is not expected to be available before
+Cowboy 3.0 because of Cowboy's current router's limitations.
+
 The `reverse` operation does the opposite: it
 takes a converted value and changes it back to what the
 user input would have been.
diff --git a/doc/src/guide/getting_started.asciidoc b/doc/src/guide/getting_started.asciidoc
index a26802d..06677ee 100644
--- a/doc/src/guide/getting_started.asciidoc
+++ b/doc/src/guide/getting_started.asciidoc
@@ -69,7 +69,7 @@ fetch and compile Cowboy, and that we will use releases:
 PROJECT = hello_erlang
 
 DEPS = cowboy
-dep_cowboy_commit = 2.11.0
+dep_cowboy_commit = 2.13.0
 
 REL_DEPS = relx
 
diff --git a/doc/src/guide/introduction.asciidoc b/doc/src/guide/introduction.asciidoc
index 519608d..3a03a78 100644
--- a/doc/src/guide/introduction.asciidoc
+++ b/doc/src/guide/introduction.asciidoc
@@ -35,14 +35,14 @@ guarantee that the experience will be safe and smooth. You are advised
 to perform the necessary testing and security audits prior to deploying
 on other platforms.
 
-Cowboy is developed for Erlang/OTP 22.0 and newer.
+Cowboy is developed for Erlang/OTP 24.0 and newer.
 
 === License
 
 Cowboy uses the ISC License.
 
 ----
-Copyright (c) 2011-2024, Loïc Hoguin <[email protected]>
+Copyright (c) 2011-2025, Loïc Hoguin <[email protected]>
 
 Permission to use, copy, modify, and/or distribute this software for any
 purpose with or without fee is hereby granted, provided that the above
diff --git a/doc/src/guide/migrating_from_2.12.asciidoc b/doc/src/guide/migrating_from_2.12.asciidoc
new file mode 100644
index 0000000..d058db3
--- /dev/null
+++ b/doc/src/guide/migrating_from_2.12.asciidoc
@@ -0,0 +1,115 @@
+[appendix]
+== Migrating from Cowboy 2.12 to 2.13
+
+Cowboy 2.13 focuses on improving the performance of
+Websocket, as well as the HTTP protocols. It also
+contains a variety of new features and bug fixes.
+In addition, Cowboy 2.13 is the first Cowboy version
+that contains the experimental HTTP/3 support.
+
+Cowboy 2.13 requires Erlang/OTP 24.0 or greater.
+
+=== Features added
+
+* The option `dynamic_buffer` has been added. When
+  enabled, Cowboy will dynamically change the
+  `buffer` socket option based on how much data
+  it receives. It will start at 1024 bytes and
+  go up to 131072 bytes by default. This applies
+  to HTTP/1.1, HTTP/2 and Websocket. The performance
+  gains are very important depending on the scenario.
+
+* HTTP/1.1 and HTTP/2 now accept the `hibernate`
+  option. When set the connection process will
+  automatically hibernate to reduce memory usage
+  at a small performance cost.
+
+* The `protocols` and `alpn_default_protocol` protocol
+  options have been added to control exactly which
+  HTTP protocols are allowed over clear and TLS listeners.
+
+* The Websocket `max_frame_size` option can now be
+  set dynamically via the `set_options` command.
+  This allows configuring a smaller max size and
+  increase it after authentication or other checks.
+
+* `cowboy_req:set_resp_headers` now accept lists of
+  headers. This can be used to simplify passing
+  headers coming from client applications such as
+  Gun. Note that the set-cookie header cannot be
+  provided using this function.
+
+* `cowboy_rest` now always sets the allow header.
+
+* Update Ranch to 1.8.1.
+
+* Update Cowlib to 2.14.0.
+
+* When using Hex.pm, version check requirements will
+  now be relaxed. Cowboy will accept any Ranch version
+  from 1.8.0 to 2.2.0 as well as future 2.x versions.
+  Similarly, any Cowlib 2.x version from 2.14.0 will
+  be accepted.
+
+=== Experimental features added
+
+* Experimental support for HTTP/3 has been added,
+  including Websocket over HTTP/3. HTTP/3 support
+  is disabled by default; to enable, the environment
+  variable COWBOY_QUICER must be set at compile-time.
+
+=== Features deprecated
+
+* The `inactivity_timeout` option is now deprecated
+  for all protocols. It is de facto ignored when
+  `hibernate` is enabled.
+
+=== Optimisation-related changes
+
+* The behavior of the `idle_timeout` timer has been
+  changed for HTTP/2 and Websocket. Cowboy used to
+  reset the timer on every data packet received from
+  the socket. Now Cowboy will check periodically
+  whether new data was received in the interval.
+
+* URI and query string hex encoding and decoding has
+  been optimised.
+
+* Websocket UTF-8 validation of text frames has been
+  optimised.
+
+* Websocket unmasking has been optimised.
+
+=== Bugs fixed
+
+* HTTP/1.1 upgrade to HTTP/2 is now disabled over TLS,
+  as HTTP/2 over TLS must be negotiated via ALPN.
+
+* `cowboy_req:filter_cookies` could miss valid cookies.
+  It has been corrected.
+
+* HTTP/1.1 could get to a state where it would stop
+  receiving data from the socket, or buffer the data
+  without processing it, and the connection eventually
+  time out. This has been fixed.
+
+* Websocket did not compress zero-length frames properly.
+  This resulted in decompression errors in the client.
+  This has been corrected.
+
+* Websocket compression will now be disabled when only
+  the server sets `client_max_window_bits`, as otherwise
+  decompression errors will occur.
+
+* Websocket will now apply `max_frame_size` both to
+  compressed frames as well as the uncompressed payload.
+  Cowboy will stop decompressing when the limit is
+  reached.
+
+* Cowboy now properly handles exits of request processes
+  that occurred externally (e.g. via `exit/2`).
+
+* Invalid return values from `content_types_provided`
+  could result in an atom sent to the socket, leading
+  to a cryptic error message. The invalid value will
+  now result in a better error message.
diff --git a/doc/src/guide/req.asciidoc b/doc/src/guide/req.asciidoc
index 754e470..6b95228 100644
--- a/doc/src/guide/req.asciidoc
+++ b/doc/src/guide/req.asciidoc
@@ -258,7 +258,8 @@ contain two parameters of name `key`.
 
 The same is true when trying to use the PHP-style suffix `[]`.
 When a query string is `key[]=1&key[]=2`, the list returned will
-contain two parameters of name `key[]`.
+contain two parameters of name `key[]`. Cowboy does not require
+the `[]` suffix to properly handle repeated key names.
 
 When a query string is simply `key`, Cowboy will return the
 list `[{<<"key">>, true}]`, using `true` to indicate that the
@@ -291,9 +292,11 @@ If no default is provided and the value is missing, the
 query string is deemed invalid and the process will crash.
 
 When the query string is `key=1&key=2`, the value for `key`
-will be the list `[1, 2]`. Parameter names do not need to
-include the PHP-style suffix. Constraints may be used to
-ensure that only one value was passed through.
+will be the list `[<<"1">>, <<"2">>]`. Parameter names do not
+need to include the PHP-style suffix. Constraints may be used
+to ensure that only one value was given. Constraints do not
+automatically look inside the list, a custom constraint must
+be written if that is necessary.
 
 === Headers