Docs: Rewrite Bazel pages to clarify intended user, part 5

PiperOrigin-RevId: 362427806

site/docs/test-encyclopedia.html

@@ -30,10 +30,10 @@ <h2>Objective</h2>
 for and expected behavior of Bazel tests. It will also impose requirements on
 the test runner and the build system.
 
-Our intent is to help test authors avoid relying on unspecified
-behavior, and thus give the testing infrastructure more freedom to make
-implementation changes. We will also take the opportunity to tighten up some
-holes which currently allow many tests to pass despite not being
+The test environment specification helps test authors avoid relying on
+unspecified behavior, and thus gives the testing infrastructure more freedom
+to make implementation changes. The specification tightens up some
+holes that currently allow many tests to pass despite not being
 properly hermetic, deterministic, and reentrant.</p>
 
 <p>This page is intended to be both normative and authoritative. If

site/docs/toolchains.md

@@ -19,7 +19,7 @@ platform constraints.
 ## Motivation
 
 Let's first look at the problem toolchains are designed to solve. Suppose you
-were writing rules to support the "bar" programming language. Your `bar_binary`
+are writing rules to support the "bar" programming language. Your `bar_binary`
 rule would compile `*.bar` files using the `barc` compiler, a tool that itself
 is built as another target in your workspace. Since users who write `bar_binary`
 targets shouldn't have to specify a dependency on the compiler, you make it an
@@ -47,7 +47,7 @@ implementation function just like any other attribute:
 BarcInfo = provider(
     doc = "Information about how to invoke the barc compiler.",
     # In the real world, compiler_path and system_lib might hold File objects,
-    # but for simplicity we'll make them strings instead. arch_flags is a list
+    # but for simplicity they are strings for this example. arch_flags is a list
     # of strings.
     fields = ["compiler_path", "system_lib", "arch_flags"],
 )
@@ -88,7 +88,7 @@ bar_binary(
 )
 ```
 
-We can improve on this solution by using `select` to choose the `compiler`
+You can improve on this solution by using `select` to choose the `compiler`
 [based on the platform](configurable-attributes.html):
 
 ```python
@@ -134,7 +134,8 @@ need know the complete set of available platforms and toolchains.
 Under the toolchain framework, instead of having rules depend directly on tools,
 they instead depend on *toolchain types*. A toolchain type is a simple target
 that represents a class of tools that serve the same role for different
-platforms. For instance, we can declare a type that represents the bar compiler:
+platforms. For instance, you can declare a type that represents the bar
+compiler:
 
 ```python
 # By convention, toolchain_type targets are named "toolchain_type" and
@@ -179,7 +180,7 @@ def _bar_binary_impl(ctx):
 [`ToolchainInfo` provider](skylark/lib/platform_common.html#ToolchainInfo)
 of whatever target Bazel resolved the toolchain dependency to. The fields of the
 `ToolchainInfo` object are set by the underlying tool's rule; in the next
-section we'll define this rule such that there is a `barcinfo` field that wraps
+section, this rule is defined such that there is a `barcinfo` field that wraps
 a `BarcInfo` object.
 
 Bazel's procedure for resolving toolchains to targets is described
@@ -208,7 +209,7 @@ def _bar_aspect_impl(target, ctx):
 
 ## Defining toolchains
 
-To define some toolchains for a given toolchain type, we need three things:
+To define some toolchains for a given toolchain type, you need three things:
 
 1. A language-specific rule representing the kind of tool or tool suite. By
    convention this rule's name is suffixed with "\_toolchain".
@@ -253,11 +254,11 @@ The rule must return a `ToolchainInfo` provider, which becomes the object that
 the consuming rule retrieves using `ctx.toolchains` and the label of the
 toolchain type. `ToolchainInfo`, like `struct`, can hold arbitrary field-value
 pairs. The specification of exactly what fields are added to the `ToolchainInfo`
-should be clearly documented at the toolchain type. Here we have returned the
-values wrapped in a `BarcInfo` object in order to reuse the schema defined
-above; this style may be useful for validation and code reuse.
+should be clearly documented at the toolchain type. In this example, the values
+return wrapped in a `BarcInfo` object to reuse the schema defined above; this
+style may be useful for validation and code reuse.
 
-Now we can define targets for specific `barc` compilers.
+Now you can define targets for specific `barc` compilers.
 
 ```python
 bar_toolchain(
@@ -281,7 +282,7 @@ bar_toolchain(
 )
 ```
 
-Finally, we create `toolchain` definitions for the two `bar_toolchain` targets.
+Finally, you create `toolchain` definitions for the two `bar_toolchain` targets.
 These definitions link the language-specific targets to the toolchain type and
 provide the constraint information that tells Bazel when the toolchain is
 appropriate for a given platform.
@@ -326,7 +327,7 @@ for a real-world example.
 
 ## Registering and building with toolchains
 
-At this point all the building blocks are assembled, and we just need to make
+At this point all the building blocks are assembled, and you just need to make
 the toolchains available to Bazel's resolution procedure. This is done by
 registering the toolchain, either in a `WORKSPACE` file using
 `register_toolchains()`, or by passing the toolchains' labels on the command
@@ -336,7 +337,7 @@ line using the `--extra_toolchains` flag.
 register_toolchains(
     "//bar_tools:barc_linux_toolchain",
     "//bar_tools:barc_windows_toolchain",
-    # Target patterns are also permitted, so we could have also written:
+    # Target patterns are also permitted, so you could have also written:
     # "//bar_tools:all",
 )
 ```
@@ -413,7 +414,7 @@ The resolution steps are as follows.
    the list of available execution platforms is filtered to remove
    any that do not match the execution constraints.
 
-1. For each available execution platform, we associate each toolchain type with
+1. For each available execution platform, you associate each toolchain type with
    the first available toolchain, if any, that is compatible with this execution
    platform and the target platform.
 

site/docs/updating-bazel.md

@@ -36,7 +36,7 @@ Bazel backwards compatibility policy is designed to avoid _upgrade cliffs_: any
 project can be prepared for the next Bazel release without breaking
 compatibility with the current release.
 
-We recommend the following process for project migration:
+Follow this process for project migration:
 
 1. Assume that your project already works with a given Bazel release, say 0.26,
    and you want to prepare for the next release, say 0.27

site/docs/user-manual.html

@@ -78,8 +78,8 @@ <h4 id='flag--package_path'><code class='flag'>--package_path</code></h4>
   </li>
 </ol>
 <p>
-  If you use a non-default package path, we recommend that you specify
-  it in your <a href='guide.html#bazelrc'>Bazel configuration file</a> for
+  If you use a non-default package path, specify it in your
+  <a href='guide.html#bazelrc'>Bazel configuration file</a> for
   convenience.
 </p>
 <p>
@@ -1161,8 +1161,8 @@ <h4 id='flag--save_temps'><code class='flag'>--save_temps</code></h4>
   generated for the set of targets specified on the command line.
 </p>
 <p>
-  Note that our implementation of <code class='flag'>--save_temps</code> does not use the compiler's
-  <code>-save-temps</code> flag. Instead, we do two passes, one with <code>-S</code>
+  Note that the implementation of <code class='flag'>--save_temps</code> does not use the compiler's
+  <code>-save-temps</code> flag. Instead, there are two passes, one with <code>-S</code>
   and one with <code>-E</code>. A consequence of this is that if your build fails,
   Bazel may not yet have produced the ".i" or ".ii" and ".s" files.
   If you're trying to use <code class='flag'>--save_temps</code> to debug a failed compilation,
@@ -2150,20 +2150,17 @@ <h4>The <code>clean</code> command</h4>
 <p>
   The <code>clean</code> command is provided primarily as a means of
   reclaiming disk space for workspaces that are no longer needed.
-  However, we recognize that Bazel's incremental rebuilds might not be
-  perfect; <code>clean</code> may be used to recover a consistent
+  Bazel's incremental rebuilds may not be
+  perfect so <code>clean</code> can be used to recover a consistent
   state when problems arise.
 </p>
 <p>
-  Bazel's design is such that these problems are fixable; we consider
-  such bugs a high priority, and will do our best fix them. If you
-  ever find an incorrect incremental build, please file a bug report.
-  We encourage developers to get out of the habit of
-  using <code>clean</code> and into that of reporting bugs in the
-  tools.
+  Bazel's design is such that these problems are fixable and
+  these bugs are a high priority to be fixed. If you
+  ever find an incorrect incremental build, file a bug report, and report bugs in the tools
+  rather than using <code>clean</code>.
 </p>
 
-
 <h2 id='run'>Running executables</h2>
 <p>
   The <code>bazel run</code> command is similar to <code>bazel build</code>, except
@@ -2823,9 +2820,8 @@ <h4 id='flag--output_user_root'><code class='flag'>--output_user_root=<var>dir</
   overriden with <code class='flag'>--output_base</code>. The directory
   must either not exist or be owned by the calling user. In the past,
   this was allowed to point to a directory shared among various users
-  but it's not allowed any longer. (We can reconsider allowing this once
-  <a href='https://github.com/bazelbuild/bazel/issues/11100'>#11100</a>
-  is addressed.)
+  but it's not allowed any longer. This may be allowed once the following is addressed:
+  <a href='https://github.com/bazelbuild/bazel/issues/11100'>#11100</a>.
 </p>
 <p>
   If the <code class='flag'>--output_base</code> option is specified, it overrides
@@ -2939,7 +2935,7 @@ <h4 id='flag--batch'><code class='flag'>--batch</code></h4>
   <i>WARNING:</i> <code class='flag'>--batch</code> is sufficiently slower than standard
   client/server mode. Additionally it might not support all of the features and optimizations which
   are made possible by a persistent Bazel server. If you're using <code class='flag'>--batch</code>
-  for the purpose of build isolation, we recommend using the command option
+  for the purpose of build isolation, you should use the command option
   <code class='flag'>--nokeep_state_after_build</code>, which guarantees that no incremental
   in-memory state is kept between builds. In order to restart the Bazel server and JVM after a
   build, please explicitly do so using the "shutdown" command.

site/docs/windows.md

@@ -10,8 +10,8 @@ instructions, see [Install Bazel on Windows](install-windows.html).
 
 ## Known issues
 
-We mark Windows-related Bazel issues on GitHub with the "team-Windows"
-label. [You can see the open issues here.](https://github.com/bazelbuild/bazel/issues?q=is%3Aopen+is%3Aissue+label%3Ateam-Windows)
+Windows-related Bazel issues are marked with the "team-Windows"
+label on GitHub. [You can see the open issues here.](https://github.com/bazelbuild/bazel/issues?q=is%3Aopen+is%3Aissue+label%3Ateam-Windows)
 
 ## Best practices
 
@@ -52,10 +52,10 @@ build --enable_runfiles
 <a name="running-bazel-shells"></a>
 ### Running Bazel: MSYS2 shell vs. command prompt vs. PowerShell
 
-We recommend running Bazel from the command prompt (`cmd.exe`) or from
+**Recommendation:** Run Bazel from the command prompt (`cmd.exe`) or from
 PowerShell.
 
-As of 2020-01-15, we **do not recommend** running Bazel from `bash` -- either
+As of 2020-01-15, **do not** run Bazel from `bash` -- either
 from MSYS2 shell, or Git Bash, or Cygwin, or any other Bash variant. While Bazel
 may work for most use cases, some things are broken, like
 [interrupting the build with Ctrl+C from MSYS2](https://github.com/bazelbuild/bazel/issues/10573)).
@@ -115,9 +115,9 @@ rules that use `ctx.actions.run_shell()` and `ctx.resolve_command()`. This
 applies not only to rules in your project, but to rules in any of the external
 repositories your project depends on (even transitively).
 
-We may explore the option to use Windows Subsystem for Linux (WSL) to build
-these rules, but as of 2020-01-15 it is not a priority for the Bazel-on-Windows
-subteam.
+In the future, there may be an option to use Windows Subsystem for
+Linux (WSL) to build these rules, but currently it is not a priority for
+the Bazel-on-Windows subteam.
 
 ### Setting environment variables
 
@@ -215,8 +215,9 @@ example](https://github.com/bazelbuild/bazel/tree/master/examples/windows/dll).
 From 0.29.0, Bazel supports building with LLVM's MSVC-compatible compiler driver (`clang-cl.exe`).
 
 **Requirement**: To build with Clang, you have to install **both**
-[LLVM](http://releases.llvm.org/download.html) and Visual C++ Build tools, because although we use
-`clang-cl.exe` as compiler, we still need to link to Visual C++ libraries.
+[LLVM](http://releases.llvm.org/download.html) and Visual C++ Build tools,
+because although you use `clang-cl.exe` as compiler, you still need to link to
+Visual C++ libraries.
 
 Bazel can automatically detect LLVM installation on your system, or you can explicitly tell
 Bazel where LLVM is installed by `BAZEL_LLVM`.

site/docs/workspace-log.md

@@ -5,7 +5,7 @@ title: Finding non-hermetic behavior in WORKSPACE rules
 
 # Finding Non-Hermetic Behavior in WORKSPACE Rules
 
-In the following, we say that a host machine is the machine where Bazel runs.
+In the following, a host machine is the machine where Bazel runs.
 
 When using remote execution, the actual build and/or test steps are not
 happening on the host machine, but are instead sent off to the remote execution