Merge pull request #2369 from WordPress/develop

Release WordPressCS 3.0.0

.codecov.yml

@@ -0,0 +1,21 @@
+codecov:
+  notify:
+    after_n_builds: 4
+
+coverage:
+  round: nearest
+  # Status will be green when coverage is between 90 and 100%.
+  range: "90...100"
+  status:
+    project:
+      default:
+        target: auto
+        threshold: 1%
+        paths:
+          - "WordPress"
+    patch: off
+
+ignore:
+  - "WordPress/Tests"
+
+comment: false

.gitattributes

@@ -1,19 +1,23 @@
 #
 # Exclude these files from release archives.
 # This will also make them unavailable when using Composer with `--prefer-dist`.
-# If you develop for WPCS using Composer, use `--prefer-source`.
+# If you develop for WordPressCS using Composer, use `--prefer-source`.
 # https://blog.madewithlove.be/post/gitattributes/
 #
-/.travis.yml export-ignore
-/.phpcs.xml.dist export-ignore
-/phpunit.xml.dist export-ignore
-/.github export-ignore
-/bin export-ignore
-/WordPress/Tests export-ignore
+/.gitattributes     export-ignore
+/.gitignore         export-ignore
+/.codecov.yml       export-ignore
+/.phpcs.xml.dist    export-ignore
+/CODE_OF_CONDUCT.md export-ignore
+/phpstan.neon.dist  export-ignore
+/phpunit.xml.dist   export-ignore
+/.github            export-ignore
+/Tests              export-ignore
+/WordPress/Tests    export-ignore
 
 #
 # Auto detect text files and perform LF normalization
-# http://davidlaing.com/2012/09/19/customise-your-gitattributes-to-become-a-git-ninja/
+# https://pablorsk.medium.com/be-a-git-ninja-the-gitattributes-file-e58c07c9e915
 #
 * text=auto
 

.github/CONTRIBUTING.md

@@ -11,17 +11,20 @@ Bug reports containing a minimal code sample which can be used to reproduce the
 
 ## Upstream Issues
 
-Since WPCS employs many sniffs that are part of PHPCS, sometimes an issue will be caused by a bug in PHPCS and not in WPCS itself. If the error message in question doesn't come from a sniff whose name starts with `WordPress`, the issue is probably a bug in PHPCS itself, and should be [reported there](https://github.com/squizlabs/PHP_CodeSniffer/issues).
+Since WordPressCS employs many sniffs that are part of PHP_CodeSniffer itself or PHPCSExtra, sometimes an issue will be caused by a bug in PHPCS or PHPCSExtra and not in WordPressCS itself.
+If the error message in question doesn't come from a sniff whose name starts with `WordPress`, the issue is probably a bug in PHPCS or PHPCSExtra.
+
+* Bugs for sniffs starting with `Generic`, `PEAR`, `PSR1`, `PSR2`, `PSR12`, `Squiz` or `Zend` should be [reported to PHPCS](https://github.com/squizlabs/PHP_CodeSniffer/issues).
+* Bugs for sniffs starting with `Modernize`, `NormalizedArrays` or `Universal` should be [reported to PHPCSExtra](https://github.com/PHPCSStandards/PHPCSExtra/issues).
 
 # Contributing patches and new features
 
 ## Branches
 
-Ongoing development will be done in the `develop` branch with merges done into `master` once considered stable.
-
-To contribute an improvement to this project, fork the repo and open a pull request to the `develop` branch. Alternatively, if you have push access to this repo, create a feature branch prefixed by `feature/` and then open an intra-repo PR from that branch to `develop`.
+Ongoing development will be done in the `develop` branch with merges to `main` once considered stable.
 
-Once a commit is made to `develop`, a PR should be opened from `develop` into `master` and named "Next release". This PR will provide collaborators with a forum to discuss the upcoming stable release.
+To contribute an improvement to this project, fork the repo, run `composer install`, make your changes to the code, run the unit tests and code style checks by running `composer check-all`, and if all is good, open a pull request to the `develop` branch.
+Alternatively, if you have push access to this repo, create a feature branch prefixed by `feature/` and then open an intra-repo PR from that branch to `develop`.
 
 # Considerations when writing sniffs
 
@@ -32,105 +35,87 @@ Only make a property `public` if that is the intended behaviour.
 
 When you introduce new `public` sniff properties, or your sniff extends a class from which you inherit a `public` property, please don't forget to update the [public properties wiki page](https://github.com/WordPress/WordPress-Coding-Standards/wiki/Customizable-sniff-properties) with the relevant details once your PR has been merged into the `develop` branch.
 
-## Whitelist comments
-
-> **Important**:
-> PHPCS 3.2.0 introduced new selective ignore annotations, which can be considered an improved version of the whitelist mechanism which WPCS contains.
->
-> Support for the WPCS native whitelist comments has been deprecated in WPCS 2.0.0 and will be removed in WPCS 3.0.0.
->
-> With that in mind, (new) sniffs should not introduce new WPCS native whitelist comments.
-
-
 # Unit Testing
 
 ## Pre-requisites
 * WordPress-Coding-Standards
-* PHP_CodeSniffer 3.3.1 or higher
+* PHP_CodeSniffer 3.7.2 or higher
+* PHPCSUtils 1.0.8 or higher
+* PHPCSExtra 1.1.0 or higher
 * PHPUnit 4.x, 5.x, 6.x or 7.x
 
-The WordPress Coding Standards use the `PHP_CodeSniffer` native unit test suite for unit testing the sniffs.
-
-Presuming you have installed `PHP_CodeSniffer` and the WordPress-Coding-Standards as [noted in the README](https://github.com/WordPress/WordPress-Coding-Standards#how-to-use-this), all you need now is `PHPUnit`.
-
-> N.B.: If you installed WPCS using Composer, make sure you used `--prefer-source` or run `composer install --prefer-source` now to make sure the unit tests are available.
-> Other than that, you're all set already as Composer will have installed PHPUnit for you.
+The WordPress Coding Standards use the `PHP_CodeSniffer` native unit test framework for unit testing the sniffs.
 
-If you already have PHPUnit installed on your system: Congrats, you're all set.
+## Getting ready to test
 
-## Installing PHPUnit
+Presuming you have cloned WordPressCS for development, to run the unit tests you need to make sure you have run `composer install` from the root directory of your WordPressCS git clone.
 
-N.B.: _If you used Composer to install the WordPress Coding Standards, you can skip this step._
+## Custom develop setups
 
-You can either navigate to the directory where the `PHP_CodeSniffer` repo is checked out and do `composer install` to install the `dev` dependencies or you can [install PHPUnit](https://phpunit.readthedocs.io/en/7.4/installation.html) as a PHAR file.
-
-You may want to add the directory where PHPUnit is installed to a `PATH` environment variable for your operating system to make the command available everywhere on your system.
-
-## Before running the unit tests
-
-N.B.: _If you used Composer to install the WordPress Coding Standards, you can skip this step._
-
-For the unit tests to work, you need to make sure PHPUnit can find your `PHP_CodeSniffer` install.
-
-The easiest way to do this is to add a `phpunit.xml` file to the root of your WPCS installation and set a `PHPCS_DIR` environment variable from within this file.
-Copy the existing `phpunit.xml.dist` file and add the below `<env>` directive within the `<php>` section. Make sure to adjust the path to reflect your local setup.
-```xml
-	<php>
-		<env name="PHPCS_DIR" value="/path/to/PHP_CodeSniffer/"/>
-	</php>
-```
+If you are developing with a stand-alone PHP_CodeSniffer (git clone) installation and want to use that git clone to test WordPressCS, there are three extra things you need to do:
+1. Install [PHPCSUtils](https://github.com/PHPCSStandards/PHPCSUtils).
+    If you are using a git clone of PHPCS, you may want to `git clone` PHPCSUtils as well.
+2. Register PHPCSUtils with your stand-alone PHP_CodeSniffer installation by running the following commands:
+    ```bash
+    phpcs --config-show
+    ```
+    Copy the value from "installed_paths" and add the path to your local install of PHPCSUtils to it (and the path to WordPressCS if it's not registered with PHPCS yet).
+    Now use the adjusted value to run:
+    ```bash
+    phpcs --config-set installed_paths /path/1,/path/2,/path/3
+    ```
+3. Make sure PHPUnit can find your `PHP_CodeSniffer` install.
+    The most straight-forward way to do this is to add a `phpunit.xml` file to the root of your WordPressCS installation and set a `PHPCS_DIR` environment variable from within this file.
+    Copy the existing `phpunit.xml.dist` file and add the below `<env>` directive within the `<php>` section. Make sure to adjust the path to reflect your local setup.
+    ```xml
+        <php>
+            <env name="PHPCS_DIR" value="/path/to/PHP_CodeSniffer/"/>
+        </php>
+    ```
 
 ## Running the unit tests
 
-* If you didn't install WPCS using Composer, make sure you have registered the directory in which you installed WPCS with PHPCS using:
-    ```sh
-    phpcs --config-set installed_paths path/to/WPCS
-    ```
-* Navigate to the directory in which you installed WPCS.
-* To run the unit tests:
-    ```sh
-    phpunit --filter WordPress --bootstrap="/path/to/PHP_CodeSniffer/tests/bootstrap.php" /path/to/PHP_CodeSniffer/tests/AllTests.php
+From the root of your WordPressCS install, run the unit tests like so:
+```bash
+composer run-tests
 
-    # Or if you've installed WPCS with Composer:
-    composer run-tests
-    ```
+# Or if you want to use a globally installed version of PHPUnit:
+phpunit --filter WordPress /path/to/PHP_CodeSniffer/tests/AllTests.php
+```
 
 Expected output:
 ```
-PHPUnit 7.5.0 by Sebastian Bergmann and contributors.
+PHPUnit 7.5.20 by Sebastian Bergmann and contributors.
 
-Runtime:       PHP 7.2.13
-Configuration: /WordPressCS/phpunit.xml
+Runtime:       PHP 7.4.33
+Configuration: /WordPressCS/phpunit.xml.dist
 
-........................................................          56 / 56 (100%)
+.........................................................         57 / 57 (100%)
 
-152 sniff test files generated 487 unique error codes; 52 were fixable (10.68%)
+201 sniff test files generated 744 unique error codes; 50 were fixable (6%)
 
-Time: 21.36 seconds, Memory: 22.00MB
+Time: 10.19 seconds, Memory: 40.00 MB
 
-OK (56 tests, 0 assertions)
+OK (57 tests, 0 assertions)
 ```
 
-[![asciicast](https://asciinema.org/a/98078.png)](https://asciinema.org/a/98078)
-
 ## Unit Testing conventions
 
 If you look inside the `WordPress/Tests` subdirectory, you'll see the structure mimics the `WordPress/Sniffs` subdirectory structure. For example, the `WordPress/Sniffs/PHP/POSIXFunctionsSniff.php` sniff has its unit test class defined in `WordPress/Tests/PHP/POSIXFunctionsUnitTest.php` which checks the `WordPress/Tests/PHP/POSIXFunctionsUnitTest.inc` test case file. See the file naming convention?
 
 Lets take a look at what's inside `POSIXFunctionsUnitTest.php`:
 
 ```php
-...
 namespace WordPressCS\WordPress\Tests\PHP;
 
 use PHP_CodeSniffer\Tests\Standards\AbstractSniffUnitTest;
 
-class POSIXFunctionsUnitTest extends AbstractSniffUnitTest {
+final class POSIXFunctionsUnitTest extends AbstractSniffUnitTest {
 
 	/**
 	 * Returns the lines where errors should occur.
 	 *
-	 * @return array <int line number> => <int number of errors>
+	 * @return array<int, int> Key is the line number, value is the number of expected errors.
 	 */
 	public function getErrorList() {
 		return array(
@@ -142,17 +127,18 @@ class POSIXFunctionsUnitTest extends AbstractSniffUnitTest {
 			24 => 1,
 			26 => 1,
 		);
-
 	}
-...
+
+    ...
+}
 ```
 
-Also note the class name convention. The method `getErrorList()` MUST return an array of line numbers indicating errors (when running `phpcs`) found in `WordPress/Tests/PHP/POSIXFunctionsUnitTest.inc`.
-If you run:
+Also note the class name convention. The method `getErrorList()` MUST return an array of line numbers indicating errors (when running `phpcs`) found in `WordPress/Tests/PHP/POSIXFunctionsUnitTest.inc`. Similarly, the `getWarningList()` method must return an array of line numbers with the number of expected warnings.
+
+If you run the following from the root directory of your WordPressCS clone:
 
 ```sh
-$ cd /path-to-cloned/phpcs
-$ ./bin/phpcs --standard=Wordpress -s /path/to/WordPress/Tests/PHP/POSIXFunctionsUnitTest.inc --sniffs=WordPress.PHP.POSIXFunctions
+$ "vendor/bin/phpcs" --standard=Wordpress -s ./Tests/PHP/POSIXFunctionsUnitTest.inc --sniffs=WordPress.PHP.POSIXFunctions
 ...
 --------------------------------------------------------------------------------
 FOUND 7 ERRORS AFFECTING 7 LINES
@@ -163,28 +149,28 @@ FOUND 7 ERRORS AFFECTING 7 LINES
  16 | ERROR | eregi() has been deprecated since PHP 5.3 and removed in PHP 7.0,
     |       | please use preg_match() instead.
     |       | (WordPress.PHP.POSIXFunctions.ereg_eregi)
- 18 | ERROR | ereg_replace() has been deprecated since PHP 5.3 and removed in PHP
-    |       | 7.0, please use preg_replace() instead.
+ 18 | ERROR | ereg_replace() has been deprecated since PHP 5.3 and removed in
+    |       | PHP 7.0, please use preg_replace() instead.
     |       | (WordPress.PHP.POSIXFunctions.ereg_replace_ereg_replace)
- 20 | ERROR | eregi_replace() has been deprecated since PHP 5.3 and removed in PHP
-    |       | 7.0, please use preg_replace() instead.
+ 20 | ERROR | eregi_replace() has been deprecated since PHP 5.3 and removed in
+    |       | PHP 7.0, please use preg_replace() instead.
     |       | (WordPress.PHP.POSIXFunctions.ereg_replace_eregi_replace)
  22 | ERROR | split() has been deprecated since PHP 5.3 and removed in PHP 7.0,
     |       | please use explode(), str_split() or preg_split() instead.
     |       | (WordPress.PHP.POSIXFunctions.split_split)
- 24 | ERROR | spliti() has been deprecated since PHP 5.3 and removed in PHP 7.0,
-    |       | please use explode(), str_split() or preg_split() instead.
-    |       | (WordPress.PHP.POSIXFunctions.split_spliti)
- 26 | ERROR | sql_regcase() has been deprecated since PHP 5.3 and removed in PHP
-    |       | 7.0, please use preg_match() instead.
+ 24 | ERROR | spliti() has been deprecated since PHP 5.3 and removed in PHP
+    |       | 7.0, please use explode(), str_split() or preg_split()
+    |       | instead. (WordPress.PHP.POSIXFunctions.split_spliti)
+ 26 | ERROR | sql_regcase() has been deprecated since PHP 5.3 and removed in
+    |       | PHP 7.0, please use preg_match() instead.
     |       | (WordPress.PHP.POSIXFunctions.ereg_sql_regcase)
 --------------------------------------------------------------------------------
-....
+...
 ```
 You'll see the line number and number of ERRORs we need to return in the `getErrorList()` method.
 
 The `--sniffs=...` directive limits the output to the sniff you are testing.
 
 ## Code Standards for this project
 
-The sniffs and test files - not test _case_ files! - for WPCS should be written such that they pass the `WordPress-Extra` and the `WordPress-Docs` code standards using the custom ruleset as found in `/.phpcs.xml.dist`.
+The sniffs and test files - not test _case_ files! - for WordPressCS should be written such that they pass the `WordPress-Extra` and the `WordPress-Docs` code standards using the custom ruleset as found in `/.phpcs.xml.dist`.

.github/ISSUE_TEMPLATE/bug_report.md

@@ -4,6 +4,11 @@ about: Create a report to help us improve
 
 ---
 
+<!--
+PLEASE FILL OUT THE TEMPLATE COMPLETELY.
+BUG REPORTS WHICH CANNOT BE REPRODUCED BASED ON THE INFORMATION PROVIDED WILL BE CLOSED.
+-->
+
 ## Bug Description
 <!--
 Please provide a clear and concise description of what the bug is.
@@ -12,36 +17,76 @@ What did you expect to happen? What actually happened?
 -->
 
 ## Minimal Code Snippet
-<!-- Please provide example code that demonstrates the issue. Do NOT paste screenshots of code! -->
+<!-- Please provide example code that allows us to reproduce the issue. Do NOT paste screenshots of code! -->
 
+The issue happens when running this command:
+```bash
+phpcs ...
+```
+
+... over a file containing this code:
 ```php
 // Place your code sample here.
 ```
 
-For bugs with fixers: How was the code fixed? How did you expect the code to be fixed?
+<!-- For bugs with fixers: How was the code fixed? How did you expect the code to be fixed? -->
+
+The file was auto-fixed via `phpcbf` to:
+```php
+// Place your code sample here.
+```
+
+... while I expected the code to be fixed to:
+```php
+// Place your code sample here.
+```
 
 ## Error Code
 <!--
 The error code for the sniff that is (or should be) being triggered (you
 can see the sniff error codes by running `phpcs` with the `-s` flag).
 e.g. `WordPress.PHP.NoSilencedErrors.Discouraged`
 
+Note: only report issues for error codes starting with `WordPress` to this repo!
+If the error code starts with `Universal`, `NormalizedArrays` or `Modernize` report the issue to PHPCSExtra.
+If the error code starts with `Generic`, `PEAR`, `PSR1`, `PSR2`, `PSR12`, `Squiz` or `Zend` report the issue to PHP_CodeSniffer itself.
+
 You can leave this section empty if you are reporting a false negative.
 -->
 
+## Custom Ruleset
+<!--
+If the issue cannot be reproduced when using `--standard=WordPress` on the command line,
+please post the relevant part of your custom ruleset here.
+-->
+
+```xml
+<?xml version="1.0"?>
+<ruleset name="My Custom Standard">
+  ...
+</ruleset>
+```
+
 ## Environment
+<!--
+To find out the versions used:
+* PHP: run `php -v`.
+* Packages: run `composer info` or run `composer [global] info` to see the installed versions.
+-->
 
-| Question               | Answer
-| ------------------------| -------
-| PHP version             | x.y.z 
-| PHP_CodeSniffer version | x.y.z
-| WPCS version            | x.y.z
-| WPCS install type       | e.g. Composer global, Composer project local, git clone, other (please expand)
-| IDE (if relevant)       | Name and version e.g. PhpStorm 2018.2.2
+| Question                 | Answer
+| ------------------------ | -------
+| PHP version              | x.y.z
+| PHP_CodeSniffer version  | x.y.z
+| WordPressCS version      | x.y.z
+| PHPCSUtils version       | x.y.z
+| PHPCSExtra version       | x.y.z
+| WordPressCS install type | e.g. Composer global, Composer project local, other (please expand)
+| IDE (if relevant)        | Name and version e.g. PhpStorm 2018.2.2
 
 
 ## Additional Context (optional)
 <!-- Add any other context about the problem here. -->
 
-## Tested Against `develop` branch?
-- [ ] I have verified the issue still exists in the `develop` branch of WPCS.
+## Tested Against `develop` Branch?
+- [ ] I have verified the issue still exists in the `develop` branch of WordPressCS.