Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Contributing: improve the text #501

Merged
merged 2 commits into from
Jul 21, 2020
Merged

Contributing: improve the text #501

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a44e76b
Contributing: move file to `.github` directory
jrfnl Jul 21, 2020
57e4780
Contributing: improve the text
jrfnl Jul 21, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 28 additions & 12 deletions CONTRIBUTING.md → .github/CONTRIBUTING.md
View file
Open in desktop
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
2 changes: 1 addition & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down