Update migration guide (#1610)

* add `res.query` and `res.redirect`
* add `express.urlencoded` and `req.body`
* add `res.clearCookie` and `res.status`
* update introduction page
* add `res.redirect('back')` and `res.location('back')`
* bring changes from #1317
* add `brotli` support
* adapt router matching syntax

Author: bjohansebas

en/guide/migrating-5.md

@@ -9,9 +9,9 @@ redirect_from: "/guide/migrating-5.html"
 
 <h2 id="overview">Overview</h2>
 
-Express 5.0 is still in the beta release stage, but here is a preview of the changes that will be in the release and how to migrate your Express 4 app to Express 5.
+Express 5 is not very different from Express 4; although it maintains the same basic API, there are still changes that break compatibility with the previous version. Therefore, an application built with Express 4 might not work if you update it to use Express 5.
 
-To install the latest beta and to preview Express 5, enter the following command in your application root directory:
+To install this version, you need to have a Node.js version 18 or higher. Then, execute the following command in your application directory:
 
 ```console
 $ npm install "express@>={{ site.data.express.next_version }}" --save
@@ -31,6 +31,8 @@ You can then run your automated tests to see what fails, and fix problems accord
   <li><a href="#req.param">req.param(name)</a></li>
   <li><a href="#res.json">res.json(obj, status)</a></li>
   <li><a href="#res.jsonp">res.jsonp(obj, status)</a></li>
+  <li><a href="#magic-redirect">res.redirect('back') and res.location('back')</a></li>  
+  <li><a href="#res.redirect">res.redirect(url, status)</a></li>
   <li><a href="#res.send.body">res.send(body, status)</a></li>
   <li><a href="#res.send.status">res.send(status)</a></li>
   <li><a href="#res.sendfile">res.sendfile()</a></li>
@@ -41,15 +43,21 @@ You can then run your automated tests to see what fails, and fix problems accord
 <ul class="doclist">
   <li><a href="#path-syntax">Path route matching syntax</a></li>
   <li><a href="#rejected-promises">Rejected promises handled from middleware and handlers</a></li>
+  <li><a href="#express.urlencoded">express.urlencoded</a></li>
   <li><a href="#app.router">app.router</a></li>
+  <li><a href="#req.body">req.body</a></li>
   <li><a href="#req.host">req.host</a></li>
   <li><a href="#req.query">req.query</a></li>
+  <li><a href="#res.clearCookie">res.clearCookie</a></li>
+  <li><a href="#res.status">res.status</a></li>
+  <li><a href="#res.vary">res.vary</a></li>
 </ul>
 
 **Improvements**
 
 <ul class="doclist">
   <li><a href="#res.render">res.render()</a></li>
+  <li><a href="#brotli-support">Brotli encoding support</a></li>
 </ul>
 
 <h3>Removed methods and properties</h3>
@@ -94,13 +102,22 @@ Express 5 no longer supports the signature `res.json(obj, status)`. Instead, set
 
 Express 5 no longer supports the signature `res.jsonp(obj, status)`. Instead, set the status and then chain it to the `res.jsonp()` method like this: `res.status(status).jsonp(obj)`.
 
+<h4 id="res.redirect">res.redirect(url, status)</h4>
+
+Express 5 no longer supports the signature `res.redirect(url, status)`. Instead, use the following signature: `res.redirect(status, url)`.
+
+
+<h4 id="magic-redirect">res.redirect('back') and res.location('back')</h4>
+
+Express 5 no longer supports the magic string `back` in the `res.redirect()` and `res.location()` methods. Instead, use the `req.get('Referrer') || '/'` value to redirect back to the previous page. In Express 4, the res.`redirect('back')` and `res.location('back')` methods were deprecated.
+
 <h4 id="res.send.body">res.send(body, status)</h4>
 
 Express 5 no longer supports the signature `res.send(obj, status)`. Instead, set the status and then chain it to the `res.send()` method like this: `res.status(status).send(obj)`.
 
 <h4 id="res.send.status">res.send(status)</h4>
 
-Express 5 no longer supports the signature <code>res.send(<em>status</em>)</code>, where _`status`_ is a number. Instead, use the `res.sendStatus(statusCode)` function, which sets the HTTP response header status code and sends the text version of the code: "Not Found", "Internal Server Error", and so on.
+Express 5 no longer supports the signature `res.send(status)`, where `status` is a number. Instead, use the `res.sendStatus(statusCode)` function, which sets the HTTP response header status code and sends the text version of the code: "Not Found", "Internal Server Error", and so on.
 If you need to send a number by using the `res.send()` function, quote the number to convert it to a string, so that Express does not interpret it as an attempt to use the unsupported old signature.
 
 <h4 id="res.sendfile">res.sendfile()</h4>
@@ -113,26 +130,42 @@ The `res.sendfile()` function has been replaced by a camel-cased version `res.se
 
 Path route matching syntax is when a string is supplied as the first parameter to the `app.all()`, `app.use()`, `app.METHOD()`, `router.all()`, `router.METHOD()`, and `router.use()` APIs. The following changes have been made to how the path string is matched to an incoming request:
 
-- Add new `?`, `*`, and `+` parameter modifiers.
-- Matching group expressions are only RegExp syntax.
-  * `(*)` is no longer valid and must be written as `(.*)`, for example.
-- Named matching groups no longer available by position in `req.params`.
-  * `/:foo(.*)` only captures as `req.params.foo` and not available as `req.params[0]`.
-- Regular expressions can only be used in a matching group.
-  * `/\\d+` is no longer valid and must be written as `/(\\d+)`.
-- Special `*` path segment behavior removed.
-  * `/foo/*/bar` will match a literal `*` as the middle segment.
+- The wildcard `*` must have a name, matching the behavior of parameters `:`, use `/*splat` instead of `/*`
+- The optional character `?` is no longer supported, use braces instead: `/:file{.:ext}`.
+- Regexp characters are not supported. For example:
+```js
+app.get('/[discussion|page]/:slug', async (req, res) => {
+  res.status(200).send('ok')
+})
+``` 
+should be changed to:
+```js
+app.get(['/discussion/:slug', '/page/:slug'], async (req, res) => {
+  res.status(200).send('ok')
+})
+```
+
+- Some characters have been reserved to avoid confusion during upgrade (`()[]?+!`), use `\` to escape them. 
+- Parameter names now support valid JavaScript identifiers, or quoted like `:"this"`.
 
 <h4 id="rejected-promises">Rejected promises handled from middleware and handlers</h4>
 
 Request middleware and handlers that return rejected promises are now handled by forwarding the rejected value as an `Error` to the error handling middleware. This means that using `async` functions as middleware and handlers are easier than ever. When an error is thrown in an `async` function or a rejected promise is `await`ed inside an async function, those errors will be passed to the error handler as if calling `next(err)`.
 
 Details of how Express handles errors is covered in the [error handling documentation](/en/guide/error-handling.html).
 
+<h4 id="express.urlencoded">express.urlencoded</h4>
+
+The `express.urlencoded` method makes the `extended` option `false` by default.
+
 <h4 id="app.router">app.router</h4>
 
 The `app.router` object, which was removed in Express 4, has made a comeback in Express 5. In the new version, this object is a just a reference to the base Express router, unlike in Express 3, where an app had to explicitly load it.
 
+<h4 id="req.body">req.body</h4> 
+
+The `req.body` property returns `undefined` when the body has not been parsed. In Express 4, it returns `{}` by default.
+
 <h4 id="req.host">req.host</h4>
 
 In Express 4, the `req.host` function incorrectly stripped off the port number if it was present. In Express 5, the port number is maintained.
@@ -141,8 +174,24 @@ In Express 4, the `req.host` function incorrectly stripped off the port number i
 
 The `req.query` property is no longer a writable property and is instead a getter. The default query parser has been changed from "extended" to "simple".
 
+<h4 id="res.clearCookie">res.clearCookie</h4>
+
+The `res.clearCookie` method ignores the `maxAge` and `expires` options provided by the user.
+
+<h4 id="res.status">res.status</h4>
+
+The `res.status` method only accepts integers in the range of `100` to `999`, following the behavior defined by Node.js, and it returns an error when the status code is not an integer.
+
+<h4 id="res.query">res.vary</h4>
+
+The `res.vary` throws an error when the `field` argument is missing. In Express 4, if the argument was omitted, it gave a warning in the console
+
 <h3>Improvements</h3>
 
 <h4 id="res.render">res.render()</h4>
 
 This method now enforces asynchronous behavior for all view engines, avoiding bugs caused by view engines that had a synchronous implementation and that violated the recommended interface.
+
+<h4 id="brotli-support">Brotli encoding support</h4>
+
+Express 5 supports Brotli encoding for requests received from clients that support it.