Create a "Deprecation notice/warning" banner/modal/etc. for (some) deprecated API calls

[tofumatt]

Right now we deprecate APIs in two releases, but we don't really alert users to what plugins are making deprecated APIs calls. We also always deprecate in two major versions, but it's possible in the future we want to deprecate in more than two versions.

If a plugin doesn't pay attention, eventually a user's editor will break and it will seem like it happened "unexpectedly".

Once a deprecation is imminent (1-2 versions away), we should show a modal/banner/etc. when a deprecated API is called and, if possible, flag the plugin that made the call. This will alert the user:

1. that they should contact their plugin author if the author themselves isn't aware of the deprecation
2. inform the user we aren't at fault for their editor's imminent breakage

[tofumatt]

iOS and MacOS do a great job of warning users that in future versions an app they use will no longer work:

[sarahmonster]

This sounds like a similar issue to #15206 and could probably be handled in tandem to ensure these notices are as user-friendly as possible whilst providing helpful prompts to developers.

[anyssa]

I am working on a mockup for this. I have two questions about this issue:

• What would be a good copywriting for this type of warning?
• What type of UI component would be best, consistency-wise? Modal, banner, alert?

[sarahmonster]

@anyssa thanks for looking into this!

1. In terms of copywriting, since it will be user-facing, I'd suggest to keep the copy as simple, friendly, and jargon-free as possible. If you aren't sure, it can be helpful to suggest a few variations, and we can provide you with feedback. We also have some copy guidelines specific to error messaging that you may find helpful.

2. In terms of which UI component to use, we have three options here in our existing component library. In decending order of hierarchy, these are: Modal (dialog), Notice (banner), and Snackbar. The design guidelines should help you choose which component would be best suited for this use case, but if they aren't clear, that's a good opportunity to revise those guidelines for improved clarity! 😉

[noisysocks]

I'm not sure that this is worth doing now that our API is more stable. We use deprecated() a lot less than we used to, and, when we do, it's rare that we specify a version where the API will be removed.

@youknowriad @aduth: What do you think?

[youknowriad]

I agree for the moment but I think at some point we need to discuss the deprecation strategy for Core in general. and having more prominent notices depending on the "stage" of the deprecation could be good.

I think we can close for the moment though.

[aduth]

I'll second @youknowriad on this. I think we'd need to revisit this if we do ever decide to schedule deprecations for removal. The main idea behind the plugin's deprecation policy (notably its two-release scheduling) was that deprecations could be made to be less impactful if they were both predictable and well-communicated. The two-version policy satisfies the first of these goals, but our communication (outside of this handbook page) has been lackluster, which this issue would aim to improve.

[noisysocks]

Closing this for now. Agree we will need to eventually think about deprecation more holistically. (Perhaps the next time we need to remove something major.)