From 1b3a59d9987bec08db9cec85562dae016e586e11 Mon Sep 17 00:00:00 2001
From: Miguel Fonseca <miguelcsf@gmail.com>
Date: Thu, 8 Jun 2023 16:03:49 +0300
Subject: [PATCH 1/3] Add script to compile usage of experimental APIs

---
 bin/list-experimental-api-matches.sh | 48 ++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)
 create mode 100755 bin/list-experimental-api-matches.sh

diff --git a/bin/list-experimental-api-matches.sh b/bin/list-experimental-api-matches.sh
new file mode 100755
index 00000000000000..273615b4bcc695
--- /dev/null
+++ b/bin/list-experimental-api-matches.sh
@@ -0,0 +1,48 @@
+#!/bin/sh
+
+# POSIX: prefer standard grep over rg. Git is assumed present (ls-files), but
+# could be replaced with find.
+grep_experimental_apis() {
+	git ls-files packages/* lib \
+		| grep -E '\.(js|ts|jsx|tsx|php)$' \
+		| grep -v __tests__ \
+		| xargs grep -Eo '__experimental\w+'
+}
+
+# For each line as `<filepath>:<match>`, rewrite as `<package> <match>`.
+namespace() {
+	awk -F: '
+		{ print module($1), $2 }
+		function module(path) {
+			n = split(path, parts, "/")
+			if (parts[1] == "lib") return "lib"
+			return parts[1] "/" parts[2]
+		}'
+}
+
+# Like uniq, but applied across packages: if `__experimentalFoo` appears in
+# packages A and B, only keep the occurrence under A.
+compact() {
+	sort | uniq | awk '{
+		if (known_api[$2]) next
+		known_api[$2] = 1
+		print
+	}'
+}
+
+# Output a heading for each package and a link for each experimental API.
+format() {
+	awk '{
+		if (prev_dir != $1) {
+			if (NR > 1) print ""
+			printf "## `%s`\n", $1
+			prev_dir = $1
+		}
+		printf "[`%s`](/WordPress/gutenberg/search?q=%s)\n", $2, $2
+	}'
+}
+
+grep_experimental_apis \
+	| namespace \
+	| compact \
+	| format

From c896c86123acd581256fb10c52be0d449f84acd2 Mon Sep 17 00:00:00 2001
From: Miguel Fonseca <miguelcsf@gmail.com>
Date: Sat, 10 Jun 2023 11:14:59 +0300
Subject: [PATCH 2/3] Ensure script is run from root directory

---
 bin/list-experimental-api-matches.sh | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/bin/list-experimental-api-matches.sh b/bin/list-experimental-api-matches.sh
index 273615b4bcc695..9dd25adffcb193 100755
--- a/bin/list-experimental-api-matches.sh
+++ b/bin/list-experimental-api-matches.sh
@@ -1,5 +1,12 @@
 #!/bin/sh
 
+# Exit if any command fails.
+set -e
+
+# Change to the root directory.
+cd "$(dirname "$0")"
+cd ..
+
 # POSIX: prefer standard grep over rg. Git is assumed present (ls-files), but
 # could be replaced with find.
 grep_experimental_apis() {

From c7a4ebb7a15b7d548b84e46ac10a33a6e16eb13a Mon Sep 17 00:00:00 2001
From: Miguel Fonseca <miguelcsf@gmail.com>
Date: Sat, 10 Jun 2023 11:23:41 +0300
Subject: [PATCH 3/3] Add top-level comment explaining the script

---
 bin/list-experimental-api-matches.sh | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/bin/list-experimental-api-matches.sh b/bin/list-experimental-api-matches.sh
index 9dd25adffcb193..156464c4e7375e 100755
--- a/bin/list-experimental-api-matches.sh
+++ b/bin/list-experimental-api-matches.sh
@@ -1,5 +1,15 @@
 #!/bin/sh
 
+# Generate a Markdown-formatted list of experimental APIs found across our
+# packages and lib, providing GitHub search links for each match.
+#
+# Experimental APIs must be regularly audited, particularly in the context of
+# major WordPress releases. This script allows release leads to generate a list
+# to share in release issues.
+#
+# @see example audit issue for WordPress 6.2:
+# https://github.com/WordPress/gutenberg/issues/47196
+
 # Exit if any command fails.
 set -e