From f79f7eef890a91ca1fd9ecfa51f9f5157003327e Mon Sep 17 00:00:00 2001
From: jrfnl <jrfnl@users.noreply.github.com>
Date: Sat, 27 Jul 2019 00:04:01 +0200
Subject: [PATCH] Ruleset: document which WP versions contain which polyfill

WP 5.3 will drop a number of polyfills.

To allow this ruleset to still be used by projects supporting older WP versions as well as newer WP versions, they will - for now - not be removed from the ruleset.
However, documenting what WP version introduced certain polyfills and where applicable in what version of WP they were removed, seems prudent.

Note: the JSON related polyfills will most likely also be removed in WP 5.3, but those changes haven't been committed yet.
---
 PHPCompatibilityWP/ruleset.xml | 23 +++++++++++++++++++++--
 1 file changed, 21 insertions(+), 2 deletions(-)

diff --git a/PHPCompatibilityWP/ruleset.xml b/PHPCompatibilityWP/ruleset.xml
index 88f1775..5676dd8 100644
--- a/PHPCompatibilityWP/ruleset.xml
+++ b/PHPCompatibilityWP/ruleset.xml
@@ -13,7 +13,20 @@
     -->
 
     <rule ref="PHPCompatibility">
-        <!-- Contained in /wp-includes/compat.php. -->
+        <!--
+        Contained in /wp-includes/compat.php.
+
+        History of the polyfills in WP:
+        * hash_hmac(): since WP 3.2.0.
+        * json_encode() and json_decode(): since unknown.
+        * hash_equals(): since WP 3.9.2.
+        * JSON_PRETTY_PRINT: since WP 4.1.0.
+        * json_last_error_msg(): since WP 4.4.0.
+        * JsonSerializable: since WP 4.4.0.
+        * array_replace_recursive(): since WP 4.5.3 up to 5.2.x. The polyfill was removed in WP 5.3.
+        * is_iterable(): since WP 4.9.6
+        * is_countable(): since WP 4.9.6
+        -->
         <exclude name="PHPCompatibility.FunctionUse.NewFunctions.hash_hmacFound"/>
         <exclude name="PHPCompatibility.FunctionUse.NewFunctions.json_encodeFound"/>
         <exclude name="PHPCompatibility.FunctionUse.NewFunctions.json_decodeFound"/>
@@ -25,7 +38,13 @@
         <exclude name="PHPCompatibility.FunctionUse.NewFunctions.is_iterableFound"/>
         <exclude name="PHPCompatibility.FunctionUse.NewFunctions.is_countableFound"/>
 
-        <!-- Contained in /wp-includes/spl-autoload-compat.php. -->
+        <!--
+        Contained in /wp-includes/spl-autoload-compat.php.
+
+        History of the polyfills in WP:
+        * spl_autoload_register(), spl_autoload_unregister() and spl_autoload_functions() were
+          introduced in WP 4.6.0 and available up to WP 5.2.x. The polyfills were removed in WP 5.3.
+        -->
         <exclude name="PHPCompatibility.FunctionUse.NewFunctions.spl_autoload_registerFound"/>
         <exclude name="PHPCompatibility.FunctionUse.NewFunctions.spl_autoload_unregisterFound"/>
         <exclude name="PHPCompatibility.FunctionUse.NewFunctions.spl_autoload_functionsFound"/>