Merge branch 'release/1.3.0'

.github/PULL_REQUEST_TEMPLATE/dependency_change.md

@@ -0,0 +1,19 @@
+---
+name: Dependency change
+about: Update one or more of the YoastCS dependencies
+labels: "yoast cs/qa"
+---
+
+## Description
+
+*
+
+Refs:
+<!-- Add relevant links to, for instance, the changelog of the updated dependency. -->
+*
+
+<!--
+If the dependency update involves PHP_CodeSniffer or the WordPress Coding Standards,
+please make sure that the `.travis.yml` script is also updated to reflect this change,
+so the unit tests are run against the relevant supported versions of these repos.
+-->

.github/PULL_REQUEST_TEMPLATE/generic.md

@@ -0,0 +1,6 @@
+---
+name: General
+about: Change which doesn't fit any of the other categories
+labels: "yoast cs/qa"
+---
+

.github/PULL_REQUEST_TEMPLATE/sniff_change.md

@@ -0,0 +1,41 @@
+---
+name: Sniff change
+about: Introduce a new sniff or update an existing sniff
+labels: "yoast cs/qa"
+---
+
+## Description
+
+*
+
+
+Refs:
+<!-- Add relevant links to, for instance, related upstream issues. -->
+*
+
+
+## Test instructions
+<!--
+Please follow these guidelines when creating test instructions:
+- Please provide step-by-step instructions how to reproduce the issue, if applicable.
+- Write step-by-step instructions to test that the change fixes the issue.
+
+For changes which depend on a change in one of the external dependencies, don't forget to mention the following as the first steps:
+* Throw away an existing `vendor` directory and `composer.lock` file.
+* Run `composer install`.
+-->
+This PR can be tested by following these steps:
+
+*
+
+
+## Sniff feature completeness
+
+* [ ] **Documentation**: I have added/updated the sniff `Standard.xml` documentation to match this change.
+    * [ ] Not applicable.
+* [ ] **Functionality**: This change adds auto-fixer(s).
+    * [ ] Not applicable.
+* [ ] **Unit tests**: I have added unit tests to verify the code works as intended.
+* [ ] **End-to-end tests**: I have run the new/updated sniff against one or more of the Yoast plugin repositories to find false positives/negatives.
+
+Fixes #

.phpcs.xml.dist

@@ -8,9 +8,6 @@
 	<!-- Scan all files. -->
 	<file>.</file>
 
-	<!-- Exclude Composer vendor directory. -->
-	<exclude-pattern>*/vendor/*</exclude-pattern>
-
 	<!-- Only check PHP files. -->
 	<arg name="extensions" value="php"/>
 

.travis.yml

@@ -21,64 +21,83 @@ php:
     - 7.1
     - 7.2
     - 7.3
-    - nightly
+    - "7.4snapshot"
 
 env:
-  # Test against the highest supported PHPCS version.
-  - PHPCS_BRANCH="dev-master" PHPLINT=1
-  # Test against the lowest supported PHPCS version.
-  - PHPCS_BRANCH="3.4.0"
+  # Test against the highest/lowest supported PHPCS and WPCS versions.
+  - PHPCS_BRANCH="dev-master" WPCS="dev-develop" PHPLINT=1
+  - PHPCS_BRANCH="dev-master" WPCS="2.1.1"
+  - PHPCS_BRANCH="3.4.2" WPCS="dev-develop"
+  - PHPCS_BRANCH="3.4.2" WPCS="2.1.1"
 
 matrix:
   fast_finish: true
   include:
     # Extra build to check for XML codestyle.
     - php: 7.1
-      env: PHPCS_BRANCH="dev-master" SNIFF=1
+      env: PHPCS_BRANCH="dev-master" WPCS="^2.1.1" SNIFF=1
       addons:
           apt:
               packages:
                 - libxml2-utils
 
   allow_failures:
     # Allow failures for unstable builds.
-    - php: nightly
+    - php: "7.4snapshot"
 
 before_install:
     # Speed up build time by disabling Xdebug.
     # https://johnblackbourn.com/reducing-travis-ci-build-times-for-wordpress-projects/
     # https://twitter.com/kelunik/status/954242454676475904
     - phpenv config-rm xdebug.ini || echo 'No xdebug config.'
+
+    # On stable PHPCS versions, allow for PHP deprecation notices.
+    # Unit tests don't need to fail on those for stable releases where those issues won't get fixed anymore.
+    - |
+      if [[ $PHPCS_BRANCH != "dev-master" && $WPCS != "dev-develop" ]]; then
+        echo 'error_reporting = E_ALL & ~E_DEPRECATED' >> ~/.phpenv/versions/$(phpenv version-name)/etc/conf.d/travis.ini
+      fi
+    - php -r "echo ini_get('error_reporting');"
+
+
     - export XMLLINT_INDENT="	"
     - export PHPCS_DIR=$(pwd)/vendor/squizlabs/php_codesniffer
     - export PHPCS_BIN=$(pwd)/vendor/bin/phpcs
     # Set the PHPCS version to test against.
     - composer require squizlabs/php_codesniffer:${PHPCS_BRANCH} --no-update --no-suggest --no-scripts
+    # Set the WPCS version to test against.
+    - composer require wp-coding-standards/wpcs:${WPCS} --no-update --no-suggest --no-scripts
     - |
       if [[ "$SNIFF" == "1" ]]; then
           composer install --dev --no-suggest
           # The DealerDirect Composer plugin script takes care of the installed_paths.
       else
           # For testing the YoastCS native sniffs, the rest of the packages aren't needed.
-          composer remove wp-coding-standards/wpcs phpcompatibility/phpcompatibility-wp phpmd/phpmd --no-update
-          # This will now only install the version of PHPCS to test against.
-          composer install --no-dev --no-suggest --no-scripts
-          # Set the installed_paths for the test environment.
-          $PHPCS_BIN --config-set installed_paths $(pwd)
+          composer remove phpcompatibility/phpcompatibility-wp --no-update
+          # The Travis images for PHP >= 7.2 ship with PHPUnit 8, but the unit test suite is not compatible with that.
+          if [[ ${TRAVIS_PHP_VERSION:0:3} > "7.1" ]]; then composer require phpunit/phpunit:^7.0 --no-update --no-suggest --no-scripts;fi
+          # This will now only install the version of PHPCS/WPCS to test against.
+          composer install --no-dev --no-suggest
+          # The DealerDirect PHPCS Composer plugin takes care of the installed_paths.
       fi
+    - $PHPCS_BIN -i
 
 script:
     - if [[ "$PHPLINT" == "1" ]]; then if find . -path ./vendor -prune -o -name "*.php" -exec php -l {} \; | grep "^[Parse error|Fatal error]"; then exit 1; fi; fi
-    - phpunit --filter Yoast --bootstrap="$PHPCS_DIR/tests/bootstrap.php" $PHPCS_DIR/tests/AllTests.php
+    - |
+      if [[ ${TRAVIS_PHP_VERSION:0:3} > "7.1" ]]; then
+        vendor/bin/phpunit --filter Yoast --bootstrap="$PHPCS_DIR/tests/bootstrap.php" $PHPCS_DIR/tests/AllTests.php
+      else
+        phpunit --filter Yoast --bootstrap="$PHPCS_DIR/tests/bootstrap.php" $PHPCS_DIR/tests/AllTests.php
+      fi
     # Check the codestyle of the files within YoastCS.
     - if [[ "$SNIFF" == "1" ]]; then composer check-cs; fi
     # Validate the xml files.
     # @link http://xmlsoft.org/xmllint.html
     - if [[ "$SNIFF" == "1" ]]; then xmllint --noout --schema ./vendor/squizlabs/php_codesniffer/phpcs.xsd ./Yoast/ruleset.xml; fi
-    - if [[ "$SNIFF" == "1" ]]; then xmllint --noout ./phpmd.xml; fi
+    - if [[ "$SNIFF" == "1" ]]; then xmllint --noout ./Yoast/Docs/*/*Standard.xml; fi
     # Check the code-style consistency of the xml files.
     - if [[ "$SNIFF" == "1" ]]; then diff -B --tabsize=4 ./Yoast/ruleset.xml <(xmllint --format "./Yoast/ruleset.xml"); fi
-    - if [[ "$SNIFF" == "1" ]]; then diff -B --tabsize=4 ./phpmd.xml <(xmllint --format "./phpmd.xml"); fi
     # Validate the composer.json file.
     # @link https://getcomposer.org/doc/03-cli.md#validate
     - if [[ "$PHPLINT" == "1" ]]; then composer validate --no-check-all --strict; fi

CHANGELOG.md

@@ -1,8 +1,57 @@
-# Change Log for YoastCS
+# Changelog for YoastCS
 
 All notable changes to this project will be documented in this file.
 
-This projects adheres to [Semantic Versioning](https://semver.org/) and [Keep a CHANGELOG](https://keepachangelog.com/).
+This project adheres to [Semantic Versioning](https://semver.org/) and [Keep a CHANGELOG](https://keepachangelog.com/).
+
+### [1.3.0] - 2019-07-31
+
+#### Added
+* PHPCS: New `Yoast.Commenting.CoversTag` sniff.
+    This sniff verifies that:
+    - the contents of a `@covers` annotation is valid based on what's supported by PHPUnit;
+    - there are no duplicate `@covers` or `@coversNothing` tags in a docblock;
+    - a docblock doesn't contain both a `@covers` tag as well as a `@coversNothing` tag;
+    Includes a fixer for common errors.
+* PHPCS: New `Yoast.Commenting.TestsHaveCoversTag` sniff.
+    This sniff verifies that all unit test functions have at least one `@covers` tag - or a `@coversNothing` tag - in the function docblock or in the class docblock.
+* PHPCS: New `Yoast.Yoast.AlternativeFunctions` sniff.
+    This sniff allows for discouraging/forbidding the use of PHP/WP native functions in favor of using Yoast native functions.
+    In this initial version, the sniff checks for the use of the `json_encode()` and `wp_json_encode()` functions and suggests using `WPSEO_Utils::format_json_encode()` instead.
+    Note: this sniff contains an auto-fixer. If for any of the repos, the auto-fixer should not be used, the auto-fixer can be disabled from within the repo specific ruleset using `<rule ref="..." phpcs-only="true"/>`.
+* PHPCS: The `Squiz.WhiteSpace.MemberVarSpacing` sniff.
+    This sniff verifies and auto-fixes the number of blank lines between property declarations within OO-structures.
+* PHPCS: A default value for the `minimum_supported_wp_version` property which is used by various WPCS sniffs. The current default is WP `4.9`.
+   Previously this value would have to be set via a `config` directive in custom repo specific rulesets.
+   For those rulesets which use the Yoast default, this `config` directive can now be removed.
+   For more details, see [#131](https://github.com/Yoast/yoastcs/pull/131).
+* PHPCS: All YoastCS native sniffs are now accompanied by documentation which can be viewed from the command-line using `phpcs --generator=Text --standard=Yoast`.
+* Repo/QA: Various templates for typical pull requests to this repo.
+* Composer: `fix-cs` script.
+* Travis: Testing of the code against PHP 7.4 (unstable).
+
+#### Changed
+* PHPCS: Files in the following directories will now be excluded from all scans by default:
+    - `/.git/`
+    - `/.wordpress-svn/`
+    - `/node-modules/`
+    - `/vendor/`
+    - `/vendor_prefixed/`
+    Custom repo specific rulesets which contain excludes to this effect, can now remove them safely.
+* PHPCS: The message type for issues reported by the `Generic.Formatting.MultipleStatementAlignment` and `WordPress.Arrays.MultipleStatementAlignment` sniffs, has been upgraded from `warning` to `error`.
+* PHPCS: The WPCS native check for the `json_encode()` function in the `WordPress.WP.AlternativeFunctions` has been disabled in favor of the new YoastCS native `Yoast.Yoast.AlternativeFunctions` sniff.
+* Composer: Supported version of [PHP_CodeSniffer] has been changed from `^3.4.0` to `^3.4.2`.
+* Composer: Supported version of [WordPressCS] has been changed from `^2.0.0` to `^2.1.1`.
+* Travis: As there is now a sniff which extends a WPCS sniff, the unit tests will now run against various combinations of PHPCS and WPCS combined.
+* Minor housekeeping.
+
+#### Removed
+* PHPMD is no longer part of the YoastCS repo.
+    PHPMD was not used as a stand-alone tool by any of the repos, only in combination with CodeClimate.
+* Travis: Testing of the repo against PHP `nightly` (PHP 8, unstable) as no viable PHPUnit version is currently available.
+
+#### Fixed
+* PHPCS: The `Yoast.Files.FileName` sniff will now always suggest removing the longest prefix of the prefixes passed in the configuration.
 
 ### [1.2.2] - 2019-01-21
 
@@ -21,7 +70,7 @@ This projects adheres to [Semantic Versioning](https://semver.org/) and [Keep a
 #### Added
 * PHPCS: New `Yoast.Commenting.FileComment` sniff.
     This sniff is a wrapper around the `FileComment` sniff used in WordPressCS and manages the slightly different requirements for file comments set for the Yoast organisation, in particular:
-	- If a file is namespaced, no file comment is needed (and having one is discouraged).
+    - If a file is namespaced, no file comment is needed (and having one is discouraged).
 * PHPCS: New `Yoast.Namespaces.NamespaceDeclaration` sniff.
     This sniff forbids the use of:
     - Namespace declarations without a namespace name, i.e. `namespace;` which in effect means "global namespace".
@@ -242,6 +291,7 @@ Initial public release as a stand-alone package.
 [PHP Mess Detector]: https://github.com/phpmd/phpmd/blob/master/CHANGELOG
 [DealerDirect Composer PHPCS plugin]: https://github.com/Dealerdirect/phpcodesniffer-composer-installer/releases
 
+[1.3.0]: https://github.com/Yoast/yoastcs/compare/1.2.2...1.3.0
 [1.2.2]: https://github.com/Yoast/yoastcs/compare/1.2.1...1.2.2
 [1.2.1]: https://github.com/Yoast/yoastcs/compare/1.2.0...1.2.1
 [1.2.0]: https://github.com/Yoast/yoastcs/compare/1.1.0...1.2.0

README.md

@@ -6,7 +6,7 @@ Yoast Coding Standards (YoastCS) is a project with rulesets for code style and q
 
 ### Standalone
 
-Standards are provided as [Composer](https://getcomposer.org/) package and can be installed with:
+Standards are provided as a [Composer](https://getcomposer.org/) package and can be installed with:
 
 ```bash
 composer create-project yoast/yoastcs:dev-master
@@ -19,54 +19,68 @@ Composer will automatically install dependencies, register standards paths, and
 To include standards as part of a project require them as development dependencies:
 
 ```bash
-composer require yoast/yoastcs:dev-master --dev
+composer require --dev yoast/yoastcs:^1.0
 ```
 
-Note that Composer won't run configuration scripts in this scenario and the root project needs to take care of it.
+Composer will automatically install dependencies and register the YoastCS and other external standards with PHP_CodeSniffer.
 
 ## PHP Code Sniffer
 
-Set of [PHP Code Sniffer](https://github.com/squizlabs/PHP_CodeSniffer) rules.
-
-Based on [WordPress Coding Standards](https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards) project, implementing official [WordPress PHP Coding Standards](https://make.wordpress.org/core/handbook/coding-standards/php/).
+Set of [PHP_CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer) rules.
 
 Severity levels:
 
  - error level issues are considered mandatory to fix in Yoast projects and enforced in continuous integration
  - warning level issues are considered recommended to fix
 
-### Command line
+### The YoastCS Standard
+
+The `Yoast` standard for PHP_CodeSniffer is comprised of the following:
+* The `WordPress` ruleset from the [WordPress Coding Standards](https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards) implementing the official [WordPress PHP Coding Standards](https://make.wordpress.org/core/handbook/coding-standards/php/), with some [select exclusions](https://github.com/Yoast/yoastcs/blob/develop/Yoast/ruleset.xml#L29-L75).
+* The [`PHPCompatibilityWP`](https://github.com/PHPCompatibility/PHPCompatibilityWP) ruleset which checks code for PHP cross-version compatibility while preventing false positives for functionality polyfilled within WordPress.
+* Select additional sniffs taken from [`PHP_CodeSniffer`](https://github.com/squizlabs/PHP_CodeSniffer).
+* A number of custom Yoast specific sniffs.
+
+Files within version management and dependency related directories, such as the Composer `vendor` directory, are excluded from the scans by default.
 
+#### Sniffs
+
+To obtain a list of all sniffs used within YoastCS:
 ```bash
-"vendor/bin/phpcs" --extensions=php /path/to/folder/
+"vendor/bin/phpcs" -e --standard=Yoast
 ```
 
-### PhpStorm
+#### Sniff Documentation
 
-Refer to [Using PHP Code Sniffer Tool](https://www.jetbrains.com/phpstorm/help/using-php-code-sniffer-tool.html) in PhpStorm documentation.
+Not all sniffs have documentation available about what they sniff for, but for those which do, this documentation can be viewed from the command-line:
+```bash
+"vendor/bin/phpcs" --standard=Yoast --generator=text
+```
 
-After installation `Yoast` standard will be available as a choice in PHP Code Sniffer Validation inspection.
+### Running the sniffs
 
-## PHP Mess Detector
+#### Command line
 
-Set of [PHP Mess Detector](http://phpmd.org/) rules.
+```bash
+"vendor/bin/phpcs" --extensions=php /path/to/folder/
+```
 
-Original ruleset, produced for Yoast projects, taking under consideration typical WordPress practices and current state of code base.
+For more command-line options, please have a read through the [PHP_CodeSniffer documentation](https://github.com/squizlabs/PHP_CodeSniffer/wiki/Usage).
 
-All issues are considered informational for code development and maintenance.
+#### Yoast plugin repositories
 
-### Command line
+All Yoast plugin repositories contain a `[.]phpcs.xml.dist` file contain the repository specific configuration.
 
+From the root of these repositories, you can run PHPCS by using:
 ```bash
-"vendor/bin/phpmd" /path/to/folder/ text phpmd.xml
+composer check-cs
 ```
 
-### PhpStorm
-
-Refer to [Using PHP Mess Detector](https://www.jetbrains.com/phpstorm/help/using-php-mess-detector.html) in PhpStorm documentation.
+#### PhpStorm
 
-After installation add `phpmd.xml` file from project as custom ruleset in PHP Mess Detector Validation inspection settings.
+Refer to [Using PHP Code Sniffer Tool](https://www.jetbrains.com/phpstorm/help/using-php-code-sniffer-tool.html) in the PhpStorm documentation.
 
+After installation, the `Yoast` standard will be available as a choice in PHP Code Sniffer Validation inspection.
 
 ## Changelog
 

Yoast/Docs/Commenting/CodeCoverageIgnoreDeprecatedStandard.xml

@@ -0,0 +1,27 @@
+<?xml version="1.0"?>
+<documentation title="Code Coverage Ignore Deprecated">
+    <standard>
+    <![CDATA[
+    Deprecated functions and methods should be ignored for code coverage calculations.
+    ]]>
+    </standard>
+    <code_comparison>
+        <code title="Valid: Function marked as deprecated has a @codeCoverageIgnore tag.">
+        <![CDATA[
+/**
+ * <em>@deprecated x.x
+ * @codeCoverageIgnore</em>
+ */
+function deprecated_function() {}
+        ]]>
+        </code>
+        <code title="Invalid: Function marked as deprecated is missing a @codeCoverageIgnore tag.">
+        <![CDATA[
+/**
+ * <em>@deprecated x.x</em>
+ */
+function deprecated_function() {}
+        ]]>
+        </code>
+    </code_comparison>
+</documentation>