Problem/Motivation

Came up during #2862564: Move Custom block library to Content when changing a route path need some way to deprecate the old one

Proposed resolution

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();
  }

Remaining tasks

Come up with a solution
Ticket out

User interface changes

NA

API changes

NA

Data model changes

NA

Release notes snippet

NA

Comments

smustgrave created an issue. See original summary.

benjifisher’s picture

Component: other » documentation

Let'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.

Version: 10.1.x-dev » 11.x-dev

Drupal core is moving towards using a “main” branch. As an interim step, a new 11.x branch has been opened, as Drupal.org infrastructure cannot currently fully support a branch named main. New developments and disruptive changes should now be targeted for the 11.x branch, which currently accepts only minor-version allowed changes. For more information, see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

quietone’s picture

The remaining tasks has, "Ticket out". That does that mean?

quietone’s picture

Issue summary: View changes
Status: Active » Needs review

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:

# @todo Deprecate this route once
#   https://www.drupal.org/project/drupal/issues/3159210 is fixed, or remove
#   it in Drupal 11.
# @see https://www.drupal.org/node/3320855
entity.block_content_type.collection.bc:
  path: '/admin/structure/block/block-content/types'
  defaults:
    _controller: '\Drupal\block_content\Controller\BlockContentController::blockContentTypeRedirect'
  options:
    _admin_route: TRUE
  requirements:
    _permission: 'administer blocks'
  /**
   * Provides a redirect to the list of custom block types.
   *
   * @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(): 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);
    $route = 'entity.block_content_type.collection';
    $params = [
      '%old_path' => Url::fromRoute("$route.bc")->toString(),
      '%new_path' => Url::fromRoute($route)->toString(),
      '%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 $this->redirect($route, [], [], 301);
  }

Version: 11.x-dev » main

Drupal core is now using the main branch as the primary development branch. New developments and disruptive changes should now be targeted to the main branch.

Read more in the announcement.

smustgrave’s picture

So what's next for this one?

benjifisher’s picture

Issue summary: View changes

We should update the proposed text to use the PathChangedHelper class 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.

benjifisher’s picture

Issue summary: View changes

On 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.

smustgrave’s picture

The remaining task mentions ticketing out, not sure what we need to ticket out. Happy to help do that though.

benjifisher’s picture

@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.

smustgrave’s picture

This 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...