mirror of
https://github.com/WordPress/WordPress-Coding-Standards.git
synced 2025-08-30 03:11:24 +08:00
CONTRIBUTING: updates for WordPressCS 3.0.0
This commit updates the CONTRIBUTING guide to be in line with WordPressCS 3.0.0. This commit: * Updates the information about usage of upstream sniffs and reporting upstream issues. * Updates the information on creating a pull request. * Removes the information about the use of a long running release PR (as we don't do this anymore in practice). * Updates the information on running the unit tests, including the information on how to get set up with cloned dependencies. * Updates the examples test run output and removes the outdated the asciinema image. * Updates the code fragments and example output used in the tutorial part to be in line with the current code and run instructions. * Ensures the text consistently uses `WordPressCS` instead of `WPCS`. * Replaced some ablist language.
This commit is contained in:
jrfnl
parent
d847317559
commit
4a33d46882
1 changed files with 66 additions and 70 deletions
136
.github/CONTRIBUTING.md
vendored
136
.github/CONTRIBUTING.md
vendored
|
|
@ -11,7 +11,11 @@ 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
|
||||
|
||||
|
|
@ -19,9 +23,8 @@ Since WPCS employs many sniffs that are part of PHPCS, sometimes an issue will b
|
|||
|
||||
Ongoing development will be done in the `develop` branch with merges to `main` 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`.
|
||||
|
||||
Once a commit is made to `develop`, a PR should be opened from `develop` to `main` 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
|
||||
|
||||
|
|
@ -37,72 +40,65 @@ When you introduce new `public` sniff properties, or your sniff extends a class
|
|||
## Pre-requisites
|
||||
* WordPress-Coding-Standards
|
||||
* 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.
|
||||
The WordPress Coding Standards use the `PHP_CodeSniffer` native unit test framework 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`.
|
||||
## Getting ready to test
|
||||
|
||||
> 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.
|
||||
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.
|
||||
|
||||
If you already have PHPUnit installed on your system: Congrats, you're all set.
|
||||
## Custom develop setups
|
||||
|
||||
## Installing PHPUnit
|
||||
|
||||
N.B.: _If you used Composer to install the WordPress Coding Standards, you can skip this step._
|
||||
|
||||
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)
|
||||
```
|
||||
|
||||
[](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?
|
||||
|
|
@ -110,17 +106,16 @@ If you look inside the `WordPress/Tests` subdirectory, you'll see the structure
|
|||
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(
|
||||
|
|
@ -132,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
|
||||
|
|
@ -153,23 +149,23 @@ 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.
|
||||
|
||||
|
|
@ -177,4 +173,4 @@ 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`.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue
