Allow deprecating theme suggestions

Forgot about this. Rerolled, still needs docs update and a change record.

Created a change record and added an example hook_theme_suggestions_HOOK(), do we need to duplicate that into the alter hooks?

Fun fact on:

Also unsure what to do about $node/comment->view and the preprocess code.

In the meantime, we added the mechanism to deprecate $variables['view'] and did that, but only for node and not comment.

The approach is quite similar, but there we just used 'deprecations' key. I wonder if we should align this, it's not prefixed in a special way, but it won't conflict with a real key.

The addition of $variables['theme_hook_suggestions__DEPRECATED'] is intentional. It separates deprecated theme suggestions from the active ones to avoid affecting template rendering while still enabling deprecation logging or debug output. This approach maintains backward compatibility with existing template engines and aligns with the goal of safely phasing out deprecated suggestions.

Thanks for clarifying, your explanation makes sense. Updating the comment sounds good to me!

Ran test-only job here https://git.drupalcode.org/issue/drupal-3159050/-/jobs/6072924 not posting as it's massive.

Manually tested by following the step and using the "test_deprecated_suggestion_theme" theme

CR seems clear about how to deprecate, and example is nice.

Hiding patches as fix is in the MR.

Believe this one is good to go.

Read back through this issue and discovered me marking it needs work from RTBC in 2021, feel bad that ended up stalling it until now.

Still looks good and the docs are much better now. Committed/pushed to 11.x, thanks!

Can't wait to unpostpone #1367354: [PP-1] The list of theme hook suggestions for "field" is incorrectly ordered and has namespacing collisions → .

catch → closed merge request !12704