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
+68-82Lines changed: 68 additions & 82 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -11,17 +11,20 @@ Bug reports containing a minimal code sample which can be used to reproduce the
11
11
12
12
## Upstream Issues
13
13
14
-
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).
14
+
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.
15
+
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.
16
+
17
+
* 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).
18
+
* Bugs for sniffs starting with `Modernize`, `NormalizedArrays` or `Universal` should be [reported to PHPCSExtra](https://github.com/PHPCSStandards/PHPCSExtra/issues).
15
19
16
20
# Contributing patches and new features
17
21
18
22
## Branches
19
23
20
-
Ongoing development will be done in the `develop` branch with merges done into `master` once considered stable.
21
-
22
-
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`.
24
+
Ongoing development will be done in the `develop` branch with merges to `main` once considered stable.
23
25
24
-
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.
26
+
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.
27
+
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`.
25
28
26
29
# Considerations when writing sniffs
27
30
@@ -32,105 +35,87 @@ Only make a property `public` if that is the intended behaviour.
32
35
33
36
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.
34
37
35
-
## Whitelist comments
36
-
37
-
> **Important**:
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
-
>
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.
41
-
>
42
-
> With that in mind, (new) sniffs should not introduce new WPCS native whitelist comments.
43
-
44
-
45
38
# Unit Testing
46
39
47
40
## Pre-requisites
48
41
* WordPress-Coding-Standards
49
-
* PHP_CodeSniffer 3.3.1 or higher
42
+
* PHP_CodeSniffer 3.7.2 or higher
43
+
* PHPCSUtils 1.0.8 or higher
44
+
* PHPCSExtra 1.1.0 or higher
50
45
* PHPUnit 4.x, 5.x, 6.x or 7.x
51
46
52
-
The WordPress Coding Standards use the `PHP_CodeSniffer` native unit test suite for unit testing the sniffs.
53
-
54
-
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`.
55
-
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.
47
+
The WordPress Coding Standards use the `PHP_CodeSniffer` native unit test framework for unit testing the sniffs.
58
48
59
-
If you already have PHPUnit installed on your system: Congrats, you're all set.
49
+
## Getting ready to test
60
50
61
-
## Installing PHPUnit
51
+
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.
62
52
63
-
N.B.: _If you used Composer to install the WordPress Coding Standards, you can skip this step._
53
+
## Custom develop setups
64
54
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.
68
-
69
-
## Before running the unit tests
70
-
71
-
N.B.: _If you used Composer to install the WordPress Coding Standards, you can skip this step._
72
-
73
-
For the unit tests to work, you need to make sure PHPUnit can find your `PHP_CodeSniffer` install.
74
-
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.
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:
If you are using a git clone of PHPCS, you may want to `git clone` PHPCSUtils as well.
58
+
2. Register PHPCSUtils with your stand-alone PHP_CodeSniffer installation by running the following commands:
59
+
```bash
60
+
phpcs --config-show
61
+
```
62
+
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).
3. Make sure PHPUnit can find your `PHP_CodeSniffer` install.
68
+
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.
69
+
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.
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`testcase file. See the file naming convention?
119
105
120
106
Lets take a look at what's inside `POSIXFunctionsUnitTest.php`:
121
107
122
108
```php
123
-
...
124
109
namespace WordPressCS\WordPress\Tests\PHP;
125
110
126
111
use PHP_CodeSniffer\Tests\Standards\AbstractSniffUnitTest;
127
112
128
-
class POSIXFunctionsUnitTest extends AbstractSniffUnitTest {
113
+
final class POSIXFunctionsUnitTest extends AbstractSniffUnitTest {
129
114
130
115
/**
131
116
* Returns the lines where errors should occur.
132
117
*
133
-
* @return array<intline number> => <int number of errors>
118
+
* @return array<int, int> Key is the line number, value is the number of expected errors.
134
119
*/
135
120
public function getErrorList() {
136
121
return array(
@@ -142,17 +127,18 @@ class POSIXFunctionsUnitTest extends AbstractSniffUnitTest {
142
127
24 => 1,
143
128
26 => 1,
144
129
);
145
-
146
130
}
147
-
...
131
+
132
+
...
133
+
}
148
134
```
149
135
150
-
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`.
151
-
If you run:
136
+
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.
137
+
138
+
If you run the following from the root directory of your WordPressCS clone:
You'll see the line number and number of ERRORs we need to returnin the `getErrorList()` method.
185
171
186
172
The `--sniffs=...` directive limits the output to the sniff you are testing.
187
173
188
174
## Code Standards for this project
189
175
190
-
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`.
176
+
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`.
0 commit comments