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
Hi, thank you for your interest in contributing to the WordPress Coding Standards! We look forward to working with you.
2
4
3
-
# Reporting Bugs
5
+
##Reporting Bugs
4
6
5
7
Please search the repo to see if your issue has been reported already and if so, comment in that issue instead of opening a new one.
6
8
@@ -9,48 +11,69 @@ Running `phpcs` with the `-s` flag will show the name of the sniff with each err
9
11
10
12
Bug reports containing a minimal code sample which can be used to reproduce the issue are highly appreciated as those are most easily actionable.
11
13
12
-
## Upstream Issues
14
+
###Upstream Issues
13
15
14
16
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
17
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
18
17
19
* Bugs for sniffs starting with `Generic`, `PEAR`, `PSR1`, `PSR2`, `PSR12`, `Squiz` or `Zend` should be [reported to PHPCS](https://github.com/PHPCSStandards/PHP_CodeSniffer/issues).
18
20
* Bugs for sniffs starting with `Modernize`, `NormalizedArrays` or `Universal` should be [reported to PHPCSExtra](https://github.com/PHPCSStandards/PHPCSExtra/issues).
19
21
20
-
# Contributing patches and new features
22
+
## Contributing patches and new features
23
+
24
+
### Tips for Successful PRs
25
+
26
+
We welcome contributions from everyone, and want your PR to have the best chance of being reviewed and merged. To help with this, please keep the following in mind:
27
+
28
+
***Respect copyright and licensing.**
29
+
Only submit code that you have written yourself or that comes from sources where the license clearly allows inclusion. Submitting code that infringes on copyright or licensing terms puts both you and the project at legal risk, and such contributions cannot be accepted.
30
+
31
+
***Do not submit AI-generated code.**
32
+
Pull requests containing AI-generated code are not acceptable. Beyond copyright and licensing uncertainties, AI-generated contributions consistently require disproportionate amounts of maintainer time to review, correct, or rewrite. This wastes limited project resources and slows progress for everyone. Submitting AI-generated code may be treated as a violation of our [Code of Conduct](../CODE_OF_CONDUCT.md).
21
33
22
-
## Branches
34
+
***Focus on quality and clarity.**
35
+
Take time to explain *why* the change is needed, and include tests or examples where appropriate. Clear, self-written explanations make it more straightforward for reviewers to understand what you are trying to achieve.
36
+
37
+
***Think about long-term maintainability.**
38
+
Code should align with WordPress Coding Standards and be written in a way that others can readily read, understand, and maintain.
39
+
40
+
***Be collaborative.**
41
+
If you're unsure about an approach, open an issue first to start a conversation.
42
+
43
+
By following these tips, you'll save time for both yourself and the maintainers — and increase the likelihood that your contribution can be merged smoothly.
44
+
45
+
### Branches
23
46
24
47
Ongoing development will be done in the `develop` branch with merges to `main` once considered stable.
25
48
26
49
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
50
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`.
28
51
29
-
# Considerations when writing sniffs
52
+
##Considerations when writing sniffs
30
53
31
-
## Public properties
54
+
###Public properties
32
55
33
56
When writing sniffs, always remember that any `public` sniff property can be overruled via a custom ruleset by the end-user.
34
57
Only make a property `public` if that is the intended behavior.
35
58
36
59
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.
37
60
38
-
# Unit Testing
61
+
##Unit Testing
39
62
40
-
## Pre-requisites
63
+
###Pre-requisites
41
64
* WordPress-Coding-Standards
42
-
* PHP_CodeSniffer 3.13.0 or higher
65
+
* PHP_CodeSniffer 3.13.4 or higher
43
66
* PHPCSUtils 1.1.0 or higher
44
-
* PHPCSExtra 1.4.0 or higher
45
-
* PHPUnit 4.x - 9.x
67
+
* PHPCSExtra 1.5.0 or higher
68
+
* PHPUnit 8.x - 9.x
46
69
47
70
The WordPress Coding Standards use the `PHP_CodeSniffer` native unit test framework for unit testing the sniffs.
48
71
49
-
## Getting ready to test
72
+
###Getting ready to test
50
73
51
74
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.
52
75
53
-
## Custom develop setups
76
+
###Custom develop setups
54
77
55
78
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:
201 sniff test files generated 744 unique error codes; 50 were fixable (6%)
118
+
210 sniff test files generated 775 unique error codes; 50 were fixable (6%)
96
119
97
-
Time: 10.19 seconds, Memory: 40.00 MB
120
+
Time: 00:03.396, Memory: 60.00 MB
98
121
99
-
OK (57 tests, 0 assertions)
122
+
OK (60 tests, 6 assertions)
100
123
```
101
124
102
-
## Unit Testing conventions
125
+
### Unit Testing conventions
103
126
104
-
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?
127
+
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/TypeCastsSniff.php` sniff has its unit test class defined in`WordPress/Tests/PHP/TypeCastsUnitTest.php` which checks the `WordPress/Tests/PHP/TypeCastsUnitTest.inc`testcase file. See the file naming convention?
105
128
106
-
Lets take a look at what's inside `POSIXFunctionsUnitTest.php`:
129
+
Lets take a look at what's inside `TypeCastsUnitTest.php`:
107
130
108
131
```php
109
132
namespace WordPressCS\WordPress\Tests\PHP;
110
133
111
134
use PHP_CodeSniffer\Tests\Standards\AbstractSniffUnitTest;
112
135
113
-
final class POSIXFunctionsUnitTest extends AbstractSniffUnitTest {
136
+
final class TypeCastsUnitTest extends AbstractSniffUnitTest {
114
137
115
138
/**
116
139
* Returns the lines where errors should occur.
@@ -119,58 +142,59 @@ final class POSIXFunctionsUnitTest extends AbstractSniffUnitTest {
119
142
*/
120
143
public function getErrorList() {
121
144
return array(
145
+
10 => 1,
146
+
11 => 1,
122
147
13 => 1,
123
-
16 => 1,
124
-
18 => 1,
125
-
20 => 1,
126
-
22 => 1,
127
-
24 => 1,
128
148
26 => 1,
149
+
27 => 1,
150
+
28 => 1,
129
151
);
130
152
}
131
153
132
154
...
133
155
}
134
156
```
135
157
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.
158
+
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/TypeCastsUnitTest.inc`. Similarly, the `getWarningList()` method must return an array of line numbers with the number of expected warnings.
137
159
138
160
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.
171
195
172
196
The `--sniffs=...` directive limits the output to the sniff you are testing.
173
197
174
-
## Code Standards for this project
198
+
### Code Standards for this project
175
199
176
200
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