From 8b92b76ceb0380da92fc2dc4896981908d126c67 Mon Sep 17 00:00:00 2001
From: Aaron Robertshaw <60436221+aaronrobertshaw@users.noreply.github.com>
Date: Wed, 20 Nov 2024 18:11:33 +1000
Subject: [PATCH] Add explanation of order importance to inline comments

---
 lib/compat/wordpress-6.8/blocks.php             | 7 +++++++
 packages/blocks/src/store/process-block-type.js | 7 +++++++
 2 files changed, 14 insertions(+)

diff --git a/lib/compat/wordpress-6.8/blocks.php b/lib/compat/wordpress-6.8/blocks.php
index 7f27608efe2e2b..64e3aef01244cc 100644
--- a/lib/compat/wordpress-6.8/blocks.php
+++ b/lib/compat/wordpress-6.8/blocks.php
@@ -101,6 +101,13 @@ function gutenberg_stabilize_experimental_block_supports( $args ) {
 		 * are defined in to determine the final value.
 		 *    - If config is an array, merge the arrays in their order of definition.
 		 *    - If config is not an array, use the value defined last.
+		 *
+		 * The reason for preferring the last defined key is that after filters
+		 * are applied, the last inserted key is likely the most up-to-date value.
+		 * We cannot determine with certainty which value was "last modified" so
+		 * the insertion order is the best guess. The extreme edge case of multiple
+		 * filters tweaking the same support property will become less over time as
+		 * extenders migrate existing blocks and plugins to stable keys.
 		 */
 		if ( $support !== $stable_support_key && isset( $args['supports'][ $stable_support_key ] ) ) {
 			$key_positions      = array_flip( array_keys( $args['supports'] ) );
diff --git a/packages/blocks/src/store/process-block-type.js b/packages/blocks/src/store/process-block-type.js
index c913da6f23136a..0d7b73daa1176a 100644
--- a/packages/blocks/src/store/process-block-type.js
+++ b/packages/blocks/src/store/process-block-type.js
@@ -166,6 +166,13 @@ function stabilizeSupports( rawSupports ) {
 		 * are defined in to determine the final value.
 		 *    - If config is an array, merge the arrays in their order of definition.
 		 *    - If config is not an array, use the value defined last.
+		 *
+		 * The reason for preferring the last defined key is that after filters
+		 * are applied, the last inserted key is likely the most up-to-date value.
+		 * We cannot determine with certainty which value was "last modified" so
+		 * the insertion order is the best guess. The extreme edge case of multiple
+		 * filters tweaking the same support property will become less over time as
+		 * extenders migrate existing blocks and plugins to stable keys.
 		 */
 		if (
 			support !== stableSupportKey &&