Release version 2.2.0

.github/CONTRIBUTING.md

@@ -30,7 +30,7 @@ Once a commit is made to `develop`, a PR should be opened from `develop` into `m
 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/WordPress/WordPress-Coding-Standards/wiki/Customizable-sniff-properties) with the relevant details once your PR has been merged into the `develop` branch.
 
 ## Whitelist comments
 
@@ -51,7 +51,7 @@ When you introduce new `public` sniff properties, or your sniff extends a class
 
 The WordPress Coding Standards use the `PHP_CodeSniffer` native unit test suite for unit testing the sniffs.
 
-Presuming you have installed `PHP_CodeSniffer` and the WordPress-Coding-Standards as [noted in the README](https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards#how-to-use-this), all you need now is `PHPUnit`.
+Presuming you have installed `PHP_CodeSniffer` and the WordPress-Coding-Standards as [noted in the README](https://github.com/WordPress/WordPress-Coding-Standards#how-to-use-this), all you need now is `PHPUnit`.
 
 > N.B.: If you installed WPCS using Composer, make sure you used `--prefer-source` or run `composer install --prefer-source` now to make sure the unit tests are available.
 > Other than that, you're all set already as Composer will have installed PHPUnit for you.

.travis.yml

@@ -27,16 +27,90 @@ env:
   # Lowest supported release in the 3.x series with which WPCS is compatible.
   - PHPCS_BRANCH="3.3.1"
 
-matrix:
+# Define the stages used.
+# For non-PRs, only the sniff, ruleset and quicktest stages are run.
+# For pull requests and merges, the full script is run (skipping quicktest).
+# Note: for pull requests, "develop" should be the base branch name.
+# See: https://docs.travis-ci.com/user/conditions-v1
+stages:
+  - name: sniff
+  - name: rulesets
+  - name: quicktest
+    if: type = push AND branch NOT IN (master, develop)
+  - name: test
+    if: branch IN (master, develop)
+
+jobs:
   fast_finish: true
   include:
-    # Run PHPCS against WPCS. I just picked to run it against 7.2.
-    - php: 7.2
-      env: PHPCS_BRANCH="dev-master" SNIFF=1
+    #### SNIFF STAGE ####
+    - stage: sniff
+      php: 7.3
+      env: PHPCS_BRANCH="dev-master"
       addons:
         apt:
           packages:
             - libxml2-utils
+      script:
+        # WordPress Coding Standards.
+        # @link https://github.com/WordPress/WordPress-Coding-Standards
+        # @link http://pear.php.net/package/PHP_CodeSniffer/
+        - $(pwd)/vendor/bin/phpcs --runtime-set ignore_warnings_on_exit 1
+
+        # Validate the xml files.
+        # @link http://xmlsoft.org/xmllint.html
+        # For the build to properly error when validating against a scheme, these each have to be in their own condition.
+        - xmllint --noout --schema ./vendor/squizlabs/php_codesniffer/phpcs.xsd ./*/ruleset.xml
+        - xmllint --noout --schema ./vendor/squizlabs/php_codesniffer/phpcs.xsd ./phpcs.xml.dist.sample
+
+        # Check the code-style consistency of the xml files.
+        - diff -B --tabsize=4 ./WordPress/ruleset.xml <(xmllint --format "./WordPress/ruleset.xml")
+        - diff -B --tabsize=4 ./WordPress-Core/ruleset.xml <(xmllint --format "./WordPress-Core/ruleset.xml")
+        - diff -B --tabsize=4 ./WordPress-Docs/ruleset.xml <(xmllint --format "./WordPress-Docs/ruleset.xml")
+        - diff -B --tabsize=4 ./WordPress-Extra/ruleset.xml <(xmllint --format "./WordPress-Extra/ruleset.xml")
+        - diff -B --tabsize=4 ./phpcs.xml.dist.sample <(xmllint --format "./phpcs.xml.dist.sample")
+
+    #### RULESET STAGE ####
+    # Make sure the rulesets don't throw unexpected errors or warnings.
+    # This check needs to be run against a high PHP version to prevent triggering the syntax error check.
+    # It also needs to be run against all PHPCS versions WPCS is tested against.
+    - stage: rulesets
+      php: 7.3
+      env: PHPCS_BRANCH="dev-master"
+      script:
+        - $(pwd)/vendor/bin/phpcs -ps ./bin/class-ruleset-test.php --standard=WordPress-Core
+        - $(pwd)/vendor/bin/phpcs -ps ./bin/class-ruleset-test.php --standard=WordPress-Docs
+        - $(pwd)/vendor/bin/phpcs -ps ./bin/class-ruleset-test.php --standard=WordPress-Extra
+        - $(pwd)/vendor/bin/phpcs -ps ./bin/class-ruleset-test.php --standard=WordPress
+
+        # Test for fixer conflicts by running the auto-fixers of the complete WPCS over the test case files.
+        # This is not an exhaustive test, but should give an early indication for typical fixer conflicts.
+        # For the first run, the exit code will be 1 (= all fixable errors fixed).
+        # `travis_retry` should then kick in to run the fixer again which should now return 0 (= no fixable errors found).
+        # All error codes for the PHPCBF: https://github.com/squizlabs/PHP_CodeSniffer/issues/1270#issuecomment-272768413
+        - travis_retry $(pwd)/vendor/bin/phpcbf -pq ./WordPress/Tests/ --standard=WordPress --extensions=inc --exclude=Generic.PHP.Syntax --report=summary
+
+    - stage: rulesets
+      php: 7.3
+      env: PHPCS_BRANCH="3.3.1"
+      script:
+        - $(pwd)/vendor/bin/phpcs -ps ./bin/class-ruleset-test.php --standard=WordPress-Core
+        - $(pwd)/vendor/bin/phpcs -ps ./bin/class-ruleset-test.php --standard=WordPress-Docs
+        - $(pwd)/vendor/bin/phpcs -ps ./bin/class-ruleset-test.php --standard=WordPress-Extra
+        - $(pwd)/vendor/bin/phpcs -ps ./bin/class-ruleset-test.php --standard=WordPress
+
+    #### QUICK TEST STAGE ####
+    # This is a much quicker test which only runs the unit tests and linting against the low/high
+    # supported PHP/PHPCS combinations.
+    - stage: quicktest
+      php: 7.3
+      env: PHPCS_BRANCH="dev-master" LINT=1
+    - php: 7.3
+      env: PHPCS_BRANCH="3.3.1"
+    - php: 5.4
+      env: PHPCS_BRANCH="dev-master" LINT=1
+    - php: 5.4
+      env: PHPCS_BRANCH="3.3.1"
 
   allow_failures:
     # Allow failures for unstable builds.
@@ -47,11 +121,19 @@ before_install:
     # 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 [[ "$TRAVIS_BUILD_STAGE_NAME" != "Sniff" && $PHPCS_BRANCH != "dev-master" ]]; then
+        echo 'error_reporting = E_ALL & ~E_DEPRECATED' >> ~/.phpenv/versions/$(phpenv version-name)/etc/conf.d/travis.ini
+      fi
+
     - export XMLLINT_INDENT="	"
     - export PHPUNIT_DIR=/tmp/phpunit
     - composer require squizlabs/php_codesniffer:${PHPCS_BRANCH} --update-no-dev --no-suggest --no-scripts
     - |
-      if [[ "$SNIFF" == "1" ]]; then
+      if [[ "$TRAVIS_BUILD_STAGE_NAME" == "Sniff" ]]; then
           composer install --dev --no-suggest
           # The `dev` required DealerDirect Composer plugin takes care of the installed_paths.
       else
@@ -63,42 +145,17 @@ before_install:
     - if [[ ${TRAVIS_PHP_VERSION:0:3} > "7.1" ]]; then wget -P $PHPUNIT_DIR https://phar.phpunit.de/phpunit-7.phar && chmod +x $PHPUNIT_DIR/phpunit-7.phar; fi
 
 script:
-    # Lint the PHP files against parse errors.
-    - if [[ "$LINT" == "1" ]]; then if find . -path ./vendor -prune -o -path ./bin -prune -o -name "*.php" -exec php -l {} \; | grep "^[Parse error|Fatal error]"; then exit 1; fi; fi
-    # Run the unit tests.
-    - |
-      if [[ ${TRAVIS_PHP_VERSION:0:3} > "7.1" ]]; then
-        php $PHPUNIT_DIR/phpunit-7.phar --filter WordPress --bootstrap="$(pwd)/vendor/squizlabs/php_codesniffer/tests/bootstrap.php" $(pwd)/vendor/squizlabs/php_codesniffer/tests/AllTests.php
-      else
-        phpunit --filter WordPress --bootstrap="$(pwd)/vendor/squizlabs/php_codesniffer/tests/bootstrap.php" $(pwd)/vendor/squizlabs/php_codesniffer/tests/AllTests.php
-      fi
-    # Test for fixer conflicts by running the auto-fixers of the complete WPCS over the test case files.
-    # This is not an exhaustive test, but should give an early indication for typical fixer conflicts.
-    # For the first run, the exit code will be 1 (= all fixable errors fixed).
-    # `travis_retry` should then kick in to run the fixer again which should now return 0 (= no fixable errors found).
-    # All error codes for the PHPCBF: https://github.com/squizlabs/PHP_CodeSniffer/issues/1270#issuecomment-272768413
-    - if [[ "$SNIFF" == "1" ]]; then travis_retry $(pwd)/vendor/bin/phpcbf -p ./WordPress/Tests/ --standard=WordPress --extensions=inc --exclude=Generic.PHP.Syntax --report=summary; fi
-    # Make sure the rulesets don't thrown unexpected errors or warnings.
-    # This check needs to be run against a high PHP version to prevent triggering the syntax error check.
-    # It also needs to be run against all PHPCS versions WPCS is tested against.
-    - if [[ $TRAVIS_PHP_VERSION == "7.1" ]]; then $(pwd)/vendor/bin/phpcs -s ./bin/class-ruleset-test.php --standard=WordPress-Core; fi
-    - if [[ $TRAVIS_PHP_VERSION == "7.1" ]]; then $(pwd)/vendor/bin/phpcs -s ./bin/class-ruleset-test.php --standard=WordPress-Docs; fi
-    - if [[ $TRAVIS_PHP_VERSION == "7.1" ]]; then $(pwd)/vendor/bin/phpcs -s ./bin/class-ruleset-test.php --standard=WordPress-Extra; fi
-    - if [[ $TRAVIS_PHP_VERSION == "7.1" ]]; then $(pwd)/vendor/bin/phpcs -s ./bin/class-ruleset-test.php --standard=WordPress; fi
-    # WordPress Coding Standards.
-    # @link https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards
-    # @link http://pear.php.net/package/PHP_CodeSniffer/
-    - if [[ "$SNIFF" == "1" ]]; then $(pwd)/vendor/bin/phpcs --runtime-set ignore_warnings_on_exit 1; fi
-    # Validate the xml files.
-    # @link http://xmlsoft.org/xmllint.html
-    - if [[ "$SNIFF" == "1" ]]; then xmllint --noout --schema ./vendor/squizlabs/php_codesniffer/phpcs.xsd ./*/ruleset.xml; fi
-    - if [[ "$SNIFF" == "1" ]]; then xmllint --noout --schema ./vendor/squizlabs/php_codesniffer/phpcs.xsd ./phpcs.xml.dist.sample; fi
-    # Check the code-style consistency of the xml files.
-    - if [[ "$SNIFF" == "1" ]]; then diff -B --tabsize=4 ./WordPress/ruleset.xml <(xmllint --format "./WordPress/ruleset.xml"); fi
-    - if [[ "$SNIFF" == "1" ]]; then diff -B --tabsize=4 ./WordPress-Core/ruleset.xml <(xmllint --format "./WordPress-Core/ruleset.xml"); fi
-    - if [[ "$SNIFF" == "1" ]]; then diff -B --tabsize=4 ./WordPress-Docs/ruleset.xml <(xmllint --format "./WordPress-Docs/ruleset.xml"); fi
-    - if [[ "$SNIFF" == "1" ]]; then diff -B --tabsize=4 ./WordPress-Extra/ruleset.xml <(xmllint --format "./WordPress-Extra/ruleset.xml"); fi
-    - if [[ "$SNIFF" == "1" ]]; then diff -B --tabsize=4 ./phpcs.xml.dist.sample <(xmllint --format "./phpcs.xml.dist.sample"); fi
-    # Validate the composer.json file.
-    # @link https://getcomposer.org/doc/03-cli.md#validate
-    - if [[ "$LINT" == "1" ]]; then composer validate --no-check-all --strict; fi
+  # Lint the PHP files against parse errors.
+  - if [[ "$LINT" == "1" ]]; then if find . -path ./vendor -prune -o -path ./bin -prune -o -name "*.php" -exec php -l {} \; | grep "^[Parse error|Fatal error]"; then exit 1; fi; fi
+
+  # Validate the composer.json file.
+  # @link https://getcomposer.org/doc/03-cli.md#validate
+  - if [[ "$LINT" == "1" ]]; then composer validate --no-check-all --strict; fi
+
+  # Run the unit tests.
+  - |
+    if [[ ${TRAVIS_PHP_VERSION:0:3} > "7.1" ]]; then
+      php $PHPUNIT_DIR/phpunit-7.phar --filter WordPress --bootstrap="$(pwd)/vendor/squizlabs/php_codesniffer/tests/bootstrap.php" $(pwd)/vendor/squizlabs/php_codesniffer/tests/AllTests.php
+    else
+      phpunit --filter WordPress --bootstrap="$(pwd)/vendor/squizlabs/php_codesniffer/tests/bootstrap.php" $(pwd)/vendor/squizlabs/php_codesniffer/tests/AllTests.php
+    fi