Changes from [] that were left out of the

previous commit

Document and test how rules can run without the sandbox.

The only documentation about usable tags values was in a weird place,
along with duplicated information about flaky tests.

--
Change-Id: Ib98a0a5c582890512161ecf9f5d89c8e78d9ad68
Reviewed-on: https://bazel-review.googlesource.com/#/c/2220
MOS_MIGRATED_REVID=106858070

1 files changed, 43 insertions, 10 deletions

diff --git a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/tags.html b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/tags.html
index a004ece376..82cb9bd5e3 100644
--- a/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/tags.html
+++ b/src/main/java/com/google/devtools/build/docgen/templates/attributes/common/tags.html
@@ -1,22 +1,55 @@
+
 <p><code>List of arbitrary text tags.  Tags may be any valid string; default is the
 empty list.</code></p>
 
 <p>
-<i>Tags</i> can be used on any rule; but <i>tags</i> are most useful
-on test and <code>test_suite</code> rules.  Tags on non-test rules
-are only useful to humans and/or external programs.
-<i>Tags</i> are generally used to annotate a test's role in your debug
+<i>Tags</i> can be used on any rule. <i>Tags</i> on test and
+<code>test_suite</code> rules are useful for categorizing the tests. <i>Tags</i>
+on non-test rules are used to control sandboxed execution of
+<code>genrule</code>s and [Skylark](/docs/skylark/index.html) actions, and for
+parsing by humans and/or external tools.
+</p>
+<p>
+Bazel modifies the behavior of its sandboxing code if it finds the following
+keywords in the <code>tags</code> attribute of any test rule or
+<code>genrule</code>, or the keys of <code>execution_requirements</code> for
+any Skylark action.
+</p>
+<ul>
+  <li><code>local</code> keyword results in the action or test never being
+    run inside the [sandbox](/docs/bazel-user-manual.html#sandboxing).
+  </li>
+</ul>
+<p>
+<i>Tags</i> on tests are generally used to annotate a test's role in your debug
 and release process.  Typically, tags are most useful for C++ and
 Python tests, which
 lack any runtime annotation ability.  The use of tags and size elements
 gives flexibility in assembling suites of tests based around codebase
 check-in policy.
 </p>
-
 <p>
-A few tags have special meaning to the build tool, such as
-indicating that a particular test cannot be run remotely, for
-example. Consult
-the <a href='bazel-user-manual.html#tags_keywords'>Bazel
-documentation</a> for details.
+  Bazel modifies test running behavior if it finds the following keywords in the
+  <code>tags</code> attribute of the test rule:
 </p>
+<ul>
+  <li><code>exclusive</code> keyword will force test to be run in the
+    &quot;exclusive&quot; mode, ensuring that no other tests are running at the
+    same time. Such tests will be executed in serial fashion after all build
+    activity and non-exclusive tests have been completed.
+
+
+  </li>
+
+  <li><code>manual</code> keyword will force test to be ignored by all command
+    line wildcards (<code>...</code>, <code>:*</code>, <code>:all</code>, etc).
+    It will also be ignored by the <code>test_suite</code> rules that do not
+    mention this test explicitly. The only way
+    to run such test is to specify it explicitly on the command line.
+  </li>
+  <li><code>external</code> keyword will force test to be unconditionally
+    executed (regardless of <code class='flag'>--cache_test_results</code> value).
+  </li>
+
+
+</ul>