Merge branch '6.1' into 6.2

* 6.1:
  [Routing] Document the new alias feature
  Add ignoreAttributes to the documentation

Author: javiereguiluz

routing.rst

@@ -1528,6 +1528,114 @@ A possible solution is to change the parameter requirements to be more permissiv
     as the token and the format will be empty. This can be solved by replacing
     the ``.+`` requirement by ``[^.]+`` to allow any character except dots.
 
+.. _routing-alias:
+
+Route Aliasing
+--------------
+
+Route alias allow you to have multiple name for the same route:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/routes.yaml
+        new_route_name:
+            alias: original_route_name
+
+    .. code-block:: xml
+
+        <!-- config/routes.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <routes xmlns="http://symfony.com/schema/routing"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/routing
+                https://symfony.com/schema/routing/routing-1.0.xsd">
+
+            <route id="new_route_name" alias="original_route_name"/>
+        </routes>
+
+    .. code-block:: php
+
+        // config/routes.php
+        use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
+
+        return function (RoutingConfigurator $routes) {
+            $routes->alias('new_route_name', 'original_route_name');
+        };
+
+In this example, both ``original_route_name`` and ``new_route_name`` routes can
+be used in the application and will produce the same result.
+
+.. _routing-alias-deprecation:
+
+Deprecating Route Aliases
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If some route alias should no longer be used (because it is outdated or
+you decided not to maintain it anymore), you can deprecate its definition:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        new_route_name:
+            alias: original_route_name
+
+            # this outputs the following generic deprecation message:
+            # Since acme/package 1.2: The "new_route_name" route alias is deprecated. You should stop using it, as it will be removed in the future.
+            deprecated:
+                package: 'acme/package'
+                version: '1.2'
+
+            # you can also define a custom deprecation message (%alias_id% placeholder is available)
+            deprecated:
+                package: 'acme/package'
+                version: '1.2'
+                message: 'The "%alias_id%" route alias is deprecated. Do not use it anymore.'
+
+    .. code-block:: xml
+
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <routes xmlns="http://symfony.com/schema/routing"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/routing
+                https://symfony.com/schema/routing/routing-1.0.xsd">
+
+            <route id="new_route_name" alias="original_route_name">
+                <!-- this outputs the following generic deprecation message:
+                     Since acme/package 1.2: The "new_route_name" route alias is deprecated. You should stop using it, as it will be removed in the future. -->
+                <deprecated package="acme/package" version="1.2"/>
+
+                <!-- you can also define a custom deprecation message (%alias_id% placeholder is available) -->
+                <deprecated package="acme/package" version="1.2">
+                    The "%alias_id%" route alias is deprecated. Do not use it anymore.
+                </deprecated>
+            </route>
+        </routes>
+
+    .. code-block:: php
+
+        $routes->alias('new_route_name', 'original_route_name')
+            // this outputs the following generic deprecation message:
+            // Since acme/package 1.2: The "new_route_name" route alias is deprecated. You should stop using it, as it will be removed in the future.
+            ->deprecate('acme/package', '1.2', '')
+
+            // you can also define a custom deprecation message (%alias_id% placeholder is available)
+            ->deprecate(
+                'acme/package',
+                '1.2',
+                'The "%alias_id%" route alias is deprecated. Do not use it anymore.'
+            )
+        ;
+
+In this example, every time the ``new_route_name`` alias is used, a deprecation
+warning is triggered, advising you to stop using that alias.
+
+The message is actually a message template, which replaces occurrences of the
+``%alias_id%`` placeholder by the route alias name. You **must** have
+at least one occurrence of the ``%alias_id%`` placeholder in your template.
+
 .. _routing-route-groups:
 
 Route Groups and Prefixes
@@ -1828,6 +1936,8 @@ Use the ``RedirectController`` to redirect to other routes and URLs:
                 # * for temporary redirects, it uses the 307 status code instead of 302
                 # * for permanent redirects, it uses the 308 status code instead of 301
                 keepRequestMethod: true
+                # add this to remove the original route attributes when redirecting
+                ignoreAttributes: true
 
         legacy_doc:
             path: /legacy/doc