From 3f3ee05c128452ddb299c2f521a10c485b9de962 Mon Sep 17 00:00:00 2001
From: Zalathar <Zalathar@users.noreply.github.com>
Date: Sat, 4 May 2024 22:38:15 +1000
Subject: [PATCH] Document the `//@ unused-revision-names:` test header
---
src/tests/compiletest.md | 13 +++++++++++++
src/tests/headers.md | 2 ++
2 files changed, 15 insertions(+)
diff --git a/src/tests/compiletest.md b/src/tests/compiletest.md
index e57b50892..0f9cd0552 100644
--- a/src/tests/compiletest.md
+++ b/src/tests/compiletest.md
@@ -639,6 +639,19 @@ Following is classes of tests that support revisions:
- rustdoc UI tests
- incremental (these are special in that they inherently cannot be run in parallel)
+### Ignoring unused revision names
+
+Normally, revision names mentioned in other headers and error annotations must
+correspond to an actual revision declared in a `revisions` header. This is
+enforced by an `./x test tidy` check.
+
+If a revision name needs to be temporarily removed from the revision list for
+some reason, the above check can be suppressed by adding the revision name to
+an `//@ unused-revision-names:` header instead.
+
+Specifying an unused name of `*` (i.e. `//@ unused-revision-names: *`) will
+permit any unused revision name to be mentioned.
+
## Compare modes
Compiletest can be run in different modes, called _compare modes_, which can
diff --git a/src/tests/headers.md b/src/tests/headers.md
index 88a87181e..a59ffe6cc 100644
--- a/src/tests/headers.md
+++ b/src/tests/headers.md
@@ -94,6 +94,8 @@ found in [`header.rs`] from the compiletest source.
* `no-auto-check-cfg` — disable auto check-cfg (only for `--check-cfg` tests)
* `force-host` — build only for the host target
* [`revisions`](compiletest.md#revisions) — compile multiple times
+ * [`unused-revision-names`](compiletest.md#ignoring-unused-revision-names) -
+ suppress tidy checks for mentioning unknown revision names
* [`forbid-output`](compiletest.md#incremental-tests) — incremental cfail rejects output pattern
* [`should-ice`](compiletest.md#incremental-tests) — incremental cfail should ICE
* [`known-bug`](ui.md#known-bugs) — indicates that the test is