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).
Comments
Comment #5
lauriiiClosed #2962344: [policy, no patch] Document how to handle deprecations in JavaScript as a duplicate to this.
Comment #6
xjmDiscussed with @lauriii. This issue is at least major, and at least a soft-blocker for #3051352: [Plan] Remove unused jQuery UI components and replace with a suite of contrib packages for the continuous upgrade path. It might be critical.
Comment #7
lauriiiComment #8
lauriiiThis doesn't go against our current coding standards. JSDoc already supports @deprecated , but it doesn't specify any guidelines around content of the message. I think it's acceptable for us to require stricter rules for the contents of deprecation messages as a project. Various projects have defined their own deprecation message standards, so I would say that isn't unexpected.
We should also open follow-up for building system for triggering warnings whenever deprecated APIs are being used.
Comment #9
xjmBased on #8 I think we can go ahead and adopt this. Followups needed:
console.log()(or whatever) if@deprecatedJS is calledComment #10
GrandmaGlassesRopeManProbably want to use `console.warn()`
Comment #11
lauriiiOpened a follow-up to discuss how we want to trigger deprecation notices: #3070521: Trigger deprecation notifications on JavaScript deprecations to notify developers that deprecated code is being used.
Comment #12
lauriiiIt doesn't seem like anyone has strong concerns on this, so I'm moving this to RTBC.
Comment #13
larowlanI think after https://www.drupal.org/core/deprecation is updated with a Javscript section, this can be marked fixed.
Needs work for that.
Comment #14
lauriiiDocumented this in the documentation page. Moving back to RTBC.
Comment #15
wim leersLGTM! Only made a minor formatting improvement.
Comment #16
catchThanks everyone!
Comment #18
xjmWe'll want to mention the new JS deprecation process (and the error-triggering followup) in the release notes, since these have disruptive impacts (by adding new workflows).