Merge pull request #794 from Automattic/release/3.0.0

Author: GaryJones

.github/CONTRIBUTING.md

@@ -17,11 +17,12 @@ Since VIPCS employs many sniffs that are part of PHPCS, and makes use of WordPre
 
 To determine where best to report the bug, use the first part of the sniff name:
 
-Sniffname starts with | Report to
+Sniff name starts with | Report to
 --- | ---
 `Generic` | [PHP_CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer/issues/)
 `PSR2` | [PHP_CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer/issues/)
 `Squiz` | [PHP_CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer/issues/)
+`Universal` | [PHPCSExtra](https://github.com/PHPCSStandards/PHPCSExtra/issues/)
 `VariableAnalysis` | [VariableAnalysis](https://github.com/sirbrillig/phpcs-variable-analysis/issues/)
 `WordPress` | [WordPressCS](https://github.com/WordPress/WordPress-Coding-Standards/issues/)
 `WordPressVIPMinimum` | [VIPCS](https://github.com/Automattic/VIP-Coding-Standards/issues/) (this repo)
@@ -44,7 +45,7 @@ After `composer install`, you can do:
 
 ## Branches
 
-Ongoing development will be done in feature branches then pulled against the `develop` branch and follows a typical _git-flow_ approach, where merges to `master` only happen when a new release is made.
+Ongoing development will be done in feature branches then pulled against the `develop` branch and follows a typical _git-flow_ approach, where merges to `main` only happen when a new release is made.
 
 To contribute an improvement to this project, fork the repo and open a pull request to the relevant branch. Alternatively, if you have push access to this repo, create a feature branch prefixed by `fix/` (followed by the issue number) or `add/` and then open a PR from that branch to the default (`develop`) branch.
 
@@ -90,7 +91,7 @@ The easiest way to do this is to add a `phpunit.xml` file to the root of your VI
 <?xml version="1.0" encoding="UTF-8"?>
 <phpunit
 	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-	xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/7.2/phpunit.xsd"
+	xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/7.5/phpunit.xsd"
 	backupGlobals="true"
 	bootstrap="./tests/bootstrap.php"
 	beStrictAboutTestsThatDoNotTestAnything="false"
@@ -112,47 +113,52 @@ The easiest way to do this is to add a `phpunit.xml` file to the root of your VI
 * To run the unit tests:
 
     ```sh
-    phpunit --filter WordPressVIPMinimum $PHPCS_DIR/tests/AllTests.php
+    composer test
     ```
 
 Expected output:
 ```
 PHPUnit 7.5.20 by Sebastian Bergmann and contributors.
 
-..........................................                        42 / 42 (100%)
+........................................                          40 / 40 (100%)
 
-43 sniff test files generated 117 unique error codes; 0 were fixable (0%)
+45 sniff test files generated 175 unique error codes; 0 were fixable (0%)
 
-Time: 246 ms, Memory: 32.00 MB
+Time: 150 ms, Memory: 20.00 MB
+
+OK (40 tests, 0 assertions)
 ```
 
 ### Unit Testing conventions
 
-If you look inside the `WordPressVIPMinimum/Tests` subdirectory, you'll see the structure mimics the `WordPressVIPMinimum/Sniffs` subdirectory structure. For example, the `WordPressVIPMinimum/Sniffs/VIP/WPQueryParams.php` sniff has its unit test class defined in `WordPressVIPMinimum/Tests/VIP/WPQueryParamsUnitTest.php` which checks the `WordPressVIPMinimum/Tests/VIP/WPQueryParamsUnitTest.inc` test case file. See the file naming convention?
+If you look inside the `WordPressVIPMinimum/Tests` subdirectory, you'll see the structure mimics the `WordPressVIPMinimum/Sniffs` subdirectory structure. For example, the `WordPressVIPMinimum/Sniffs/Performance/WPQueryParams.php` sniff has its unit test class defined in `WordPressVIPMinimum/Tests/Performance/WPQueryParamsUnitTest.php` which checks the `WordPressVIPMinimum/Tests/Performance/WPQueryParamsUnitTest.inc` test case file. See the file naming convention?
 
-Lets take a look at what's inside `WPQueryParamsUnitTest.php`:
+Let's take a look at what's inside `WPQueryParamsUnitTest.php`:
 
 ```php
 ...
-namespace WordPressVIPMinimum\Tests\VIP;
+namespace WordPressVIPMinimum\Tests\Performance;
 
 use PHP_CodeSniffer\Tests\Standards\AbstractSniffUnitTest;
 
 /**
  * Unit test class for the WP_Query params sniff.
+ *
+ * @covers \WordPressVIPMinimum\Sniffs\Performance\WPQueryParamsSniff
  */
 class WPQueryParamsUnitTest extends AbstractSniffUnitTest {
 
 	/**
 	 * Returns the lines where errors should occur.
 	 *
-	 * @return array <int line number> => <int number of errors>
+	 * @return array<int, int> Key is the line number, value is the number of expected errors.
 	 */
 	public function getErrorList() {
-		return array(
+		return [
 			5  => 1,
 			17 => 1,
-		);
+			31 => 1,
+		];
 	}
 ...
 ```
@@ -161,24 +167,35 @@ Also note the class name convention. The method `getErrorList()` MUST return an
 If you run:
 
 ```sh
-$ cd /path-to-cloned/phpcs
-$ ./bin/phpcs --standard=WordPressVIPMinimum -s --sniffs=WordPressVIPMinimum.VIP.WPQueryParams /path/to/WordPressVIPMinimum/Tests/VIP/WPQueryParamsUnitTest.inc
-...
-E 1 / 1 (100%)
-
-
-
-FILE: /path/to/vipcs/WordPressVIPMinimum/Tests/VIP/WPQueryParamsUnitTest.inc
---------------------------------------------------------------------------------------------------------------------------------
-FOUND 2 ERRORS AND 2 WARNINGS AFFECTING 4 LINES
---------------------------------------------------------------------------------------------------------------------------------
-  4 | WARNING | Using `post__not_in` should be done with caution. (WordPressVIPMinimum.VIP.WPQueryParams.post__not_in)
-  5 | ERROR   | Setting `suppress_filters` to `true` is probihited.
-    |         | (WordPressVIPMinimum.VIP.WPQueryParams.suppressFiltersTrue)
- 11 | WARNING | Using `post__not_in` should be done with caution. (WordPressVIPMinimum.VIP.WPQueryParams.post__not_in)
- 17 | ERROR   | Setting `suppress_filters` to `true` is probihited.
-    |         | (WordPressVIPMinimum.VIP.WPQueryParams.suppressFiltersTrue)
---------------------------------------------------------------------------------------------------------------------------------
+$ cd /path/to/vipcs
+$ ./vendor/bin/phpcs --standard=WordPressVIPMinimum -s --sniffs=WordPressVIPMinimum.Performance.WPQueryParams WordPressVIPMinimum/Tests/Performance/WPQueryParamsUnitTest.inc
+
+FILE: /path/to/vipcs/WordPressVIPMinimum/Tests/Performance/WPQueryParamsUnitTest.inc
+------------------------------------------------------------------------------------------------------------------------------------------------------
+FOUND 3 ERRORS AND 5 WARNINGS AFFECTING 8 LINES
+------------------------------------------------------------------------------------------------------------------------------------------------------
+  4 | WARNING | Using exclusionary parameters, like post__not_in, in calls to get_posts() should be done with caution, see
+    |         | https://wpvip.com/documentation/performance-improvements-by-removing-usage-of-post__not_in/ for more information.
+    |         | (WordPressVIPMinimum.Performance.WPQueryParams.PostNotIn_post__not_in)
+  5 | ERROR   | Setting `suppress_filters` to `true` is prohibited.
+    |         | (WordPressVIPMinimum.Performance.WPQueryParams.SuppressFilters_suppress_filters)
+ 11 | WARNING | Using exclusionary parameters, like post__not_in, in calls to get_posts() should be done with caution, see
+    |         | https://wpvip.com/documentation/performance-improvements-by-removing-usage-of-post__not_in/ for more information.
+    |         | (WordPressVIPMinimum.Performance.WPQueryParams.PostNotIn_post__not_in)
+ 17 | ERROR   | Setting `suppress_filters` to `true` is prohibited.
+    |         | (WordPressVIPMinimum.Performance.WPQueryParams.SuppressFilters_suppress_filters)
+ 21 | WARNING | Using exclusionary parameters, like exclude, in calls to get_posts() should be done with caution, see
+    |         | https://wpvip.com/documentation/performance-improvements-by-removing-usage-of-post__not_in/ for more information.
+    |         | (WordPressVIPMinimum.Performance.WPQueryParams.PostNotIn_exclude)
+ 29 | WARNING | Using exclusionary parameters, like exclude, in calls to get_posts() should be done with caution, see
+    |         | https://wpvip.com/documentation/performance-improvements-by-removing-usage-of-post__not_in/ for more information.
+    |         | (WordPressVIPMinimum.Performance.WPQueryParams.PostNotIn_exclude)
+ 30 | WARNING | Using exclusionary parameters, like exclude, in calls to get_posts() should be done with caution, see
+    |         | https://wpvip.com/documentation/performance-improvements-by-removing-usage-of-post__not_in/ for more information.
+    |         | (WordPressVIPMinimum.Performance.WPQueryParams.PostNotIn_exclude)
+ 31 | ERROR   | Setting `suppress_filters` to `true` is prohibited.
+    |         | (WordPressVIPMinimum.Performance.WPQueryParams.SuppressFilters_suppress_filters)
+------------------------------------------------------------------------------------------------------------------------------------------------------
 ....
 ```
 You'll see the line number and number of ERRORs we need to return in the `getErrorList()` method.
@@ -189,23 +206,26 @@ The `--sniffs=...` directive limits the output to the sniff you are testing.
 
 The ruleset tests, previously named here as _integration tests_, are our way of ensuring that _rulesets_ do check for the violations we expect them to.
 
-An example where it might not would be when a ruleset references a local sniff or a sniff from upstream (WPCS or PHPCS), but that the violation code, sniff name or category name has changed. Without a ruleset test, this would go unnoticed.
+An example where it might not would be when a ruleset references a local sniff or a sniff from upstream (WordPressCS or PHPCS), but that the violation code, sniff name or category name has changed. Without a ruleset test, this would go unnoticed.
 
-The `composer check` or `composer test-ruleset` commands run the `ruleset-test.php` files (one for each standard), which internally run `phpcs` against the "dirty" test files (`ruleset-test.inc`), and looks out for a known number of errors, warnings, and messages on each line. This is then compared against the expected errors, warnings and messages to see if there are any missing or unexpected violations or difference in messages.
+The `composer check` or `composer test-ruleset` commands run the `ruleset-test.php` files (one for each ruleset), which internally run `phpcs` against the "dirty" test files (`ruleset-test.inc`), and looks out for a known number of errors, warnings, and messages on each line. This is then compared against the expected errors, warnings, and messages to see if there are any missing or unexpected violations or difference in messages.
 
 When adding or changing a sniff, the ruleset test files should be updated to match.
 
 ## Releases
 
-- In a `changelog/x.y.z` branch off of `develop`, update the `CHANGELOG.md` with a list of all of the changes following the keepachangelog.com format. Include PR references and GitHub username props.
-- Create a PR of `develop` <-- `changelog/x.y.z`, but do not merge until ready to release.
-- Create a PR of `master` <-- `develop`, and copy-paste the [`release-template.md`](https://github.com/Automattic/VIP-Coding-Standards/blob/develop/.github/ISSUE_TEMPLATE/release-template.md) contents.
-- When ready to release, merge the change log PR into `develop`, then merge the `develop` into `master` PR.
-- Tag the commit in `master` with the appropriate version number. Ideally, have it signed.
-- Close the current milestone.
+- Create a `release/x.y.z` branch off of `develop`.
+- In a `release/x.y.z-changelog` branch off of `release/x.y.z`, update the `CHANGELOG.md` with a list of all of the changes following the keepachangelog.com format. Include PR references and GitHub username props.
+- Create a PR of `release/x.y.z` <-- `release/x.y.z-changelog`, but do not merge until ready to release.
+- Create any other last-minute PRs as necessary, such as documentation updates, against the release branch.
+- When ready to release, merge the changelog and other branches into `release/x.y.z`.
+- Create a PR of `main` <-- `release/x.y.z`, and copy-paste the [`release-template.md`](https://github.com/Automattic/VIP-Coding-Standards/blob/develop/.github/ISSUE_TEMPLATE/release-template.md) contents.
+- When ready to release, merge `release/x.y.z` into `main`. Undelete the release branch after merging.
+- Tag the commit in `main` with the appropriate version number. Ideally, have it signed.
 - Open a new milestone for the next release.
 - If any open PRs/issues which were milestoned for this release do not make it into the release, update their milestone.
-- Write a Lobby post to inform VIP customers about the release, including the date when the Review Bot will be updated (usually about 1.5 weeks after the VIPCS release).
+- Close the current milestone.
+- Create a PR of `develop` <-- `release/x.y.z` and merge in when ready.
+- Write a Lobby post to inform VIP customers about the release, including the date when the VIP Code Analysis Bot will be updated (usually about 2 weeks after the VIPCS release).
 - Write an internal P2 post.
-- Open a PR to update the [Review Bot dependencies](https://github.com/Automattic/vip-go-ci/blob/master/tools-init.sh).
-
+- Open a PR to update the [VIP Code Analysis bot dependencies](https://github.com/Automattic/vip-go-ci/blob/master/tools-init.sh).

.github/ISSUE_TEMPLATE/bug_report.md

@@ -54,7 +54,7 @@ Use `php -v` and `composer show` to get versions.
 
 <!-- Add any other context about the problem here. -->
 
-## Tested Against `master` branch?
+## Tested Against `main` branch?
 
-- [ ] I have verified the issue still exists in the `master` branch of VIPCS.
+- [ ] I have verified the issue still exists in the `main` branch of VIPCS.
 - [ ] I have verified the issue still exists in the `develop` branch of VIPCS.

.github/ISSUE_TEMPLATE/release-template.md

@@ -13,11 +13,11 @@ assignees: GaryJones, rebeccahum
 
 PR for tracking changes for the X.Y.Z release. Target release date: DOW DD MMMM YYYY.
 
-- [ ] Scan WordPress (or just wp-admin folder) with prior version and compare results against new release for potential new bugs. 
+- [ ] Scan WordPress (or just wp-admin folder) with prior version and compare results against new release for potential new bugs.
 - [ ] Add change log for this release: PR #XXX
 - [ ] Double-check whether any dependencies need bumping.
 - [ ] Merge this PR.
-- [ ] Add signed release tag against `master`.
+- [ ] Add signed release tag against `main`.
 - [ ] Close the current milestone.
 - [ ] Open a new milestone for the next release.
 - [ ] If any open PRs/issues which were milestoned for this release do not make it into the release, update their milestone.

.github/workflows/quicktest.yml

@@ -1,10 +1,10 @@
 name: Quicktest
 
 on:
-  # Run on pushes, including merges, to all branches except `master`.
+  # Run on pushes, including merges, to all branches except `main`.
   push:
     branches-ignore:
-      - master
+      - main
     paths-ignore:
       - '**.md'
   # Allow manually triggering the workflow.

.github/workflows/test.yml

@@ -1,11 +1,11 @@
 name: Test
 
 on:
-  # Run on pushes to `master` and on all pull requests.
+  # Run on pushes to `main` and on all pull requests.
   # Prevent the "push" build from running when there are only irrelevant changes.
   push:
     branches:
-      - master
+      - main
     paths-ignore:
       - '**.md'
   pull_request:

CHANGELOG.md

@@ -4,6 +4,48 @@ 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).
 
+## [3.0.0] - 2023-09-05
+
+Props: @GaryJones, @jrfnl
+
+This release requires [WordPressCS 3.0.0](https://github.com/WordPress/WordPress-Coding-Standards/releases/tag/3.0.0). It is not compatible with WordPressCS 2.x. Users should read the [WordPressCS 3.0 upgrade guide for end-users](https://github.com/WordPress/WordPress-Coding-Standards/wiki/Upgrade-Guide-to-WordPressCS-3.0.0-for-ruleset-maintainers).
+
+Increases requirements for PHPCS from 3.7.1 to 3.7.2.
+
+The tagged releases branch is now `main` instead of `master`.
+
+### Added
+- [#777](https://github.com/Automattic/VIP-Coding-Standards/pull/777): 3.0: start using PHPCSUtils.
+- [#779](https://github.com/Automattic/VIP-Coding-Standards/pull/779): 3.0: support WordPressCS 3.0.
+
+## Changed
+- [#780](https://github.com/Automattic/VIP-Coding-Standards/pull/780): Performance/WPQueryParams: defer to the parent sniff.
+  - Two error codes changed:
+    - `WordPressVIPMinimum.Performance.WPQueryParams.PostNotIn` is now `WordPressVIPMinimum.Performance.WPQueryParams.PostNotIn_post__not_in`.
+    - `WordPressVIPMinimum.Performance.WPQueryParams.SuppressFiltersTrue` is now `WordPressVIPMinimum.Performance.WPQueryParams.SuppressFilters_suppress_filters`.
+
+### Removed
+- [#774](https://github.com/Automattic/VIP-Coding-Standards/pull/774): Performance/BatcacheWhitelistedParams: remove the sniff.
+- [#775](https://github.com/Automattic/VIP-Coding-Standards/pull/775): Compatibility/Zoninator: remove the sniff.
+- [#776](https://github.com/Automattic/VIP-Coding-Standards/pull/776): Variables/VariableAnalysis: remove the sniff.
+
+### Fixed
+- [#784](https://github.com/Automattic/VIP-Coding-Standards/pull/784): Performance/WPQueryParams: prevent false positives for `'exclude'` with `get_users()`.
+- [#788](https://github.com/Automattic/VIP-Coding-Standards/pull/788): Security/Mustache: prevent false positives on block editor templates.
+
+### Maintenance
+- [#778](https://github.com/Automattic/VIP-Coding-Standards/pull/778): CS: improve use statements.
+- [#781](https://github.com/Automattic/VIP-Coding-Standards/pull/781): Performance/NoPaging: add extra tests.
+- [#782](https://github.com/Automattic/VIP-Coding-Standards/pull/782): GH Actions: minor tweaks to the composer options used.
+- [#783](https://github.com/Automattic/VIP-Coding-Standards/pull/783): Hooks/AlwaysReturnInFilter: remove redundant condition.
+- [#785](https://github.com/Automattic/VIP-Coding-Standards/pull/785): Docs: remove redundant `@package` tags.
+- [#786](https://github.com/Automattic/VIP-Coding-Standards/pull/786): Add PHPStan to QA checks.
+- [#787](https://github.com/Automattic/VIP-Coding-Standards/pull/787): GH Actions: tweak the way the PHPCS/WPCS versions are set.
+- [#789](https://github.com/Automattic/VIP-Coding-Standards/pull/789): Updates related to branch rename from `master` to `main`.
+- [#790](https://github.com/Automattic/VIP-Coding-Standards/pull/790): PHPUnit: Use 7.5 schema.
+- [#791](https://github.com/Automattic/VIP-Coding-Standards/pull/791): Docs: Update `CONTRIBUTING.md`.
+
+
 ## [2.3.4] - 2023-07-05
 
 Props: kshaner, GaryJones, jrfnl, yolih
@@ -632,7 +674,7 @@ Initial release.
 
 Props: david-binda, pkevan.
 
-
+[3.0.0]: https://github.com/Automattic/VIP-Coding-Standards/compare/2.3.4...3.0.0
 [2.3.4]: https://github.com/Automattic/VIP-Coding-Standards/compare/2.3.3...2.3.4
 [2.3.3]: https://github.com/Automattic/VIP-Coding-Standards/compare/2.3.2...2.3.3
 [2.3.2]: https://github.com/Automattic/VIP-Coding-Standards/compare/2.3.1...2.3.2

phpunit.xml.dist

@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <phpunit
 	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-	xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/7.2/phpunit.xsd"
+	xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/7.5/phpunit.xsd"
 	backupGlobals="true"
 	bootstrap="./tests/bootstrap.php"
 	beStrictAboutTestsThatDoNotTestAnything="false"