4.0 | Deprecate and remove support for Standards called "Internal"

[jrfnl]

Current Situation

The Internal. reference prefix is solely intended for internal use, i.e. for error codes coming from PHPCS itself about the processing of a file, such as Internal.NoCodeFound.

However, while writing tests for the Ruleset class, I discovered, it is currently possible to name a standard Internal and have sniffs included from it.

Aside from this being confusing for end-users, the fact that this is (incidentally ?) supported may not be taken into account in all relevant places and I wouldn't be surprised if there are bugs to content with if a standard would be called Internal.

Proposal

• Soft deprecate support for a standard being called Internal in the next 3.x minor.
• Hard deprecate support for a standard being called Internal in what is expected to be the last 3.x minor.
• Remove support for including a standard called Internal in 4.0.0.

In practice, removing support will mean that if an Internal standard is requested via --standard=Internal or by including such a standard from within a ruleset via <rule ref="Internal"/>, the standard will no longer be read out and the sniffs no longer included. The end-user will be presented with a warning letting them know the standard is being disregarded.
If the Internal standard was the only referenced standard, the user will also be presented with a "No sniffs were registered" error.

Terminology used

Soft deprecation: deprecation via changelog mention and/or announcement only.
Hard deprecation: a deprecation notice will be shown at runtime, but will not affect the exit code of PHPCS.

Impact

It is not expected that there are any external standards in existence which are called Internal, so the impact is expected to be nill.

Code searches of public code executed to confirm this:

• https://sourcegraph.com/search?q=context:global+file:ruleset.xml+name%3D%22Internal%22&patternType=keyword&sm=0
• https://github.com/search?q=name%3D%22Internal%22+path%3A**%2Fruleset.xml&type=code&ref=advsearch

Related issues

Loosely related to #689

Opinions ?

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

[sirbrillig]

This sounds quite reasonable to me.

[weierophinney]

I'm of two minds about it.

In terms of the process of deprecation, that looks fine.

The part I'm not so sure about: I could see companies using "Internal" for their own... internal rulesets. This would effectively mean they would need to name them some other way. While you won't see these in public repos, the question is really how many private orgs are using that.

[jrfnl]

The part I'm not so sure about: I could see companies using "Internal" for their own... internal rulesets. This would effectively mean they would need to name them some other way. While you won't see these in public repos, the question is really how many private orgs are using that.

@weierophinney That's a fair point and I did consider that, but it is also a situation which is currently only partially supported, so I still consider it highly unlikely that companies would be using a standard called Internal due to the existing problems with them.

To illustrate:

<rule ref="Internal"/>

☝🏻 The above works and will load all the sniffs in the standard.

<rule ref="Internal.MyCategory"/>
<rule ref="Internal.OtherCategory.SniffName"/>
<rule ref="Internal.ACategory.SniffName.ErrorCode"/>

☝🏻 None of the above will work and each of these includes will currently silently be ignored.

[jrfnl]

FYI: PR #893 is now open to add a deprecation notice for this.