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

  1. 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.
  2. 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

xjm created an issue. See original summary.

Version: 8.5.x-dev » 8.6.x-dev

Drupal 8.5.0-alpha1 will be released the week of January 17, 2018, which means new developments and disruptive changes should now be targeted against the 8.6.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.6.x-dev » 8.7.x-dev

Drupal 8.6.0-alpha1 will be released the week of July 16, 2018, which means new developments and disruptive changes should now be targeted against the 8.7.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.7.x-dev » 8.8.x-dev

Drupal 8.7.0-alpha1 will be released the week of March 11, 2019, which means new developments and disruptive changes should now be targeted against the 8.8.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

lauriii’s picture

xjm’s picture

lauriii’s picture

lauriii’s picture

Issue tags: +Needs followup

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.

This 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.

xjm’s picture

Status: Active » Needs review

Based on #8 I think we can go ahead and adopt this. Followups needed:

  1. console.log() (or whatever) if @deprecated JS is called
  2. See if we can warn about them in functional JS tests
  3. Try to detect them in static analysis
  4. Potentially add an eslint rule extending the AirBnb standard with our rule format, similar to our phpcs rule for PHP deprecations.
GrandmaGlassesRopeMan’s picture

Probably want to use `console.warn()`

lauriii’s picture

lauriii’s picture

Status: Needs review » Reviewed & tested by the community

It doesn't seem like anyone has strong concerns on this, so I'm moving this to RTBC.

larowlan’s picture

Status: Reviewed & tested by the community » Needs work

I think after https://www.drupal.org/core/deprecation is updated with a Javscript section, this can be marked fixed.

Needs work for that.

lauriii’s picture

Status: Needs work » Reviewed & tested by the community

Documented this in the documentation page. Moving back to RTBC.

wim leers’s picture

LGTM! Only made a minor formatting improvement.

catch’s picture

Status: Reviewed & tested by the community » Fixed

Thanks everyone!

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.

xjm’s picture

Issue tags: +8.8.0 release notes

We'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).