Skip to content

Add documentation for FileName sniff #1142

Add documentation for FileName sniff

Add documentation for FileName sniff #1142

Workflow file for this run

name: Basic QA checks
on:
push:
pull_request:
# Allow manually triggering the workflow.
workflow_dispatch:
# Cancels all previous workflow runs for the same branch that have not yet completed.
concurrency:
# The concurrency group contains the workflow name and the branch name.
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
env:
PHPCS_DEV: 'dev-master'
UTILS_DEV: 'dev-develop'
EXTRA_DEV: 'dev-develop'
jobs:
# Check code style of sniffs, rulesets and XML documentation.
# Check that all sniffs are feature complete.
sniffs:
name: Run code sniffs
runs-on: ubuntu-latest
env:
XMLLINT_INDENT: ' '
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: Setup PHP
uses: shivammathur/setup-php@v2
with:
php-version: 'latest'
coverage: none
tools: cs2pr
# @link https://getcomposer.org/doc/03-cli.md#validate
- name: Validate the composer.json file
run: composer validate --no-check-all --strict
# Using dev versions of the dependencies as an early detection system for bugs upstream.
- name: "Composer: set PHPCS dependencies (dev)"
run: >
composer require --no-update --no-scripts --no-interaction
squizlabs/php_codesniffer:"${{ env.PHPCS_DEV }}"
phpcsstandards/phpcsutils:"${{ env.UTILS_DEV }}"
phpcsstandards/phpcsextra:"${{ env.EXTRA_DEV }}"
- name: Install Composer dependencies
uses: ramsey/composer-install@v3
with:
# Bust the cache at least once a month - output format: YYYY-MM.
custom-cache-suffix: $(date -u "+%Y-%m")
# Updating the lists can fail intermittently, typically after Microsoft has released a new package.
# This should not be blocking for this job, so ignore any errors from this step.
# Ref: https://github.com/dotnet/core/issues/4167
- name: Update the available packages list
continue-on-error: true
run: sudo apt-get update
- name: Install xmllint
run: sudo apt-get install --no-install-recommends -y libxml2-utils
# Show XML violations inline in the file diff.
# @link https://github.com/marketplace/actions/xmllint-problem-matcher
- name: Enable showing XML issues inline
uses: korelstar/xmllint-problem-matcher@v1
- name: Check the code style of the PHP files
id: phpcs
run: vendor/bin/phpcs --report-full --report-checkstyle=./phpcs-report.xml
- name: Show PHPCS results in PR
if: ${{ always() && steps.phpcs.outcome == 'failure' }}
run: cs2pr ./phpcs-report.xml
# Validate the Ruleset XML files.
# @link http://xmlsoft.org/xmllint.html
- name: Validate the WordPress rulesets
run: xmllint --noout --schema vendor/squizlabs/php_codesniffer/phpcs.xsd ./*/ruleset.xml
- name: Validate the sample ruleset
run: xmllint --noout --schema vendor/squizlabs/php_codesniffer/phpcs.xsd ./phpcs.xml.dist.sample
# Validate the Documentation XML files.
- name: Validate documentation against schema
run: xmllint --noout --schema vendor/phpcsstandards/phpcsdevtools/DocsXsd/phpcsdocs.xsd ./WordPress/Docs/*/*Standard.xml
- name: Check the code-style consistency of the xml files
run: |
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")
# Check that the sniffs available are feature complete.
# For now, just check that all sniffs have unit tests.
# At a later stage the documentation check can be activated.
- name: Check sniff feature completeness
run: composer check-complete
# Makes sure the rulesets don't throw unexpected errors or warnings.
# This workflow needs to be run against a high PHP version to prevent triggering the syntax error check.
# It also needs to be run against all dependency versions WPCS is tested against.
ruleset-tests:
runs-on: ubuntu-latest
strategy:
matrix:
php: [ 'latest' ]
dependencies: [ 'lowest', 'stable', 'dev' ]
name: "Ruleset test: PHP ${{ matrix.php }} on PHPCS ${{ matrix.dependencies }}"
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: Set up PHP
uses: shivammathur/setup-php@v2
with:
php-version: ${{ matrix.php }}
# Allow for PHP deprecation notices.
ini-values: error_reporting = E_ALL & ~E_DEPRECATED
coverage: none
- name: "Composer: set PHPCS dependencies for tests (dev)"
if: ${{ matrix.dependencies == 'dev' }}
run: >
composer require --no-update --no-scripts --no-interaction
squizlabs/php_codesniffer:"${{ env.PHPCS_DEV }}"
phpcsstandards/phpcsutils:"${{ env.UTILS_DEV }}"
phpcsstandards/phpcsextra:"${{ env.EXTRA_DEV }}"
- name: Enable creation of `composer.lock` file
if: ${{ matrix.dependencies == 'lowest' }}
run: composer config --unset lock
- name: Install Composer dependencies
uses: ramsey/composer-install@v3
with:
composer-options: --no-dev
# Bust the cache at least once a month - output format: YYYY-MM.
custom-cache-suffix: $(date -u "+%Y-%m")
- name: "Composer: downgrade PHPCS dependencies for tests (lowest)"
if: ${{ matrix.dependencies == 'lowest' }}
run: >
composer update --prefer-lowest --no-scripts --no-interaction
squizlabs/php_codesniffer
phpcsstandards/phpcsutils
phpcsstandards/phpcsextra
- name: Test the WordPress-Core ruleset
run: $(pwd)/vendor/bin/phpcs -ps ./Tests/RulesetCheck/class-ruleset-test.inc --standard=WordPress-Core
- name: Test the WordPress-Docs ruleset
run: $(pwd)/vendor/bin/phpcs -ps ./Tests/RulesetCheck/class-ruleset-test.inc --standard=WordPress-Docs
- name: Test the WordPress-Extra ruleset
run: $(pwd)/vendor/bin/phpcs -ps ./Tests/RulesetCheck/class-ruleset-test.inc --standard=WordPress-Extra
- name: Test the WordPress ruleset
run: $(pwd)/vendor/bin/phpcs -ps ./Tests/RulesetCheck/class-ruleset-test.inc --standard=WordPress
- name: Rename the example ruleset to one which can be used for a ruleset
run: cp phpcs.xml.dist.sample sample.xml
- name: Test the example ruleset
run: $(pwd)/vendor/bin/phpcs -ps ./Tests/RulesetCheck/example-ruleset-test.inc --standard=./sample.xml
# 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.
# If only fixable errors are found, the exit code will be 1, which can be interpreted as success.
# This check is only run against "dev" as conflicts can not be fixed for already released versions.
- name: Test for fixer conflicts (fixes expected)
if: ${{ matrix.dependencies == 'dev' }}
id: phpcbf
continue-on-error: true
run: |
set +e
$(pwd)/vendor/bin/phpcbf -pq ./WordPress/Tests/ --standard=WordPress --extensions=inc --exclude=Generic.PHP.Syntax --report=summary --ignore=/WordPress/Tests/WP/GlobalVariablesOverrideUnitTest.7.inc
exitcode="$?"
echo "EXITCODE=$exitcode" >> $GITHUB_OUTPUT
exit "$exitcode"
- name: Fail the build on fixer conflicts and other errors
if: ${{ steps.phpcbf.outputs.EXITCODE != 0 && steps.phpcbf.outputs.EXITCODE != 1 }}
run: exit ${{ steps.phpcbf.outputs.EXITCODE }}
phpstan:
name: "PHPStan"
runs-on: "ubuntu-latest"
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Install PHP
uses: shivammathur/setup-php@v2
with:
php-version: 'latest'
coverage: none
tools: phpstan
# Install dependencies and handle caching in one go.
# Dependencies need to be installed to make sure the PHPCS and PHPUnit classes are recognized.
# @link https://github.com/marketplace/actions/install-php-dependencies-with-composer
- name: Install Composer dependencies
uses: "ramsey/composer-install@v3"
with:
# Bust the cache at least once a month - output format: YYYY-MM.
custom-cache-suffix: $(date -u "+%Y-%m")
- name: Run PHPStan
run: phpstan analyse