Needs review
Project:
Drupal core
Version:
main
Component:
documentation
Priority:
Normal
Category:
Plan
Assigned:
Unassigned
Reporter:
Created:
13 Jan 2023 at 16:08 UTC
Updated:
12 Oct 2026 at 15:54 UTC
Jump to comment: Most recent
Came up during #2862564: Move Custom block library to Content when changing a route path need some way to deprecate the old one
Internal path
Add a route for the deprecated path. Name the route the same at the original adding ".bc" to the end. Set the path to the deprecated path. Add a controller, naming it to identify it as a redirect. Create the controller. The controller includes the
@trigger_error('...', E_USER_DEPRECATED)and the necessary logic to perform the redirect.For example:
entity.block_content_type.collection.bc: deprecated: package: 'drupal/core' version: '10.1.0' message: 'The route "entity.block_content_type.collection.bc" is deprecated in drupal:10.1.0 and is removed from drupal:11.0.0. Use "entity.block_content_type.collection" route instead. See https://www.drupal.org/node/3320855' path: '/admin/structure/block/block-content/types' defaults: _controller: '\Drupal\block_content\Controller\BlockContentController::blockContentTypeRedirect' options: _admin_route: TRUE requirements: _permission: 'administer blocks'use Drupal\Core\Routing\PathChangedHelper; use Drupal\Core\Routing\RouteMatchInterface; use Symfony\Component\HttpFoundation\Request; use Symfony\Component\HttpFoundation\RedirectResponse; // ... /** * Provides a redirect to the list of custom block types. * * @param \Drupal\Core\Routing\RouteMatchInterface $route_match * A route match object, used for the route name and the parameters. * @param \Symfony\Component\HttpFoundation\Request $request * The current request object. * * @return \Symfony\Component\HttpFoundation\RedirectResponse * * @deprecated in drupal:10.1.0 and is removed from drupal:11.0.0. Use * /admin/structure/block-content directly instead of * /admin/structure/block/block-content/types. * * @see https://www.drupal.org/node/3320855 */ public function blockContentTypeRedirect(RouteMatchInterface $route_match, Request $request): RedirectResponse { @trigger_error('The path /admin/structure/block/block-content/types is deprecated in drupal:10.1.0 and is removed from drupal:11.0.0. Use /admin/structure/block-content. See https://www.drupal.org/node/3320855.', E_USER_DEPRECATED); $helper = new PathChangedHelper($route_match, $request); $params = [ '%old_path' => $helper->oldPath(), '%new_path' => $helper->newPath(), '%change_record' => 'https://www.drupal.org/node/3320855', ]; $warning_message = $this->t('You have been redirected from %old_path. Update links, shortcuts, and bookmarks to use %new_path.', $params); $this->messenger()->addWarning($warning_message); $this->getLogger('block_content')->warning('A user was redirected from %old_path to %new_path. This redirect will be removed in a future version of Drupal. Update links, shortcuts, and bookmarks to use %new_path. See %change_record for more information.', $params); return $helper->redirect(); }
Come up with a solution
Ticket out
NA
NA
NA
NA
Comments
Comment #2
benjifisherLet's call this a documentation issue, not "other".
Maybe the end result should be a new section on Drupal deprecation policy, or a new sibling page.
Now that #3333383: Create a redirect for the new Block types path is fixed, we can start drafting the policy.
Comment #4
quietone commentedThe remaining tasks has, "Ticket out". That does that mean?
Comment #5
quietone commentedInternal path
Add a route for the deprecated path. Name the route the same at the original adding ".bc" to the end. Set the path to the deprecated path. Add a controller, naming it to identify it as a redirect. Create the controller. The controller includes the
@trigger_error('...', E_USER_DEPRECATED)and the necessary logic to perform the redirect.For example:
Comment #7
smustgrave commentedSo what's next for this one?
Comment #8
benjifisherWe should update the proposed text to use the
PathChangedHelperclass that we added in #3351750: Create BC redirects for children of changed paths. I just took care of that.Then we have to agree on where to add the documentation. I suggested something in Comment #2.
Comment #9
benjifisherOn second thought, #3159210: Support route aliasing (Symfony 5.4) and allow deprecating the route name is now fixed, so we should also update the comment in the YAML.
I have not deprecated a route before, but it is documented on https://www.drupal.org/about/core/policies/core-change-policies/how-to-d.... (Yes, that fragment works.) I think we do not want to use a route alias in this case: we want to create a redirect.
I updated the YAML snippet in the proposed resolution.
Comment #10
smustgrave commentedThe remaining task mentions ticketing out, not sure what we need to ticket out. Happy to help do that though.
Comment #11
benjifisher@smustgrave:
Looking at the revision history, I think that "Ticket out" was in the original revision, which you wrote.
Perhaps the idea is that this issue is for planning. Once we agree on the text and the place to add the documentation, we might have a separate issue for implementation (adding the new page). OTOH, that seems excessive: if we agree on the text and where to add it, then we should just do it in order to finish this issue.
Comment #12
smustgrave commentedThis page could be broken up I think but probably would live here I'd imagine https://www.drupal.org/about/core/policies/core-change-policies/how-to-d...