Skip to content

Commit

Permalink
Merge pull request #2369 from WordPress/develop
Browse files Browse the repository at this point in the history 
Release WordPressCS 3.0.0
  • Loading branch information
@jrfnl
jrfnl committed Aug 21, 2023
2 parents 7da1894 + e36e0ea commit bb792cb
Show file tree
Hide file tree
Showing 394 changed files with 19,928 additions and 13,325 deletions.
21 changes: 21 additions & 0 deletions .codecov.yml
View file
@@ -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
20 changes: 12 additions & 8 deletions .gitattributes
View file
@@ -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

Expand Down
150 changes: 68 additions & 82 deletions .github/CONTRIBUTING.md
View file
Expand Up @@ -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

Expand All @@ -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(
Expand All @@ -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
Expand All @@ -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`.
67 changes: 56 additions & 11 deletions .github/ISSUE_TEMPLATE/bug_report.md
View file
Expand Up @@ -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.
Expand All @@ -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.

0 comments on commit bb792cb

Please sign in to comment.