WordPress CS 3.0.0 planning & roadmap

[jrfnl]

Work on WordPressCS 3.0.0 will start in the near future. @GaryJones, @dingo-d and me have recently had a call to discuss what we envision for WPCS 3.0.0.

This issue is intended to keep track of what needs to be done, as well as give openness about the changes envisioned for WPCS 3.0.0.

Milestone: https://github.com/WordPress/WordPress-Coding-Standards/milestone/25

Planning:

• Ready when it's ready.
• Most of the initial PRs are tentatively expected in the second half of April/beginning of May (2020) July 2020.
• There will be at least one release candidate before the actual release of WPCS 3.0.0.

Environment changes:

• The minimum PHPCS requirement will go up to - at least - PHPCS 3.5.0.
• WPCS will get two (three) new dependencies:
  • PHPCSUtils - a set of utility functions and other helpers for sniff writers
  • PHPCSExtra - a set of generic sniffs
  • The DealerDirect Composer PHPCS plugin - this is a dependency of the above two packages, so we will automatically benefit from it.
• The installation instructions will change.
  • A Composer based project/global install will be the recommended and only supported manner of installation.
  • Stand-alone installation from a downloaded zip file, using a git clone or using composer create-project will still be possible, but no support will be given for those installations.

Note: PHPCSUtils and PHPCSExtra both are on 1.0.0-alphaX releases at the time of writing this.
The first stable 1.0.0 for both will be tagged before the first WPCS 3.0.0 RC will be (pre-)released.

Roadmap / what needs to be done:

• Update the environment files (composer.json, .travis.yml etc) to allow the changes to be made. - PR 3.0: Composer: set the new requirements for WPCS #1905
• Remove all previously deprecated code - WPCS 3.0: Remove the deprecated Sniff::has_whitelist_comment() method #1583, WPCS 3.0.0: Remove deprecated WP.TimezoneChange sniff #1819 - PRs 3.0: Remove deprecated Sniff::has_whitelist_comment() method and all references to it #1908, 3.0: Remove the WordPress.WP.TimezoneChange sniff #1909
• Remove all sniffs which can be replaced by upstream sniffs now the minimum PHPCS version has been upped (if any) and add the PHPCS native sniff to the ruleset(s) instead. - PR 3.0: Replace the WordPress.CodeAnalysis.EmptyStatement sniff #1910
• Remove all sniffs which can be replaced by sniffs in the PHPCSExtra standard and add the PHPCSExtra sniff to the ruleset(s) instead. - PR 3.0: Replace the WordPress.PHP.DisallowShortTernary sniff #1911, 3.0: Replace the WordPress.WhiteSpace.DisallowInlineTabs sniff #1912, 3.0: Replace the WordPress.PHP.StrictComparisons sniff #1919, 3.0: Core: replace Generic.Arrays.DisallowShortArraySyntax with Universal version #1920 (more to come)
• Remove all WPCS native utility methods which can be replaced by utility methods from PHPCSUtils and adjust the function calls to these methods in individual sniffs. Part 1: PR 3.0: Remove the PHPCSHelper class #1922, Part 2: PR 3.0: Remove some utility methods from the Sniff class #1926
• Review every individual sniff for opportunities to simplify the code and/or fix "modern PHP" bugs by using utilities from PHPCSUtils.
  Where applicable, add extra unit tests to the sniff to demonstrate bugs fixed and safeguard this for the future.
  See the checklist in the comment below for status
• Once available, switch over to using the Class/Function/FunctionParam abstracts from PHPCSUtils for all sniffs using the WPCS native abstracts for these type of sniffs. (expected partially in PHPCSUtils alpha 3, partially in alpha 4).
• Once all sniffs using a particular type of WPCS native abstract sniff have been switched over, remove the WPCS native version of that abstract sniff.
• Of the remaining utility methods/properties in the WPCS native Sniff class: aside from generically useful methods, move most methods and properties to traits which target something specific. Also see Extract re-usable code from Sniff.php into new package #1465 (@jrfnl)
• If any WPCS sniffs extend another sniff, while the other sniff is also included in one of the WPCS rulesets, split the logic being re-used off into a trait and let the sniffs use the trait, instead of one sniff extending another as this is known to be buggy with the PHPCS autoloader.
• Go through the Make blog post and find relevant sniffs to add. (@jrfnl)
• For those things in the Make blog post for which there are no existing sniffs in either PHPCS itself or PHPCSExtra, open an issue to create this sniff.
  Generically usable sniffs should be added to PHPCSExtra, WP or WPCS specific sniffs should be added to WPCS itself.
  Note: these do not all need to be addressed in WPCS 3.0.0. Additional sniffs can be added in minors, so some issues may be left to address later.
• Go through the 3.0.0 milestone and address what else needs addressing.
• Go through the open issues to see if there are any issues which can now be more easily addressed with the utilities from PHPCSUtils and either send in a PR or milestone the issue for a later 3.x release.
• Go through the open PRs, especially the ones which have been abandoned, and either update them to make them mergable if the author is no longer responding or close them.
• Review the rulesets for any other sniffs replacements/tweaks which can/should be made.
• Update the README and the CONTRIBUTING files for the new reality.
• Write an "Upgrade Guide" for external standards which use(d) the utilities in WPCS to be added to the wiki.
• Create the changelog ;-)

I've tried to be complete here, but please feel free to leave comments about anything I've forgotten in this list ;-)

[jrfnl]

Oh and just in case anyone is wondering about the date: no this amount of work is no joke 😂

[jrfnl]

Status of sniff review & priorities:

To review - prio 1:

All done

To review - prio 2:

Code in the sniff (if any) itself can be reviewed already. Underlying abstract sniff logic is expected to be replaced with an abstract from PHPCSUtils.

All done

To review - prio 3:

All done

Leave alone for now as these will probably be (partially) replaced with a sniff from PHPCSExtra:

• WordPress.Classes.ClassInstantiation (removed)
• WordPress.WhiteSpace.PrecisionAlignment (removed)

Reviewed & changes pulled:

• Sniff base class, including addressing Extract re-usable code from Sniff.php into new package #1465 (@jrfnl) - various PRs
• WordPress.Arrays.ArrayDeclarationSpacing (@jrfnl) - Arrays/ArrayDeclarationSpacing: partially replace the sniff + implement PHPCSUtils in what remains #2301
• WordPress.Arrays.ArrayIndentation (@jrfnl) - Arrays/ArrayIndentation: implement PHPCSUtils #2196
• WordPress.Arrays.ArrayKeySpacingRestrictions (@jrfnl) - Arrays/ArrayKeySpacingRestrictions: implement PHPCSUtils and various bug fixes and other improvements #2075
• WordPress.Arrays.CommaAfterArrayItem (@jrfnl) - Arrays/CommaAfterArrayItem: minor tweaks #2151
• WordPress.Arrays.MultipleStatementAlignment (@jrfnl) - Arrays/MultipleStatementAlignment: implement PHPCSUtils #2194
• WordPress.CodeAnalysis.AssignmentInCondition (@jrfnl) - CodeAnalysis/AssignmentInCondition: defer to upstream, implement PHPCSUtils & support modern PHP #2198
• WordPress.CodeAnalysis.EscapedNotTranslated (@jrfnl) - EscapedNotTranslated: use PHPCSUtils GetTokensAsString #1941
• WordPress.DateTime.CurrentTimeTimestamp (@jrfnl) - DateTime/CurrentTimeTimestamp: add support for PHP 8.0+ named parameters + minor tweak #2160
• WordPress.DB.DirectDatabaseQuery (@jrfnl) - DB/DirectDatabaseQuery: implement PHPCSUtils and support modern PHP  #2186
• WordPress.DB.PreparedSQL (@jrfnl) - DB/PreparedSQL: implement PHPCSUtils and support modern PHP  #2188
• WordPress.DB.PreparedSQLPlaceholders (@jrfnl) - DB/PreparedSQLPlaceholders: use PHPCSUtils, allow for modern PHP and some bug fixes #2314
• WordPress.Files.FileName (@jrfnl) - Files/FileName: implement PHPCSUtils, exclude test files and more tweaks #2154
• WordPress.NamingConventions.PrefixAllGlobals (@jrfnl) - NamingConventions/PrefixAllGlobals: implement PHPCSUtils and support modern PHP  #2185
• WordPress.NamingConventions.ValidFunctionName (@jrfnl) - 3.0: ValidFunctionName: implement PHPCSUtils and more #1931
• WordPress.NamingConventions.ValidHookName (@jrfnl) - NamingConventions/ValidHookName: implement PHPCSUtils and support modern PHP #2166
• WordPress.NamingConventions.ValidPostTypeSlug (@jrfnl) - NamingConventions/ValidPostTypeSlug: implement PHPCSUtils and support modern PHP #2167
• WordPress.NamingConventions.ValidVariableName (@jrfnl) - NamingConventions/ValidVariableName: implement PHPCSUtils and support modern PHP #2192
• WordPress.PHP.IniSet (@jrfnl) - PHP/IniSet: add support for PHP 8.0+ named parameters + bug fix #2161
• WordPress.PHP.NoSilencedErrors (@jrfnl) - PHP/NoSilencedErrors: implement PHPCSUtils methods #2162
• WordPress.PHP.PregQuoteDelimiter (@jrfnl) - PHP/PregQuoteDelimiter: add support for PHP 8.0+ named parameters #2139
• WordPress.PHP.StrictInArray (@jrfnl) - PHP/StrictInArray: prevent some false positives #2163
• WordPress.PHP.YodaConditions (@jrfnl) - PHP/YodaConditions: implement PHPCSUtils + more tweaks #2152
• WordPress.Security.EscapeOutput (@jrfnl) - Security/EscapeOutput: use PHPCSUtils, allow for modern PHP and slew of bug fixes #2326
• WordPress.Security.NonceVerification (@jrfnl) - Security/NonceVerification: use PHPCSUtils, modern PHP + other bug fixes #2297
• WordPress.Security.PluginMenuSlug (@jrfnl) - Security/PluginMenuSlug: implement PHPCSUtils and support modern PHP #2168
• WordPress.Security.ValidatedSanitizedInput (@jrfnl) - Security/ValidatedSanitizedInput: use PHPCSutils and bug fixes #2362
• WordPress.Utils.I18nTextDomainFixer (@jrfnl) - Utils/I18nTextDomainFixer: implement PHPCSUtils and support modern PHP  #2195
• WordPress.WhiteSpace.CastStructureSpacing (@jrfnl) - CastStructureSpacing: minor error message improvement #1928
• WordPress.WhiteSpace.ControlStructureSpacing - also see issues "No space after opening parenthesis is prohibited" when using traits #1071 and Function declaration verification #1101 (@jrfnl) - Whitespace/ControlStructureSpacing: sync with upstream + minor tweaks #2333
• WordPress.WhiteSpace.OperatorSpacing (@jrfnl) - OperatorSpacing: defer to upstream for "instanceof" #1930
• WordPress.WP.AlternativeFunctions (@jrfnl) - WP/AlternativeFunctions: implement PHPCSUtils and support modern PHP #2169
• WordPress.WP.CapitalPDangit (@jrfnl) - 3.0: CapitalPDangit: implement PHPCSUtils and check namespace names #1929 + WP/CapitalPDangit: implement PHPCSUtils and support modern PHP #2170
• WordPress.WP.CronInterval (@jrfnl) - WP/CronInterval: implement PHPCSUtils and support modern PHP  #2172
• WordPress.WP.DeprecatedFunctions (@jrfnl) - Update the minimum_wp_version to WP 5.8 #2121
• WordPress.WP.DeprecatedParameterValues (@jrfnl) - WP/DeprecatedParameterValues: support modern PHP + update for WP 6.1 #2174
• WordPress.WP.DeprecatedParameters (@jrfnl) - WP/DeprecatedParameters: add support for PHP 8.0+ named parameters #2138 + WP/DeprecatedParameters: verify against WP Core #2173
• WordPress.WP.DiscouragedConstants (@jrfnl) - WP/DiscouragedConstants: implement PHPCSUtils and support modern PHP  #2175
• WordPress.WP.EnqueuedResourceParameters (@jrfnl) - WP/EnqueuedResourceParameters: implement PHPCSUtils and support modern PHP #2177
• WordPress.WP.EnqueuedResources (@dingo-d + @jrfnl) - WP/EnqueuedResources: various tweaks #2176
• WordPress.WP.GlobalVariablesOverride (@jrfnl) - WP/GlobalVariablesOverride: implement PHPCSUtils and support modern PHP #2181
• WordPress.WP.I18n (@jrfnl) - WP/I18n: complete refactor, implement PHPCSUtils, modern PHP and more #2214

Verified / No (extra) changes needed:

• WordPress.DateTime.RestrictedFunctions (@jrfnl)
  Note: the underlying abstract for this sniff is still subject to change.
• WordPress.DB.RestrictedClasses (@jrfnl)
  Note: the underlying abstract for this sniff is still subject to change.
• WordPress.DB.RestrictedFunctions (@jrfnl)
  Note: the underlying abstract for this sniff is still subject to change.
• WordPress.DB.SlowDBQuery (@jrfnl)
  Note: the underlying abstract for this sniff is still subject to change.
• WordPress.PHP.DevelopmentFunctions (@jrfnl)
  Note: the underlying abstract for this sniff is still subject to change.
• WordPress.PHP.DiscouragedPHPFunctions (@jrfnl)
  Note: the underlying abstract for this sniff is still subject to change.
• WordPress.PHP.DontExtract (@jrfnl)
  Note: this sniff will probably be replaced by one from Extra.
• WordPress.PHP.POSIXFunctions (@jrfnl)
  Note: the underlying abstract for this sniff is still subject to change.
• WordPress.PHP.RestrictedPHPFunctions (@jrfnl)
  Note: the underlying abstract for this sniff is still subject to change.
• WordPress.PHP.TypeCasts (@jrfnl)
• WordPress.Security.SafeRedirect (@jrfnl)
  Note: the underlying abstract for this sniff is still subject to change.
• WordPress.WP.DeprecatedClasses (@jrfnl)
  Note: the underlying abstract for this sniff is still subject to change.
• WordPress.WP.DiscouragedFunctions (@jrfnl)
  Note: the underlying abstract for this sniff is still subject to change.
• WordPress.WP.PostsPerPage (@jrfnl)
  Note: the underlying abstract for this sniff is still subject to change.

Please add your name to the sniff to claim it or leave a comment in this thread.

[shivapoudel]

@jrfnl Deal direct is not supported for PHP 8.0, will that be patched in WPCS 3.0.0?

[jrfnl]

@shivapoudel The DealerDirect plugin is a dev dependency in WPCS 2.x, so should not be a concern of an end-user (other than that they should probably require-dev it in their own project).
As of WPCS 3.x, it will be a no-dev dependency via the PHPCSUtils library and will allow for a wide range of versions.

[GaryJones]

Also, as per https://github.com/Dealerdirect/phpcodesniffer-composer-installer/pull/132/files#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5R34 the dealerdirect plugin has had PHP 8 support since 0.7.0 (see the releases).

[shivapoudel]

@jrfnl @GaryJones This is the error I am receiving currently with PHP 8.0.

$ composer create-project wp-coding-standards/wpcs --no-dev
Creating a "wp-coding-standards/wpcs" project at "./wpcs"
Warning from https://repo.packagist.org: Support for Composer 1 is deprecated and some packages will not be available. You should upgrade to Composer 2. See https://blog.packagist.com/deprecating-composer-1-support/
Installing wp-coding-standards/wpcs (2.3.0)
  - Installing wp-coding-standards/wpcs (2.3.0): Loading from cache
Created project in C:\Users\shiva\wpcs
Loading composer repositories with package information
Warning from https://repo.packagist.org: Support for Composer 1 is deprecated and some packages will not be available. You should upgrade to Composer 2. See https://blog.packagist.com/deprecating-composer-1-support/
Updating dependencies
Your requirements could not be resolved to an installable set of packages.

  Problem 1
    - dealerdirect/phpcodesniffer-composer-installer v0.6.2 requires php ^5.3|^7 -> your PHP version (8.0.0) does not satisfy that requirement.
    - dealerdirect/phpcodesniffer-composer-installer v0.6.1 requires php ^5.3|^7 -> your PHP version (8.0.0) does not satisfy that requirement.
    - dealerdirect/phpcodesniffer-composer-installer v0.6.0 requires php ^5.3|^7 -> your PHP version (8.0.0) does not satisfy that requirement.
    - dealerdirect/phpcodesniffer-composer-installer v0.5.0 requires php ^5.3|^7 -> your PHP version (8.0.0) does not satisfy that requirement.
    - Installation request for dealerdirect/phpcodesniffer-composer-installer ^0.5 || ^0.6 -> satisfiable by dealerdirect/phpcodesniffer-composer-installer[v0.5.0, v0.6.0, v0.6.1, v0.6.2].

Running update with --no-dev does not mean require-dev is ignored, it just means the packages will not be installed. If dev requirements are blocking the update you have to resolve those problems.

Now lets see if everything is compatible with latest stable composer. I am giving it a try:

$ composer self-update --2
Updating to version 2.1.3 (2.x channel).
   Downloading (100%)
Use composer self-update --rollback to return to version 1.10.22

Again receiving some sort of dealerdirect problems:

$ composer create-project wp-coding-standards/wpcs --no-dev
Creating a "wp-coding-standards/wpcs" project at "./wpcs"
Installing wp-coding-standards/wpcs (2.3.0)
  - Installing wp-coding-standards/wpcs (2.3.0): Extracting archive
Created project in C:\Users\shiva\wpcs
Loading composer repositories with package information
Updating dependencies
Your requirements could not be resolved to an installable set of packages.

  Problem 1
    - dealerdirect/phpcodesniffer-composer-installer[v0.5.0, ..., v0.6.2] require php ^5.3|^7 -> your php version (8.0.0) does not satisfy that requirement.
    - Root composer.json requires dealerdirect/phpcodesniffer-composer-installer ^0.5 || ^0.6 -> satisfiable by dealerdirect/phpcodesniffer-composer-installer[v0.5.0, v0.6.0, v0.6.1, v0.6.2].

Running update with --no-dev does not mean require-dev is ignored, it just means the packages will not be installed. If dev requirements are blocking the update you have to resolve those problems.

[jrfnl]

@dingo-d and me had a long call today discussing how to move forward and get WPCS 3.0.0 in a releasable state.

Aside from everything discussed above (and overlapping it), we came to the conclusion that there are four big things which need to be addressed and we intend to take action on these in the near future:

1. Implement all non-disputed rules from the March 2020 Make post, in as far as there are ready-made sniffs available for it already.
   Everything that still needs a new sniff to be written for it, can be actioned in later 3.x versions.
2. Implement PHPCSUtils anywhere and everywhere.
3. Add support to all sniffs for PHP 7.4, 8.0 and 8.1 syntaxes, in so far they are currently supported by PHPCS itself.
   This also means preventing false positives/negatives related to those new syntaxes.
   We strongly recommend updating the minimum supported PHPCS version to 3.7.0 as soon as it is released, which should be before WPCS 3.0.0 is ready for its new release. This will prevent a lot of issues and having to introduce work-arounds for new syntaxes.
4. Move generic utilities which are NOT moving to PHPCSUtils to traits to allow us to switch the abstract sniff used by sniffs in the future without that being a breaking change.

Of course, other generic maintenance actions, like updating the global variables list, updating deprecated function lists etc should all be executed as well before release.