Skip to content

Commit

Permalink
Merge branch 'release/2.0.0'
Browse files Browse the repository at this point in the history
  • Loading branch information
IreneStr committed Dec 17, 2019
2 parents f2e02a9 + d1d9270 commit 2f445be
Show file tree
Hide file tree
Showing 74 changed files with 2,393 additions and 222 deletions.
8 changes: 8 additions & 0 deletions .phpcs.xml.dist
Original file line number Diff line number Diff line change
Expand Up @@ -32,4 +32,12 @@
<!-- Enforce PSR1 compatible namespaces. -->
<rule ref="PSR1.Classes.ClassDeclaration"/>

<rule ref="Yoast.NamingConventions.NamespaceName">
<properties>
<property name="prefixes" type="array">
<element value="YoastCS\Yoast"/>
</property>
</properties>
</rule>

</ruleset>
102 changes: 58 additions & 44 deletions .travis.yml
Original file line number Diff line number Diff line change
@@ -1,7 +1,4 @@
sudo: false

language:
- php
language: php

dist: trusty

Expand All @@ -26,24 +23,58 @@ php:
env:
# 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"
- PHPCS_BRANCH="dev-master" WPCS="2.2.0"
- PHPCS_BRANCH="3.5.0" WPCS="dev-develop"
- PHPCS_BRANCH="3.5.0" WPCS="2.2.0"

# 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: quicktest
if: type = push AND branch NOT IN (master, develop)
- name: test
if: branch IN (master, develop)

matrix:
fast_finish: true
include:
# Extra build to check for XML codestyle.
- php: 7.1
env: PHPCS_BRANCH="dev-master" WPCS="^2.1.1" SNIFF=1
#### SNIFF STAGE ####
- stage: sniff
php: 7.3
env: PHPCS_BRANCH="dev-master" WPCS="dev-master"
addons:
apt:
packages:
- libxml2-utils
apt:
packages:
- libxml2-utils
script:
# Check the codestyle of the files within YoastCS.
- composer check-cs

# 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 ./Yoast/ruleset.xml
- xmllint --noout ./Yoast/Docs/*/*Standard.xml

allow_failures:
# Allow failures for unstable builds.
- php: "7.4snapshot"
# Check the code-style consistency of the xml files.
- diff -B --tabsize=4 ./Yoast/ruleset.xml <(xmllint --format "./Yoast/ruleset.xml")

#### QUICK TEST STAGE ####
# This is a much quicker test which only runs the unit tests and linting against low/high
# supported PHP/PHPCS/WPCS combinations.
- stage: quicktest
php: 7.3
env: PHPCS_BRANCH="dev-master" WPCS="dev-develop" PHPLINT=1
- php: 7.3
env: PHPCS_BRANCH="3.5.0" WPCS="2.2.0"
- php: 5.4
env: PHPCS_BRANCH="dev-master" WPCS="2.2.0" PHPLINT=1
- php: 5.4
env: PHPCS_BRANCH="3.5.0" WPCS="dev-develop"

before_install:
# Speed up build time by disabling Xdebug.
Expand All @@ -54,11 +85,9 @@ before_install:
# 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
if [[ "$TRAVIS_BUILD_STAGE_NAME" != "Sniff" && $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
Expand All @@ -68,36 +97,21 @@ before_install:
# 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
if [[ "$TRAVIS_BUILD_STAGE_NAME" != "Sniff" ]]; then
# For testing the YoastCS native sniffs, the rest of the packages aren't needed.
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.
composer remove phpcompatibility/phpcompatibility-wp phpcompatibility/php-compatibility --no-update
fi
- composer install --dev --no-suggest
# The DealerDirect Composer plugin script takes care of the installed_paths.
- $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
- |
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 ./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
# Lint the PHP files against parse errors.
- if [[ "$PHPLINT" == "1" ]]; then composer lint; fi

# Run the unit tests.
- vendor/bin/phpunit --filter Yoast --bootstrap="$PHPCS_DIR/tests/bootstrap.php" $PHPCS_DIR/tests/AllTests.php

# 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
70 changes: 69 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,72 @@ All notable changes to this project will be documented in this file.

This project adheres to [Semantic Versioning](https://semver.org/) and [Keep a CHANGELOG](https://keepachangelog.com/).

### [2.0.0] - 2019-12-17

#### Added
* PHPCS: New `Yoast.NamingConventions.ObjectNameDepth` sniff.
- For objects _declared within a namespace_, this sniff verifies that an object name consist of maximum three words separated by underscores.
- For objects which are part of a unit test suite, a `_Test`, `_Mock` or `_Double` suffix at the end of the object name will be disregarded for the purposes of the word count.
- The sniff has two configurable properties `max_words` (error) and `recommended_max_words` (warning). The default for both is `3`.
* PHPCS: New `Yoast.NamingConventions.NamespaceName` sniff.
This sniff verifies that:
- Namespace names consist of a maximum of three levels (excluding the plugin specific prefix) and recommends for the name to be maximum two levels deep.
For unit test files, `Tests\(Doubles\)` directly after the prefix will be ignored when determining the level depth.
- The levels in the namespace name directly translate to the directory path to the file.
- The sniff has four configurable properties:
- `max_levels` (error) and `recommended_max_levels` (warning) which are by default set to `3` and `2` respectively.
- `src_directory` to indicate the project root(s) for the _path-to-name_ translation when the project root is not the repo root directory.
- `prefixes` to set the plugin specific prefix(es) to take into account.
* PHPCS: New `Yoast.NamingConventions.ValidHookName` sniff.
This sniff extends and adds to the upstream `WordPress.NamingConventions.ValidHookName` sniff.
The sniff will ignore non-prefixed hooks and hooks with a prefix unrelated to the plugin being examined, to prevent errors being thrown about hook names which are outside of our control.
This sniff verifies that:
- Hook names are in lowercase with words separated by underscores (same as WordPressCS).
- Hook names are prefixed with the plugin specific prefix in namespace format, i.e. `Yoast\WP\PluginName`.
Note: The prefix is exempt from the _lowercase with words separated by underscores_ rule.
If the non-namespace type prefix for a plugin is used, the sniff will throw a `warning`.
- The actual hook name (after the prefix) consist of maximum four words separated by underscores.
- Note: _The hook_name part should be descriptive for the (dev-)user and does not need to follow the namespace or file path of the file they are in._
- Also note: for dynamic hook names where the hook name length can not reliably be determined, the sniff will throw a `warning` at severity `3` suggesting the hook name be inspected manually.
As the default `severity` for PHPCS is `5`, this `warning` at severity `3` will normally not be shown.
It is there to allow for intermittently checking of the dynamic hook names. To trigger it, `--severity=3` should be passed on the command line.
- The sniff has three configurable properties:
- `maximum_depth` (error) and `soft_maximum_depth` (warning). The default for both is `4`.
- `prefixes` to set the plugin specific prefix(es) to take into account.
* PHPCS: The `Generic.Arrays.DisallowLongArraySyntax` sniff.
WPCS 2.2.0 demands long array syntax. In contrast to that, YoastCS demands short array syntax.
* PHPCS: The `Generic.ControlStructures.DisallowYodaConditions` sniff.
In contrast to WPCS, YoastCS never demanded Yoda conditions. With the addition of this sniff, "normal" (non-Yoda) conditions will now be enforced.
* PHPCS: The `Generic.WhiteSpace.SpreadOperatorSpacingAfter` sniff.
Enforces no space between the `...` spread operator and the variable/function call it applies to.
* PHPCS: The `PEAR.WhiteSpace.ObjectOperatorIndent` sniff.
Enforce consistent indentation of chained method calls to one more or less than the previous call in the chain and always at least one in from the start of the chain.
* PHPCS: The `PSR12.Classes.ClosingBrace` sniff.
This sniff disallows the outdated practice of `// end ...` comments for OO stuctures.
* PHPCS: The `PSR12.Files.ImportStatement` sniff.
Import `use` statements must always be fully qualified, so a leading backslash is redundant (and discouraged by PHP itself).
This sniff enforces that no leading backslash is used for import `use` statements.
* PHPCS: The `PSR12.Files.OpenTag` sniff.
Enforces that a PHP open tag is on a line by itself in PHP-only files.
* PHPCS: A `CustomPrefixesTrait` to handle checking names against a list of custom prefixes.
* Composer: `lint` script which uses the [Parallel-Lint] package for faster and more readable linting results.

#### Changed
* :warning: PHPCS: `Yoast.Files.FileName` sniff: the public `$prefixes` property, which can be used to indicate which _prefixes_ should be stripped of a class name when translating it to a file name, has been renamed to `$oo_prefixes`.
Custom repo specific rulesets using the property should be updates to reflect this change.
* :warning: PHPCS: `Yoast.Files.FileName` sniff: the public `$exclude` property, which can be used to indicate which files to exclude from the file name versus object name check, has been renamed to `$excluded_files_strict_check`.
Custom repo specific rulesets using the property should be updates to reflect this change.
* PHPCS: The default setting for the minimum supported PHP version for repos using YoastCS is now PHP 5.6 (was 5.2).
* PHPCS: The default value for the `minimum_supported_wp_version` property which is used by various WPCS sniffs has been update to WP `5.2` (was `4.9`).
* Composer: Supported version of [PHP_CodeSniffer] has been changed from `^3.4.2` to `^3.5.0`.
Note: this makes the option `--filter=gitstaged` available which can be used in git `pre-commit` hooks to only check staged files.
* Composer: Supported version of [WordPressCS] has been changed from `^2.1.1` to `^2.2.0`.
* Composer: Supported version of [PHPCompatibilityWP] has been changed from `^2.0.0` to `^2.1.0`.
* Travis: the build check is now run in stages.
* Travis: Tests against PHP 7.4 are no longer allowed to fail.
* Various housekeeping & code compliance with YoastCS 2.0.0.


### [1.3.0] - 2019-07-31

#### Added
Expand Down Expand Up @@ -285,12 +351,14 @@ Initial public release as a stand-alone package.


[PHP_CodeSniffer]: https://github.com/squizlabs/PHP_CodeSniffer/releases
[WordPressCS]: https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/blob/develop/CHANGELOG.md
[WordPressCS]: https://github.com/WordPress/WordPress-Coding-Standards/blob/develop/CHANGELOG.md
[PHPCompatibilityWP]: https://github.com/PHPCompatibility/PHPCompatibilityWP#changelog
[PHPCompatibility]: https://github.com/PHPCompatibility/PHPCompatibility/blob/master/CHANGELOG.md
[PHP Mess Detector]: https://github.com/phpmd/phpmd/blob/master/CHANGELOG
[DealerDirect Composer PHPCS plugin]: https://github.com/Dealerdirect/phpcodesniffer-composer-installer/releases
[Parallel-Lint]: https://packagist.org/packages/jakub-onderka/php-parallel-lint

[2.0.0]: https://github.com/Yoast/yoastcs/compare/1.3.0...2.0.0
[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
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ Severity levels:
### 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 `WordPress` ruleset from the [WordPress Coding Standards](https://github.com/WordPress/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.
Expand Down
51 changes: 51 additions & 0 deletions Yoast/Docs/NamingConventions/NamespaceNameStandard.xml
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
<?xml version="1.0"?>
<documentation title="Namespace Name Depth">
<standard>
<![CDATA[
A namespace name is not allowed to be more than 3 levels deep (excluding the prefix).
It is recommended for the name to be two levels.
For unit test files, `Tests\(Doubles\)` will be regarded as part of the prefix for this check.
]]>
</standard>
<code_comparison>
<code title="Valid: two-level namespace name declaration.">
<![CDATA[
namespace Yoast\WP\Plugin\<em>Admin\Forms</em>;
namespace Yoast\WP\Plugin\Tests\<em>Admin\Forms</em>;
]]>
</code>
<code title="Invalid: four-level namespace name declaration.">
<![CDATA[
namespace Yoast\WP\Plugin\<em>Admin\Forms\Type\Sub</em>;
namespace Yoast\WP\Plugin\Tests\<em>Foo\Bar\Flo\Sub</em>;
]]>
</code>
</code_comparison>
<standard>
<![CDATA[
The levels in a namespace name should reflect the path to the file.
The plugin specific prefix is disregarded for this check.
]]>
</standard>
<code_comparison>
<code title="Valid: namespace name reflects the path to the file.">
<![CDATA[
<!-- Path to file: <em>admin/forms/</em>file.php -->
<?php
namespace Yoast\WP\Plugin\<em>Admin\Forms</em>;
]]>
</code>
<code title="Invalid: namespace name does not reflect the path to the file.">
<![CDATA[
<!-- Path to file: <em>admin/forms/</em>file.php -->
<?php
namespace Yoast\WP\Plugin\<em>Unrelated</em>;
]]>
</code>
</code_comparison>
</documentation>
64 changes: 64 additions & 0 deletions Yoast/Docs/NamingConventions/ObjectNameDepthStandard.xml
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
<?xml version="1.0"?>
<documentation title="Object Name Depth">
<standard>
<![CDATA[
The name of objects - classes, interfaces, traits - declared within a namespace should consist of a maximum of three words.
A partial exception is made for test, mock and double classes. These can have a `_Test`, `_Mock` or `_Double` class name suffix, which won't be counted.
Note: the maximum (error) and the recommended (warning) maximum length are configurable.
]]>
</standard>
<code_comparison>
<code title="Valid: long class name in a file without a namespace.">
<![CDATA[
class <em>Non_Namespaced_Long_Class_Name</em> {}
]]>
</code>
<code title="Invalid: long class name in a namespaced file.">
<![CDATA[
namespace Yoast\WP\Plugin;
class <em>Namespaced_Long_Class_Name</em> {}
]]>
</code>
</code_comparison>
<code_comparison>
<code title="Valid: short class name in a namespaced file.">
<![CDATA[
namespace Yoast\WP\Plugin;
class <em>Short_Class_Name</em> {}
]]>
</code>
<code title="Invalid: long class name in a namespaced file.">
<![CDATA[
namespace Yoast\WP\Plugin;
class <em>Namespaced_Too_Long_Class_Name</em> {}
]]>
</code>
</code_comparison>
<code_comparison>
<code title="Valid: test class in a namespaced file.">
<![CDATA[
namespace Yoast\WP\Plugin\Tests;
use PHPUnit\Framework\TestCase;
class <em>Short_Class_Name_Test</em>
extends TestCase {}
]]>
</code>
<code title="Invalid: long test class name in a namespaced file.">
<![CDATA[
namespace Yoast\WP\Plugin\Tests;
use PHPUnit\Framework\TestCase;
class <em>Namespaced_Too_Long_Class_Name_Test</em>
extends TestCase {}
]]>
</code>
</code_comparison>
</documentation>
Loading

0 comments on commit 2f445be

Please sign in to comment.