From 7d3bdbcfbe86eb37d665aba08c13a9101d35c0f7 Mon Sep 17 00:00:00 2001
From: nharmata <nharmata@google.com>
Date: Mon, 7 Jun 2021 14:33:39 -0700
Subject: [PATCH] Improve documentation of a "manual" string value in the
 `test_suite.tags` string list.

PiperOrigin-RevId: 378007236
---
 site/docs/guide.md                              | 11 +++++++----
 .../build/lib/rules/test/TestSuiteRule.java     | 17 +++++++++++------
 2 files changed, 18 insertions(+), 10 deletions(-)

diff --git a/site/docs/guide.md b/site/docs/guide.md
index ae773049c65654..61cfef892fac7c 100644
--- a/site/docs/guide.md
+++ b/site/docs/guide.md
@@ -263,10 +263,13 @@ that weren't subtracted. For example, if there were a target `//foo:all-apis`
 that among others depended on `//foo/bar:api`, then the latter would be built as
 part of building the former.
 
-Targets with `tags = ["manual"]` will not be included in wildcard target
-patterns (`...`, `:*`, `:all`, etc.). You should specify such test targets with
-explicit target patterns on the command line if you want Bazel to build/test
-them.
+Targets with `tags = ["manual"]` are not included in wildcard target patterns
+(`...`, `:*`, `:all`, etc.) when specified in commands like
+<code>bazel build</code> and <code>bazel test</code>; you should specify such
+test targets with explicit target patterns on the command line if you want Bazel
+to build/test them. In contrast, <code>bazel query</code> doesn't perform any
+such filtering automatically (that would defeat the purpose of
+<code>bazel query</code>).
 
 <a id="fetch"></a>
 ### Fetching external dependencies
diff --git a/src/main/java/com/google/devtools/build/lib/rules/test/TestSuiteRule.java b/src/main/java/com/google/devtools/build/lib/rules/test/TestSuiteRule.java
index 33b449453771be..ecd4e34cb32003 100644
--- a/src/main/java/com/google/devtools/build/lib/rules/test/TestSuiteRule.java
+++ b/src/main/java/com/google/devtools/build/lib/rules/test/TestSuiteRule.java
@@ -58,11 +58,13 @@ public RuleClass build(RuleClass.Builder builder, RuleDefinitionEnvironment env)
           tests still need to be legal (e.g. not blocked by visibility constraints).
         </p>
         <p>
-          The <code>manual</code> tag keyword is treated specially. It marks the
-          <code>test_suite</code> target as "manual" so that it will be ignored by the wildcard
-          expansion and automated testing facilities. It does not work as a filter on the set
-          of tests in the suite. So when the <code>manual</code> tag is used on a test_suite, test
-          rules do not have to be tagged as <code>manual</code> to be included in the test suite.
+          The <code>manual</code> tag keyword is treated differently than the above by the
+          "test_suite expansion" performed by the <code>blaze test</code> command on invocations
+          involving wildcard
+          <a href="https://docs.bazel.build/versions/master/guide.html#specifying-targets-to-build">target patterns</a>.
+          There, <code>test_suite</code> targets tagged "manual" are filtered out (and thus not
+          expanded). This behavior is consistent with how <code>blaze build</code> and
+          <code>blaze test</code> handle wildcard target patterns in general.
         </p>
         <p>
           Note that a test's <code>size</code> is considered a tag for the purpose of filtering.
@@ -120,7 +122,10 @@ public Metadata getMetadata() {
 <p>
 A <code>test_suite</code> defines a set of tests that are considered "useful" to humans. This
 allows projects to define sets of tests, such as "tests you must run before checkin", "our
-project's stress tests" or "all small tests."
+project's stress tests" or "all small tests." The <code>blaze test</code> command respects this sort
+of organization: For an invocation like <code>blaze test //some/test:suite</code>, Blaze first
+enumerates all test targets transitively included by the <code>//some/test:suite</code> target (we
+call this "test_suite expansion"), then Blaze builds and tests those targets.
 </p>
 
 <h4 id="test_suite_examples">Examples</h4>