Theme suggestions can now be deprecated

It is now possible to deprecate theme suggestions. Using the special __DEPRECATED key, list each deprecated theme suggestion, next to its definition with the deprecation message as value.

/**
 * Implements hook_theme_suggestions_alter().
 */
function MODULE_suggestions_alter(array &$suggestions, array $variables, $hook): void {
  if ($hook == 'theme_test_suggestion_provided') {
    // Add a deprecated suggestion.
    $suggestions[] = 'theme_test_suggestion_provided__deprecated';
    $suggestions['__DEPRECATED']['theme_test_suggestion_provided__deprecated'] = 'Theme suggestion theme_test_suggestion_provided__deprecated is deprecated in drupal:X.0.0 and is removed from drupal:Y.0.0. This is a test.';
  }
}