Last 3.x minor | Hard deprecate sniffs setting the `$supportedTokenizers` property

[jrfnl]

Support for the JS and CSS Tokenizers will be removed in PHPCS 4.0.

This was announced in squizlabs/PHP_CodeSniffer#2448 and has been formalized via a soft deprecation (documentation and changelog only) in the PHPCS 3.9.0 release (see #276).

A deprecation notice should be shown for sniffs which comply with these conditions:

1. Set the (public) $supportedTokenizers property on a sniff to a value which does not include PHP.
2. Do not implement the DeprecatedSniff interface (see ✨ Native handling of sniff deprecations #281).

To be determined

I'm not yet sure what to do about sniffs which set the property to a value which includes both PHP as well as CSS and/or JS.
Throwing a deprecation notice for those feels noisy, as removing support for CSS/JS from the sniff would be a breaking change and would therefore require a new major release, so a deprecation notice would not be actionable for sniff maintainers (including for PHPCS itself).

Opinions welcome.

[jrfnl]

Realized I'd forgotten the /cc list. Oops.

Would value some opinions on the "To be determined" part of this issue.

/cc @asispts @dingo-d @fredden @GaryJones @greg0ire @kukulich @michalbundyra @Ocramius @sirbrillig @stronk7 @weierophinney @wimg

[sirbrillig]

It's a good question. 🤔 We want the maintainers of those libraries to be aware of the upcoming breaking change while still allowing them to continue using the old version without disruption. It makes me wonder how other libraries deal with this sort of situation. I think that React prints deprecation warnings before a major version change, but in a browser, console messages are usually hidden from the user unless they opt-in by opening the console. As a command-line application, we have to be much more careful about how we notify users. I wonder if there's some way to let developers opt-in to deprecation notices for the next version?

[jrfnl]

@sirbrillig Well, at this time, PHPCS doesn't even have a mechanism to show these type of Ruleset related deprecations yet 😁

It's one of the things I'm working on for the 3.12.0 release.

So, let's take it one step at a time for now.

1. First get the mechanism to improve the error handling in the Ruleset in place.
2. Next, as per this and a few other issues, show actionable deprecation notices in the last 3.x minor.
3. Iterate and improve on that mechanism.
   And yes, I welcome suggestions for that, but we're not there yet.

As for this particular change, I would kind of hope that all active maintainers of external standards are aware of it by now, what with the actual change having been announced over five years ago ;-)