Merge branch 'release/1.0.0'

CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0] - Unreleased
+### Added
+- Added `PHPCompatibilityWP` rule.
+- Added `VariableAnalysis` rule.
+- Added `WordPress` rule.
+- Added `WordPressVIPMinimum` rule.
+- Added `WordPress-VIP-Go` rule.
+- Excluded `WordPress.Files.FileName.InvalidClassFileName` sniff.
+- Excluded `WordPress.Files.FileName.NotHyphenatedLowercase` sniff.
+- Added relative exclude pattern `^bower_components/*` for the `bower_components` folder.
+- Added relative exclude pattern `^node_modules/*` for the `node_modules` folder.
+- Added relative exclude pattern `^vendor/*` for the `vendor` folder.
+- Added relative exclude pattern `^vendor-bin/*` for the `vendor-bin` folder.
+- Added relative exclude pattern `^wordpress/*` for the `wordpress` folder.
+- Added relative exclude pattern `^wp-content/*` for the `wp-content` folder.
+
+[Unreleased]: https://github.com/pronamic/wp-coding-standards/compare/1.0.0...HEAD
+[1.0.0]: https://github.com/pronamic/wp-coding-standards/releases/tag/1.0.0

PronamicWP/ruleset.xml

@@ -7,31 +7,69 @@
 >
 	<description>Pronamic WordPress WordPress Coding Standards</description>
 
-	<config name="minimum_supported_wp_version" value="4.7" />
-
-	<config name="testVersion" value="5.6-" />
-
+	<!-- Use colors in output. -->
 	<arg name="colors"/>
+
+	<!-- A comma separated list of file extensions to check. -->
 	<arg name="extensions" value="php" />
+
+	<!-- @link https://github.com/squizlabs/PHP_CodeSniffer/issues/1732 -->
 	<arg name="parallel" value="8" />
+
+	<!-- Show show sniff codes and progress. -->
 	<arg value="sp" />
 
+	<!-- Minimum WordPress version to check. -->
+	<!-- @link https://github.com/WordPress/WordPress-Coding-Standards/wiki/Customizable-sniff-properties#minimum-wp-version-to-check-for-usage-of-deprecated-functions-classes-and-function-parameters -->
+	<config name="minimum_supported_wp_version" value="4.7" />
+
+	<!-- PHP compatibility test version 5.6 and higher. -->
+	<config name="testVersion" value="5.6-" />
+
 	<!-- Exclude files relative to the root of the project -->
 	<!-- @link https://github.com/squizlabs/PHP_CodeSniffer/issues/981 -->
+
+	<!-- Exclude the `bower` `bower_components` folder. -->
+	<!-- @link https://bower.io/ -->
+	<exclude-pattern type="relative">^bower_components/*</exclude-pattern>
+
+	<!-- Exclude the `npm` `node_modules` folder. -->
+	<!-- @link https://docs.npmjs.com/cli/v7/configuring-npm/folders -->
 	<exclude-pattern type="relative">^node_modules/*</exclude-pattern>
+
+	<!-- Exclude the `composer` `vendor` folder. -->
+	<!-- @link https://getcomposer.org/doc/06-config.md#vendor-dir -->
 	<exclude-pattern type="relative">^vendor/*</exclude-pattern>
+
+	<!-- Exclude the "Composer bin plugin" `vendor-bin` folder. -->
+	<!-- @link https://github.com/bamarni/composer-bin-plugin -->
 	<exclude-pattern type="relative">^vendor-bin/*</exclude-pattern>
+
+	<!-- Exclude the WordPress `wordpress` folder. -->
+	<!-- @link https://roots.io/announcing-the-roots-wordpress-composer-package/ -->
 	<exclude-pattern type="relative">^wordpress/*</exclude-pattern>
+
+	<!-- Exclude the WordPress Packagist `wp-content` folder. -->
+	<!-- @link https://wpackagist.org/ -->
 	<exclude-pattern type="relative">^wp-content/*</exclude-pattern>
 
+	<!-- @link https://github.com/pronamic/wp-coding-standards/tree/develop#phpcompatibilitywp -->
 	<rule ref="PHPCompatibilityWP" />
+
+	<!-- @link https://github.com/pronamic/wp-coding-standards/tree/develop#variableanalysis -->
 	<rule ref="VariableAnalysis" />
 
 	<rule ref="WordPress">
+		<!-- @link https://github.com/pronamic/wp-coding-standards/tree/main#wordpressfilesfilenameinvalidclassfilename -->
 		<exclude name="WordPress.Files.FileName.InvalidClassFileName" />
+
+		<!-- @link https://github.com/pronamic/wp-coding-standards/tree/main#wordpressfilesfilenamenothyphenatedlowercase -->
 		<exclude name="WordPress.Files.FileName.NotHyphenatedLowercase" />
 	</rule>
 
+	<!-- @link https://github.com/pronamic/wp-coding-standards/tree/main#wordpressvipminimum -->
 	<rule ref="WordPressVIPMinimum" />
+
+	<!-- @link https://github.com/pronamic/wp-coding-standards/tree/develop#wordpress-vip-go -->
 	<rule ref="WordPress-VIP-Go" />
 </ruleset>

README.md

@@ -1,3 +1,128 @@
 # Pronamic WordPress WordPress Coding Standards
 
 Pronamic WordPress WordPress Coding Standards for PHP_CodeSniffer.
+
+## PHP_CodeSniffer
+
+https://github.com/squizlabs/PHP_CodeSniffer
+
+### Arguments
+
+https://github.com/squizlabs/PHP_CodeSniffer/wiki/Usage
+
+#### `colors`
+
+By default use colors in output.
+
+```xml
+<arg name="colors"/>
+```
+
+#### `extensions`
+
+By default only check files with `php` extension:
+
+```xml
+<arg name="extensions" value="php" />
+```
+
+#### `parallel`
+
+By default use `8` parallel processes.
+
+```xml
+<arg name="parallel" value="8" />
+```
+
+https://github.com/squizlabs/PHP_CodeSniffer/issues/1732
+
+#### `sp`
+
+By default show sniff codes in all reports.
+By default show progress of the run.
+
+```xml
+<arg value="sp" />
+```
+
+## Rules
+
+### PHPCompatibilityWP
+
+https://github.com/PHPCompatibility/PHPCompatibilityWP
+
+By default this package test PHP 5.6 and higher via the following setting:
+
+```xml
+<config name="testVersion" value="5.6-"/>
+```
+
+### PHPCompatibility
+
+https://github.com/PHPCompatibility/PHPCompatibility
+
+Required through `PHPCompatibilityWP`.
+
+### WordPress
+
+https://github.com/WordPress/WordPress-Coding-Standards
+
+By default the minimum WordPress version to check is set to `4.7` via the following setting:
+
+```xml
+<config name="minimum_supported_wp_version" value="4.7" />
+```
+
+https://github.com/WordPress/WordPress-Coding-Standards/wiki/Customizable-sniff-properties#minimum-wp-version-to-check-for-usage-of-deprecated-functions-classes-and-function-parameters
+
+### WordPressVIPMinimum
+
+https://github.com/Automattic/VIP-Coding-Standards
+
+### WordPress-VIP-Go
+
+https://github.com/Automattic/VIP-Coding-Standards
+
+### VariableAnalysis
+
+https://github.com/sirbrillig/phpcs-variable-analysis
+
+## Exclusions
+
+### `WordPress.Files.FileName.InvalidClassFileName`
+
+According to the WordPress PHP Coding Standards:
+
+> Class file names should be based on the class name with `class-` prepended and the underscores in the class name replaced with hyphens, for example `WP_Error` becomes:
+>
+> ```
+> class-wp-error.php
+> ```
+
+_Source:_ https://make.wordpress.org/core/handbook/best-practices/coding-standards/php/#naming-conventions
+
+This sniff will check on this naming convention:
+
+```
+Class file names should be based on the class name with "class-" prepended. Expected class-test.php, but found Test.php.
+```
+
+We often use the [PSR-4](https://www.php-fig.org/psr/psr-4/) autoloading mechanism and therefore deviate from it.
+
+### `WordPress.Files.FileName.NotHyphenatedLowercase`
+
+According to the WordPress PHP Coding Standards:
+
+> Files should be named descriptively using lowercase letters. Hyphens should separate words.
+>
+> ```
+> my-plugin-name.php
+> ```
+
+_Source:_ https://make.wordpress.org/core/handbook/best-practices/coding-standards/php/#naming-conventions
+
+```
+Filenames should be all lowercase with hyphens as word separators. Expected test.php, but found Test.php.
+```
+
+We often use the [PSR-4](https://www.php-fig.org/psr/psr-4/) autoloading mechanism and therefore deviate from it.