Docs: Rewrite Bazel pages to clarify intended user, Part 4 PiperOrigin-RevId: 361612150
diff --git a/site/docs/query.html b/site/docs/query.html index 48ae8a7..8755d13 100644 --- a/site/docs/query.html +++ b/site/docs/query.html
@@ -121,11 +121,11 @@ "'a' + 'a'" # OK </pre> - <p>We chose this syntax so that quote marks aren't needed in most cases. + <p>This syntax doesn't need quote marks in most cases. The (unusual) <code>".*test rule"</code> example needs quotes: it starts with a period and contains a space. Quoting <code>"cc_library"</code> is unnecessary but harmless. - </p> + </p> <li><b>Punctuation</b>, such as parens <code>()</code>, period <code>.</code> and comma <code>,</code>, etc. Words containing @@ -144,13 +144,13 @@ datatype. </p> <p> - In some expressions, the partial order of the graph is - not interesting; In this case, we call the values - "sets". In cases where the partial order of elements - is significant, we call values "graphs". Note - that both terms refer to the same datatype, but merely emphasize - different aspects of it. + Set and graph refer to the same datatype, but emphasize different + aspects of it, for example: </p> +<ul> + <li><b>Set:</b> The partial order of the targets is not interesting.</li> + <li><b>Graph:</b> The partial order of targets is significant.</li> +</ul> <h3>Cycles in the dependency graph</h3> <p> @@ -330,7 +330,7 @@ </pre> <p> - We will examine each of the productions of this grammar in order. + The following sections describe each of the productions of this grammar in order. </p> <h3 id="target-patterns">Target patterns</h3> @@ -504,8 +504,8 @@ x intersect (y union z)</pre> <p> - (We strongly recommend that you use parentheses where there is - any danger of ambiguity in reading a query expression.) + **Recommendation:** Use parentheses where there is + any danger of ambiguity in reading a query expression. </p> <h3 id="set">Read targets from an external source: set</h3>
diff --git a/site/docs/remote-caching-debug.md b/site/docs/remote-caching-debug.md index 7b82d41..e1e8d36 100644 --- a/site/docs/remote-caching-debug.md +++ b/site/docs/remote-caching-debug.md
@@ -12,11 +12,7 @@ locally and is set up to utilize remote caching, and that you want to ensure that the remote cache is being effectively utilized. -For tips on how to check your cache hit rate and how to compare the execution -logs between two Bazel invocations, see [Debugging Remote Cache Hits for Remote -Execution](/remote-execution-caching-debug.html). Everything presented in that -guide also applies to remote caching with local execution. However, local -execution presents some additional challenges which we will discuss here. +For tips on how to check your cache hit rate and how to compare the execution logs between two Bazel invocations, see [Debugging Remote Cache Hits for Remote Execution](/remote-execution-caching-debug.html). Everything presented in that guide also applies to remote caching with local execution. However, local execution presents some additional challenges. ## Checking your cache hit rate
diff --git a/site/docs/remote-caching.md b/site/docs/remote-caching.md index 826af30..eb1d9d1 100644 --- a/site/docs/remote-caching.md +++ b/site/docs/remote-caching.md
@@ -309,9 +309,9 @@ **Input file modification during a build** When an input file is modified during a build, Bazel might upload invalid -results to the remote cache. We implemented a change detection that can be -enabled via the `--experimental_guard_against_concurrent_changes` flag. There -are no known issues and we expect to enable it by default in a future release. +results to the remote cache. You can enable a change detection with +the `--experimental_guard_against_concurrent_changes` flag. There +are no known issues and it will be enabled by default in a future release. See [issue #3360] for updates. Generally, avoid modifying source files during a build.
diff --git a/site/docs/remote-execution-caching-debug.md b/site/docs/remote-execution-caching-debug.md index 583fa04..567581f 100644 --- a/site/docs/remote-execution-caching-debug.md +++ b/site/docs/remote-execution-caching-debug.md
@@ -37,7 +37,7 @@ ### Ensure re-running the same build/test command produces cache hits 1. Run the build(s) and/or test(s) that you expect to populate the cache. The - first time a new build is run on a particular stack, we expect no remote + first time a new build is run on a particular stack, you can expect no remote cache hits. As part of remote execution, action results are stored in the cache and a subsequent run should pick them up.
diff --git a/site/docs/remote-execution-rules.md b/site/docs/remote-execution-rules.md index 2459596..a382f78 100644 --- a/site/docs/remote-execution-rules.md +++ b/site/docs/remote-execution-rules.md
@@ -144,7 +144,7 @@ To help find potential non-hermetic behavior you can use [Workspace rules log](/workspace-log.md). If an external dependency executes specific operations dependent on the host -platform, we recommend splitting those operations between `WORKSPACE` and build +platform, you should split those operations between `WORKSPACE` and build rules as follows: * **Platform inspection and dependency enumeration.** These operations are