Problem/Motivation
For PHP code, we have a well-defined set of rules for how to do deprecations in a continuous upgrade path:
https://www.drupal.org/core/deprecation
For JavaScript, we haven't defined a deprecation strategy yet. Some JS frameworks, including React and Ember, already provide mechanisms for providing developer-facing warnings about deprecated code use that are similar to what Symfony (and now Drupal) have adopted.
Proposed resolution
- Adopt the same deprecation message format for JS as for PHP. It should include:
- What version the code was first deprecated in
- When it will be removed (the next major version)
- What to use instead.
- An @see tag linking the replacement.
- A link to the change record.
- Follow the same general best practices as we do for PHP, namely: public APIs should always provide BC and a deprecation. Internal APIs do not require BC and deprecations, but it's recommended to provide them unless there are substantial costs to doing so (in terms of maintainability, performance, etc.).
For #1, I've heard feedback from JavaScript contributors that since we're using a well-defined set of coding standards rules that's used outside Drupal, they don't want to add additional Drupalisms on top of that. However, for deprecations, I think all five of the things listed are important and so we might as well just use the same format as we do for PHP.
For #2, we'll need to actually define what's part of our public JS API vs. what is internal. There's an existing policy issue for that. I don't have it at the moment, but we should discuss that in that issue, not this one. :)
Remaining tasks
Run this by relevant maintainers (JS, frontend framework managers, release managers).