You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: .github/CONTRIBUTING.md
+29-62
Original file line number
Diff line number
Diff line change
@@ -37,111 +37,78 @@ When you introduce new `public` sniff properties, or your sniff extends a class
37
37
> **Important**:
38
38
> PHPCS 3.2.0 introduced new selective ignore annotations, which can be considered an improved version of the whitelist mechanism which WPCS contains.
39
39
>
40
-
> There is a [tentative intention to drop support for the WPCS native whitelist comments](https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/issues/1048#issuecomment-340698249) in WPCS 2.0.0.
41
-
>
42
-
> Considering that, the introduction of new whitelist comments is discouraged.
40
+
> Support for the WPCS native whitelist comments has been deprecated in WPCS 2.0.0 and will be removed in WPCS 3.0.0.
43
41
>
44
-
> The below information remains as guidance for exceptional cases and to aid in understanding the previous implementation.
45
-
46
-
Sometimes, a sniff will flag code which upon further inspection by a human turns out to be OK.
47
-
48
-
If the sniff you are writing is susceptible to this, please consider adding the ability to [whitelist lines of code](https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/wiki/Whitelisting-code-which-flags-errors).
49
-
50
-
To this end, the `WordPress\Sniff::has_whitelist_comment()` method was introduced.
51
-
52
-
Example usage:
53
-
```php
54
-
namespace WordPress\Sniffs\Security;
55
-
56
-
use WordPress\Sniff;
57
-
58
-
class NonceVerificationSniff extends Sniff {
59
-
60
-
public function process_token( $stackPtr ) {
61
-
62
-
// Check something.
63
-
64
-
if ( $this->has_whitelist_comment( 'CSRF', $stackPtr ) ) {
65
-
return;
66
-
}
67
-
68
-
$this->phpcsFile->addError( ... );
69
-
}
70
-
}
71
-
```
72
-
73
-
When you introduce a new whitelist comment, please don't forget to update the [whitelisting code wiki page](https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/wiki/Whitelisting-code-which-flags-errors) with the relevant details once your PR has been merged into the `develop` branch.
42
+
> With that in mind, (new) sniffs should not introduce new WPCS native whitelist comments.
74
43
75
44
76
45
# Unit Testing
77
46
78
47
## Pre-requisites
79
48
* WordPress-Coding-Standards
80
-
* PHP_CodeSniffer 2.9.x or 3.x
49
+
* PHP_CodeSniffer 3.3.1 or higher
81
50
* PHPUnit 4.x, 5.x, 6.x or 7.x
82
51
83
-
The WordPress Coding Standards use the PHP_CodeSniffer native unit test suite for unit testing the sniffs.
52
+
The WordPress Coding Standards use the `PHP_CodeSniffer` native unit test suite for unit testing the sniffs.
84
53
85
-
Presuming you have installed PHP_CodeSniffer and the WordPress-Coding-Standards as [noted in the README](https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards#how-to-use-this), all you need now is `PHPUnit`.
54
+
Presuming you have installed `PHP_CodeSniffer` and the WordPress-Coding-Standards as [noted in the README](https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards#how-to-use-this), all you need now is `PHPUnit`.
86
55
87
-
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.
56
+
> 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.
57
+
> Other than that, you're all set already as Composer will have installed PHPUnit for you.
88
58
89
59
If you already have PHPUnit installed on your system: Congrats, you're all set.
90
60
91
-
If not, you can navigate to the directory where the `PHP_CodeSniffer` repo is checked out and do `composer install` to install the `dev` dependencies.
92
-
Alternatively, you can [install PHPUnit](https://phpunit.de/manual/5.7/en/installation.html) as a PHAR file.
61
+
## Installing PHPUnit
62
+
63
+
N.B.: _If you used Composer to install the WordPress Coding Standards, you can skip this step._
64
+
65
+
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.
66
+
67
+
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.
93
68
94
69
## Before running the unit tests
95
70
96
71
N.B.: _If you used Composer to install the WordPress Coding Standards, you can skip this step._
97
72
98
73
For the unit tests to work, you need to make sure PHPUnit can find your `PHP_CodeSniffer` install.
99
74
100
-
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. Make sure to adjust the path to reflect your local setup.
75
+
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.
76
+
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.
0 commit comments