Skip to content

Commit

Permalink
Contributing: improve the text
Browse files Browse the repository at this point in the history
As GH was so kind as to point me to the "contributing guidelines which have been changed since you last contributed" I quickly scanned through the file and most notably, came across a link to the WPCS wiki page, while this link should have gone to the VIPCS wiki.

As I was editing the file now anyway, I've made some other changes along the way.

* Ask people to search the issue list before opening an issue.
* Made a little table to make it easier for people to report upstream issues to the correct repository.
* Updated the "custom properties" link to point to the VIPCS wiki.
* Updated the PHPUnit installation link.
* Updated the `phpunit.xml` example to be in line with the current `phpunit.xml.dist` file.
* Updated the expected unit test output.
  • Loading branch information
jrfnl committed Jul 21, 2020
1 parent a44e76b commit 57e4780
Showing 1 changed file with 28 additions and 12 deletions.
40 changes: 28 additions & 12 deletions .github/CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,11 +7,25 @@ Hi, thank you for your interest in contributing to the VIP Coding Standards! We
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.

Please search the repository before opening an issue to verify that the issue hasn't been reported already.

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 VIPCS employs many sniffs that are part of PHPCS, and makes use of WordPress Coding Standards sniffs, sometimes an issue will be caused by a bug upstream and not in VIPCS itself. If the error message in question doesn't come from a sniff whose name starts with `WordPressVIPMinimum`, the issue is probably a bug in PHPCS itself, and should be [reported there](https://github.com/squizlabs/PHP_CodeSniffer/issues).
Since VIPCS employs many sniffs that are part of PHPCS, and makes use of WordPress Coding Standards sniffs, sometimes an issue will be caused by a bug upstream and not in VIPCS itself. If the error message in question doesn't come from a sniff whose name starts with `WordPressVIPMinimum`, the issue is probably an upstream bug.

To determine where best to report the bug, use the first part of the sniff name:

Sniffname starts with | Report to
--- | ---
`Generic` | [PHP_CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer/issues/)
`PSR2` | [PHP_CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer/issues/)
`Squiz` | [PHP_CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer/issues/)
`VariableAnalysis` | [VariableAnalysis](https://github.com/sirbrillig/phpcs-variable-analysis/issues/)
`WordPress` | [WordPressCS](https://github.com/WordPress/WordPress-Coding-Standards/issues/)
`WordPressVIPMinimum` | [VIPCS](https://github.com/Automattic/VIP-Coding-Standards/issues/) (this repo)
`Generic`, `PSR2` or `Squiz` | [PHP_CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer/issues/)

----

Expand Down Expand Up @@ -42,7 +56,7 @@ The sniffs and test files - not test _case_ files! - for VIPCS should be written
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](https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/wiki/Customizable-sniff-properties) with the relevant details once your PR has been merged into the `develop` branch.
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/Automattic/VIP-Coding-Standards/wiki/Custom-properties-for-VIPCS-Sniffs) with the relevant details once your PR has been merged into the `develop` branch.

## Unit Testing

Expand All @@ -61,7 +75,7 @@ N.B.: If you installed VIPCS using Composer, make sure you used `--prefer-source
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](https://phpunit.de/manual/5.7/en/installation.html) as a PHAR file.
Alternatively, you can [install PHPUnit](https://phpunit.readthedocs.io/en/7.5/installation.html) as a PHAR file.

### Before running the unit tests

Expand All @@ -71,11 +85,13 @@ For the unit tests to work, you need to make sure PHPUnit can find your `PHP_Cod

The easiest way to do this is to add a `phpunit.xml` file to the root of your VIPCS installation and set a `PHPCS_DIR` environment variable from within this file. Make sure to adjust the path to reflect your local setup.
```xml
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/6.3/phpunit.xsd"
beStrictAboutTestsThatDoNotTestAnything="false"
bootstrap="./tests/bootstrap.php"
<?xml version="1.0" encoding="UTF-8"?>
<phpunit
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/7.2/phpunit.xsd"
backupGlobals="true"
bootstrap="./tests/bootstrap.php"
beStrictAboutTestsThatDoNotTestAnything="false"
colors="true">
<php>
<env name="PHPCS_DIR" value="/path/to/PHP_CodeSniffer/"/>
Expand All @@ -86,7 +102,7 @@ The easiest way to do this is to add a `phpunit.xml` file to the root of your VI
### Running the unit tests

* Make sure you have registered the directory in which you installed VIPCS with PHPCS using;

```sh
phpcs --config-set installed_paths path/to/VIPCS
```
Expand All @@ -99,13 +115,13 @@ The easiest way to do this is to add a `phpunit.xml` file to the root of your VI

Expected output:
```
PHPUnit 7.5.12 by Sebastian Bergmann and contributors.
PHPUnit 7.5.20 by Sebastian Bergmann and contributors.

........................................... 43 / 43 (100%)
.......................................... 42 / 42 (100%)

44 sniff test files generated 119 unique error codes; 0 were fixable (0%)
43 sniff test files generated 117 unique error codes; 0 were fixable (0%)

Time: 380 ms, Memory: 30.00MB
Time: 246 ms, Memory: 32.00 MB
```
### Unit Testing conventions
Expand Down

0 comments on commit 57e4780

Please sign in to comment.