From d7388b594d6fcb71d3c80d8c6e94768000502cf7 Mon Sep 17 00:00:00 2001
From: Sergey Biryukov <sergeybiryukov@git.wordpress.org>
Date: Sat, 23 Sep 2023 10:56:24 +0000
Subject: [PATCH] Coding Standards: Improve organization of the
 PHPCompatibility ruleset.

This commit:
* Adds section headers to the ruleset file.
* Organizes all directives in their respective sections.

No functional changes.

Props jrf.
See #58831.

git-svn-id: https://develop.svn.wordpress.org/trunk@56666 602fd350-edb4-49c9-b593-d223f7449a82
---
 phpcompat.xml.dist | 42 +++++++++++++++++++++++++++++++++++-------
 1 file changed, 35 insertions(+), 7 deletions(-)

diff --git a/phpcompat.xml.dist b/phpcompat.xml.dist
index ab58eb44c5..e5b5f62e6a 100644
--- a/phpcompat.xml.dist
+++ b/phpcompat.xml.dist
@@ -2,10 +2,12 @@
 <ruleset name="WordPress PHP Compatibility">
 	<description>Apply PHP compatibility checks to all WordPress Core files</description>
 
-	<rule ref="PHPCompatibilityWP"/>
-
-	<!-- WordPress Core currently supports PHP 7.0+. -->
-	<config name="testVersion" value="7.0-"/>
+	<!--
+	#############################################################################
+	COMMAND LINE ARGUMENTS
+	https://github.com/squizlabs/PHP_CodeSniffer/wiki/Annotated-Ruleset
+	#############################################################################
+	-->
 
 	<!-- Only scan PHP files. -->
 	<arg name="extensions" value="php"/>
@@ -28,6 +30,13 @@
 	<!-- Show sniff codes in all reports. -->
 	<arg value="ps"/>
 
+	<!--
+	#############################################################################
+	FILE SELECTION
+	Set which files will be subject to the scans executed using this ruleset.
+	#############################################################################
+	-->
+
 	<!-- For now, only the files in src are scanned. -->
 	<file>./src/</file>
 
@@ -40,13 +49,13 @@
 	-->
 	<exclude-pattern>/vendor/*</exclude-pattern>
 
-	<!-- Must-Use plugins. -->
+	<!-- Exclude Must-Use plugins. -->
 	<exclude-pattern>/src/wp-content/mu-plugins/*</exclude-pattern>
 
-	<!-- Plugins. -->
+	<!-- Exclude plugins. -->
 	<exclude-pattern>/src/wp-content/plugins/*</exclude-pattern>
 
-	<!-- Themes except the twenty* themes. -->
+	<!-- Exclude themes except the twenty* themes. -->
 	<exclude-pattern>/src/wp-content/themes/(?!twenty)*</exclude-pattern>
 
 	<!--
@@ -55,6 +64,24 @@
 	-->
 	<exclude-pattern>src/wp-includes/sodium_compat/lib/php72compat_const\.php$</exclude-pattern>
 
+	<!--
+	#############################################################################
+	SET UP THE RULESET
+	#############################################################################
+	-->
+
+	<rule ref="PHPCompatibilityWP"/>
+
+	<!-- WordPress Core currently supports PHP 7.0+. -->
+	<config name="testVersion" value="7.0-"/>
+
+	<!--
+	#############################################################################
+	SELECTIVE EXCLUSIONS
+	Exclude specific files for specific sniffs and/or exclude sub-groups in sniffs.
+	#############################################################################
+	-->
+
 	<rule ref="PHPCompatibility.FunctionUse.NewFunctions.sodium_crypto_sign_keypair_from_secretkey_and_publickeyFound">
 		<exclude-pattern>/sodium_compat/src/Compat\.php$</exclude-pattern>
 	</rule>
@@ -81,4 +108,5 @@
 	<rule ref="PHPCompatibility.FunctionUse.RemovedFunctions.mcrypt_create_ivDeprecatedRemoved">
 		<exclude-pattern>/random_compat/random_bytes_mcrypt\.php$</exclude-pattern>
 	</rule>
+
 </ruleset>