From a44e76b8e2687b48f732322d8b4bcc9a8e882c63 Mon Sep 17 00:00:00 2001 From: jrfnl Date: Tue, 21 Jul 2020 21:07:33 +0200 Subject: [PATCH 1/2] Contributing: move file to `.github` directory --- CONTRIBUTING.md => .github/CONTRIBUTING.md | 0 README.md | 2 +- 2 files changed, 1 insertion(+), 1 deletion(-) rename CONTRIBUTING.md => .github/CONTRIBUTING.md (100%) diff --git a/CONTRIBUTING.md b/.github/CONTRIBUTING.md similarity index 100% rename from CONTRIBUTING.md rename to .github/CONTRIBUTING.md diff --git a/README.md b/README.md index ee2d7938..01001cd0 100644 --- a/README.md +++ b/README.md @@ -36,7 +36,7 @@ Alternatively, you should register the standard to PHPCS by appending the VIPCS ## Contribution -Please see [CONTRIBUTION.md](CONTRIBUTING.md). +Please see [CONTRIBUTION.md](.github/CONTRIBUTING.md). ## License From 57e4780a10882babb50ca68e0326904166f0cb4a Mon Sep 17 00:00:00 2001 From: jrfnl Date: Tue, 21 Jul 2020 21:31:22 +0200 Subject: [PATCH 2/2] Contributing: improve the text 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. --- .github/CONTRIBUTING.md | 40 ++++++++++++++++++++++++++++------------ 1 file changed, 28 insertions(+), 12 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 3a3200f1..6d3bff7b 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -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/) ---- @@ -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 @@ -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 @@ -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 - + @@ -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 ``` @@ -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