Allow to deprecate routes

Per #2905098-24: Change block entity form handler from 'off_canvas' to 'settings_tray', #2905098 is also affected by this. I explained the strategy that @dawehner and I developed in #2858482: Simplify REST routing: disallow requesting POST/PATCH in any format, make consistent, and why I think it also works for that issue.

#2858482: Simplify REST routing: disallow requesting POST/PATCH in any format, make consistent landed and added the first deprecated route.

In #2949167: Add the link template "add-form" to content entity types I have to rename some routes e.g. node.add should became entity.node.add_form. I am considering something like \Drupal\rest\RouteProcessor\RestResourceGetRouteProcessorBC for redirecting to the new route, but there is one thing that we cannot detect - a custom or contrib code checking for the route name. So this means that at some point we'll break something somewhere. Unfortunately I have no idea how we could deal with this beide having route aliases, but the feature request for that has been rejected in Symfony.

but there is one thing that we cannot detect - a custom or contrib code checking for the route name

Custom/contrib code linking to the old route name will continue to work just fine.

But yes, alterations or conditional logic (such as based on the current route match), that would still break. In the case of the REST routes, it was reasonable to assume that nobody was doing either of those things. More than 7 months after the commit, zero complaints. 🙏

After thinking again about this I am pretty convinced that something like \Drupal\rest\RouteProcessor\RestResourceGetRouteProcessorBC is really the way to go. I would generalize it and place it in the system module and let it find the deprecated and the new route through a route definition attribute. This is also allows us to deprecate a route without replacement in case we need to do this.

Additionally we need to ensure that \Drupal\Core\Routing\Router::doMatchCollection() finds the deprecated route, which is easy as we could add a new route attribute like new_route: foo.bar to the deprecated route. Then if we find a matching route having this attribute simply return the route foo.bar instead.

How do we deal with code checking the route name for incoming requests?

1. Do we communicate that developers should replace $route_name == 'old_route_name' with $route_name == 'old_route_name' ||  $route_name == 'new_route_name' in order to prepare for the removal of the deprecated route?
2. Or maybe introduce a new method for the comparison - \Drupal\Core\Routing\CurrentRouteMatch::checkRouteName($route_name), which will then first compare against the route name and then against the attribute value of new_route.

How do we deal with code checking the route name inside outbound route processors?
This is similar to the previous question, but here we don't have a route match. Maybe we need a global function for both cases, which when passed a deprecated route name will do the check properly, but will trigger a deprecated error stating that one should use the new name for the comparison. Maybe \Drupal\Core\Routing\RouteProvider::compareRouteNames($a, $b)?

----

P.S. I am just thinking out loud, so please don't judge me if that aren't any good proposals :).

I think this can be closed in favour of #3159210: Support route aliasing (Symfony 5.4) and allow deprecating the route name?

Yes let's mark it duplicate #3159210: Support route aliasing (Symfony 5.4) and allow deprecating the route name