Skip to content

Latest commit

 

History

History
223 lines (160 loc) · 10.1 KB

CONTRIBUTING.md

File metadata and controls

223 lines (160 loc) · 10.1 KB
Raw

Hi, thank you for your interest in contributing to the WordPress Coding Standards! We look forward to working with you.

Reporting Bugs

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.

Before reporting a bug, you should check what sniff an error is coming from. Running phpcs with the -s flag will show the name of the sniff with each error.

Bug reports containing a minimal code sample which can be used to reproduce the issue are highly appreciated as those are most easily actionable.

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.

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.

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.

Considerations when writing sniffs

Public properties

When writing sniffs, always remember that any public sniff property can be overruled via a custom ruleset by the end-user. 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 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.

There is a tentative intention to drop support for the WPCS native whitelist comments in WPCS 2.0.0.

Considering that, the introduction of new whitelist comments is discouraged.

The below information remains as guidance for exceptional cases and to aid in understanding the previous implementation.

Sometimes, a sniff will flag code which upon further inspection by a human turns out to be OK.

If the sniff you are writing is susceptible to this, please consider adding the ability to whitelist lines of code.

To this end, the WordPress\Sniff::has_whitelist_comment() method was introduced.

Example usage:

namespace WordPress\Sniffs\Security;

use WordPress\Sniff;

class NonceVerificationSniff extends Sniff {

	public function process_token( $stackPtr ) {

		// Check something.
		
		if ( $this->has_whitelist_comment( 'CSRF', $stackPtr ) ) {
			return;
		}
		
		$this->phpcsFile->addError( ... );
	}
}

When you introduce a new whitelist comment, please don't forget to update the whitelisting code wiki page with the relevant details once your PR has been merged into the develop branch.

Unit Testing

Pre-requisites

  • WordPress-Coding-Standards
  • PHP_CodeSniffer 2.9.x or 3.x
  • 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, 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.

If you already have PHPUnit installed on your system: Congrats, you're all set.

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. Alternatively, you can install PHPUnit as a PHAR file.

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. Make sure to adjust the path to reflect your local setup.

<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/6.3/phpunit.xsd"
	beStrictAboutTestsThatDoNotTestAnything="false"
	backupGlobals="true">
	<php>
		<env name="PHPCS_DIR" value="/path/to/PHP_CodeSniffer/"/>
	</php>
</phpunit>

Running the unit tests

The WordPress Coding Standards are compatible with both PHPCS 2.x as well as 3.x. This has some implications for running the unit tests.

  • Make sure you have registered the directory in which you installed WPCS with PHPCS using; 
    phpcs --config-set installed_paths path/to/WPCS
  • Navigate to the directory in which you installed WPCS.
  • To run the unit tests with PHPCS 3.x: 
    phpunit --bootstrap="./Test/phpcs3-bootstrap.php" --filter WordPress /path/to/PHP_CodeSniffer/tests/AllTests.php
  • To run the unit tests with PHPCS 2.x: 
    phpunit --bootstrap="./Test/phpcs2-bootstrap.php" --filter WordPress ./Test/AllTests.php

Expected output:

PHPUnit 6.5.8 by Sebastian Bergmann and contributors.

Runtime:       PHP 7.2.7 with Xdebug 2.6.0
Configuration: /WordPressCS/phpunit.xml

................................................................. 65 / 77 ( 84%)
............                                                      77 / 77 (100%)

Tests generated 576 unique error codes; 51 were fixable (8.85%)

Time: 22.93 seconds, Memory: 40.00MB

OK (77 tests, 0 assertions)

asciicast

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:

...
namespace WordPress\Tests\PHP;

use PHP_CodeSniffer\Tests\Standards\AbstractSniffUnitTest;

class POSIXFunctionsUnitTest extends AbstractSniffUnitTest {

	/**
	 * Returns the lines where errors should occur.
	 *
	 * @return array <int line number> => <int number of errors>
	 */
	public function getErrorList() {
		return array(
			13 => 1,
			16 => 1,
			18 => 1,
			20 => 1,
			22 => 1,
			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:

$ cd /path-to-cloned/phpcs
$ ./bin/phpcs --standard=Wordpress -s /path/to/WordPress/Tests/PHP/POSIXFunctionsUnitTest.inc --sniffs=WordPress.PHP.POSIXFunctions
...
--------------------------------------------------------------------------------
FOUND 7 ERRORS AFFECTING 7 LINES
--------------------------------------------------------------------------------
 13 | ERROR | ereg() has been deprecated since PHP 5.3 and removed in PHP 7.0,
    |       | please use preg_match() instead.
    |       | (WordPress.PHP.POSIXFunctions.ereg_ereg)
 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.
    |       | (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.
    |       | (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.
    |       | (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.