Re: [PATCH v2 2/2] t0450: add allowlist for builtins with missing .adoc

[Patrick Steinhardt <ps@pks.im>]

On Fri, Aug 08, 2025 at 03:07:09PM -0700, Junio C Hamano wrote:
> Toon Claes <toon@iotcl.com> writes:
> 
> > Before we were silently skipping all builtins that don't have a matching
> > .adoc file. This is overly loose and might skip documentation files
> > when it shouldn't, for example when there was a typo in the filename.
> >
> > To ensure no new builtins are added without documentation, add an
> > allowlist: t0450/adoc-missing. In this file only builtin commands that
> > do *not* have a corresponding .adoc file shall be listed. If there is a
> > mismatch, fail the test. This should force future contributions to
> > either add an .adoc, or add the builtin name to the allowlist file.
> >
> > Signed-off-by: Toon Claes <toon@iotcl.com>
> > ---
> >  t/t0450-txt-doc-vs-help.sh | 8 +++++++-
> >  1 file changed, 7 insertions(+), 1 deletion(-)
> 
> Forgot to add something?

Indeed. Toon is currently out of office, so I had a look at what it
takes. The below patch is what I ended up with -- note that I also had
to reverse the `grep` condition to set the prereq in the else branch.

Let me know whether you're fine with just squashing these changes in or
whether I shall send another version.

Thanks!

Patrick

diff --git a/t/t0450-txt-doc-vs-help.sh b/t/t0450-txt-doc-vs-help.sh
index da2d0af5b0..e12e18f97f 100755
--- a/t/t0450-txt-doc-vs-help.sh
+++ b/t/t0450-txt-doc-vs-help.sh
@@ -112,10 +112,19 @@ do
 	adoc="$(builtin_to_adoc "$builtin")" &&
 	preq="$(echo BUILTIN_ADOC_$builtin | tr '[:lower:]-' '[:upper:]_')" &&
 
-	if test -f "$adoc"
+	# If and only if *.adoc is missing, builtin shall be listed in t0450/adoc-missing.
+	if grep -q "^$builtin$" "$TEST_DIRECTORY"/t0450/adoc-missing
 	then
+		test_expect_success "$builtin appropriately marked as not having .adoc" '
+			! test -f "$adoc"
+		'
+	else
 		test_set_prereq "$preq"
-	fi &&
+
+		test_expect_success "$builtin appropriately marked as having .adoc" '
+			test -f "$adoc"
+		'
+	fi
 
 	# *.adoc output assertions
 	test_expect_success "$preq" "$builtin *.adoc SYNOPSIS has dashed labels" '
diff --git a/t/t0450/adoc-missing b/t/t0450/adoc-missing
new file mode 100644
index 0000000000..1ec9f8dcf3
--- /dev/null
+++ b/t/t0450/adoc-missing
@@ -0,0 +1,9 @@
+checkout--worker
+merge-ours
+merge-recursive
+merge-recursive-ours
+merge-recursive-theirs
+merge-subtree
+pickaxe
+submodule--helper
+upload-archive--writer