Docs: Rewrite Bazel pages to clarify intended user
PiperOrigin-RevId: 359812571
diff --git a/site/docs/android-instrumentation-test.md b/site/docs/android-instrumentation-test.md
index dd65f54..0bf5c4a 100644
--- a/site/docs/android-instrumentation-test.md
+++ b/site/docs/android-instrumentation-test.md
@@ -213,9 +213,9 @@
## Maven dependencies
-For managing dependencies on Maven artifacts from repositories like [Google
+For managing dependencies on Maven artifacts from repositories, such as [Google
Maven](https://maven.google.com) or [Maven Central](https://central.maven.org),
-we recommend using a Maven resolver like
+you should use a Maven resolver, such as
[rules_jvm_external](https://github.com/bazelbuild/rules_jvm_external).
The rest of this page shows how to use `rules_jvm_external` to
@@ -267,8 +267,8 @@
bazel query 'filter("x86_qemu2$", kind(android_device, @android_test_support//tools/android/emulated_devices/...:*))'
```
-Bazel currently supports x86-based emulators only. For better performance, we
-also recommend using `QEMU2` `android_device` targets instead of `QEMU` ones.
+Bazel currently supports x86-based emulators only. For better performance, use
+`QEMU2` `android_device` targets instead of `QEMU` ones.
## Running tests
diff --git a/site/docs/android-ndk.md b/site/docs/android-ndk.md
index abdf8a9..c7baa2a 100644
--- a/site/docs/android-ndk.md
+++ b/site/docs/android-ndk.md
@@ -106,7 +106,7 @@
This example is available in the [Bazel examples
repository](https://github.com/bazelbuild/examples/tree/master/android/ndk).
-In the `BUILD.bazel` file, we define three targets with the `android_binary`,
+In the `BUILD.bazel` file, three targets are defined with the `android_binary`,
`android_library` and `cc_library` rules.
The `android_binary` top-level target builds the APK.
@@ -376,12 +376,12 @@
--host_crosstool_top=@bazel_tools//tools/cpp:toolchain
```
-Here, we specify that top-level `cc_library` and `cc_binary` targets are built
+In this example, the top-level `cc_library` and `cc_binary` targets are built
using the NDK toolchain. However, this causes Bazel's own host tools to be built
with the NDK toolchain (and thus for Android), because the host toolchain is
-copied from the target toolchain. To work around this, we specify the value of
-`--host_crosstool_top` to be `@bazel_tools//tools/cpp:toolchain` to explicitly
-set the host's C++ toolchain.
+copied from the target toolchain. To work around this, specify the value of
+`--host_crosstool_top` to be `@bazel_tools//tools/cpp:toolchain` to
+explicitly set the host's C++ toolchain.
With this approach, the entire build tree is affected.
diff --git a/site/docs/aquery.html b/site/docs/aquery.html
index 02294fd..662f99e 100644
--- a/site/docs/aquery.html
+++ b/site/docs/aquery.html
@@ -12,7 +12,7 @@
</p>
<p>
- <code>aquery</code> is useful when we are interested in the properties of the Actions/Artifacts
+ <code>aquery</code> is useful when you are interested in the properties of the Actions/Artifacts
generated from the Configured Target Graph. For example, the actual commands run
and their inputs/outputs/mnemonics.
</p>
@@ -305,7 +305,7 @@
<p><code class='flag'>--before, --after</code>: The aquery output files to be compared</p>
<p>
<code class='flag'>--input_type=(proto|text_proto), default=proto</code>: the format of the input
- files. We currently support <code>proto</code> and <code>textproto</code> aquery output.
+ files. Support is provided for <code>proto</code> and <code>textproto</code> aquery output.
</p>
<p>
<code class='flag'>--attrs=(cmdline|inputs), default=cmdline</code>: the attributes of actions
@@ -382,7 +382,7 @@
<a href="https://source.bazel.build/bazel/+/master:src/main/java/com/google/devtools/build/lib/actions/Actions.java;l=241;drc=003b8734036a07b496012730964ac220f486b61f">simply considered as one</a> and only executed once.
However, aquery operates on the pre-execution, post-analysis action graph, and hence treats these
like separate actions whose output Artifacts have the exact same <code>execPath</code>. As a result,
- we'll have equivalent Artifacts appearing duplicated.
+ equivalent Artifacts appear duplicated.
</p>
<p>
The list of aquery issues/planned features can be found on
diff --git a/site/docs/backward-compatibility.md b/site/docs/backward-compatibility.md
index 240da27..6161974 100644
--- a/site/docs/backward-compatibility.md
+++ b/site/docs/backward-compatibility.md
@@ -24,10 +24,9 @@
1. Every breaking change is guarded with an `--incompatible_*` flag.
1. Newly introduced incompatible flags default to off.
-1. For every `--incompatible_*` flag we have a GitHub issue that explains
+1. For every `--incompatible_*` flag, there is a GitHub issue that explains
the change in behavior and provides a migration recipe.
1. The migration window is at least one release long and is set by the author of the incompatible change.
-1. We announce what set of flags we intend to flip with the next release one release in advance.
1. APIs and behavior guarded by an `--experimental_*` flag can change at any time.
1. Users should never run their production builds with `--experimental_*` or `--incompatible_*` flags.
@@ -41,8 +40,9 @@
## What is stable functionality?
-In general, if an API or a behavior is available in Bazel without
-`--experimental_...` flag, we consider it a stable, supported feature.
+In general, APIs or behaviors without `--experimental_...` flags are considered
+stable, supported features in Bazel.
+
This includes:
* Starlark language and APIs
@@ -52,20 +52,20 @@
## Incompatible changes and migration recipes
-When we introduce an incompatible change, we try to make it easier for Bazel
-users to update their code. We do this by means of _migration windows_ and
-_migration recipes_.
+When a release contains an incompatible change, the Bazel team provides
+_migration windows_ and _migration recipes_ to make it easier for Bazel users
+to update their code.
Migration window is one or more release of Bazel during which a migration from
old functionality to new functionality is possible, according to a migration
recipe.
-During the migration window, both the old functionality and the new functionality
-are available in the Bazel release. For every incompatible change, we provide
-a _migration recipe_ that allows updating the user code (`BUILD` and `.bzl` files,
-as well as any Bazel usage in scripts, usage of Bazel API and so on) in such a
-way that **it works simultaneously without any flags with old and new
-functionality**.
+During the migration window, both the old and new functionality
+are available in the Bazel release. For every incompatible change, a
+_migration recipe_ is provided that allows updating the user code
+(`BUILD` and `.bzl` files, as well as any Bazel usage in scripts,
+usage of Bazel API, and so on) in such a way that **it works simultaneously
+without any flags with old and new functionality**.
In other words, during a migration window for an incompatible change `foo`:
diff --git a/site/docs/bazel-and-cpp.md b/site/docs/bazel-and-cpp.md
index 2f3330d6..11ce1e5 100644
--- a/site/docs/bazel-and-cpp.md
+++ b/site/docs/bazel-and-cpp.md
@@ -32,8 +32,8 @@
* Each BUILD file should contain one [`cc_library`](be/c-cpp.html#cc_library)
rule target per compilation unit in the directory.
-* We recommend that you granularize your C++ libraries as much as possible to
- maximize incrementality and parallelize the build.
+* You should granularize your C++ libraries as much as
+ possible to maximize incrementality and parallelize the build.
* If there is a single source file in `srcs`, name the library the same as
that C++ file's name. This library should contain C++ file(s), any matching
diff --git a/site/docs/build-javascript.md b/site/docs/build-javascript.md
index 012cbda..f5e504c 100644
--- a/site/docs/build-javascript.md
+++ b/site/docs/build-javascript.md
@@ -136,8 +136,8 @@
```
then add scripts to your `package.json` that run Buildifier.
-We've selected a set of enabled warnings here, you could add and remove from
-this list.
+Here is a set of enabled warnings you could add and remove from
+this list:
```json
"scripts": {
@@ -177,8 +177,8 @@
**Tip:** You can try out the `ts_library` rule by running bazel build src in
the [sample project](https://github.com/alexeagle/angular-bazel-example/wiki).
-**Note:** We recommend standardizing your TypeScript settings into a single
-`tsconfig.json` file or as few `tsconfig.json` files as possible.
+**Recommendation:** Standardize your TypeScript settings into
+a single `tsconfig.json` file or as few `tsconfig.json` files as possible.
Note the following:
diff --git a/site/docs/build-ref.html b/site/docs/build-ref.html
index ddb99fc..6bc3efc 100644
--- a/site/docs/build-ref.html
+++ b/site/docs/build-ref.html
@@ -316,7 +316,7 @@
</p>
<p>While it is common to use <code>/</code> in the name of a file
- target, we recommend that you avoid the use of <code>/</code> in the
+ target, it is recommended that you avoid the use of <code>/</code> in the
names of rules. Especially when the shorthand form of a label is
used, it may confuse the reader. The
label <code>//foo/bar/wiz</code> is always a shorthand
@@ -436,8 +436,8 @@
<p>
The previous section described packages, targets and labels, and the
- build dependency graph abstractly. In this section, we'll look at
- the concrete syntax used to define a package.
+ build dependency graph abstractly. This section describes the
+ concrete syntax used to define a package.
</p>
<p>
@@ -608,7 +608,7 @@
<code>B</code> if <code>B</code> is needed by <code>A</code> at
build or execution time. The <i>depends upon</i> relation induces a
<a href="https://en.wikipedia.org/wiki/Directed_acyclic_graph">Directed
- Acyclic Graph</a> (DAG) over targets, and we call this a
+ Acyclic Graph</a> (DAG) over targets, and it is called a
<em>dependency graph</em>.
A target's <em>direct</em> dependencies are those other targets
@@ -646,7 +646,7 @@
For correct builds, the graph of actual dependencies <i>A</i> must
be a subgraph of the graph of declared dependencies <i>D</i>. That
is, every pair of directly-connected nodes <code>x --> y</code>
- in <i>A</i> must also be directly connected in <i>D</i>. We say
+ in <i>A</i> must also be directly connected in <i>D</i>. It can be said that
<i>D</i> is an <em>overapproximation</em> of <i>A</i>.
</p>
@@ -893,8 +893,8 @@
<p>A build target might need some data files to run correctly. These
data files aren't source code: they don't affect how the target is
built. For example, a unit test might compare a function's output
- to the contents of a file. When we build the unit test, we
- don't need the file; but we do need it when we run the test. The
+ to the contents of a file. When you build the unit test you
+ don't need the file, but you do need it when you run the test. The
same applies to tools that are launched during execution.
<p>The build system runs tests in an isolated directory where only files
diff --git a/site/docs/cc-toolchain-config-reference.md b/site/docs/cc-toolchain-config-reference.md
index 2481f90..c6b6078 100644
--- a/site/docs/cc-toolchain-config-reference.md
+++ b/site/docs/cc-toolchain-config-reference.md
@@ -416,7 +416,7 @@
The last two attributes are redundant against the corresponding attributes on
features and are included because some Bazel actions require certain flags or
-environment variables and we want to avoid unnecessary `action_config`+`feature`
+environment variables and the goal is to avoid unnecessary `action_config`+`feature`
pairs. Typically, sharing a single feature across multiple `action_config`s is
preferred.
@@ -460,7 +460,7 @@
by iterating through the `tools` attribute on an `action_config` until a tool
with a `with_feature` set matching the feature configuration is found
(see [Feature relationships](#feature-relationships) earlier on this page
-for more information). We recommend that you end your tool lists with a default
+for more information). You should end your tool lists with a default
tool that corresponds to an empty feature configuration.
### Example usage
diff --git a/site/docs/configurable-attributes.md b/site/docs/configurable-attributes.md
index 275fbb8a..def638f 100644
--- a/site/docs/configurable-attributes.md
+++ b/site/docs/configurable-attributes.md
@@ -332,7 +332,7 @@
allowing those `config_setting`s to match in `select()` expressions.
For example, in order to set the `srcs` attribute of `my_rocks` to `calcite.sh`,
-we can simply run
+you can simply run
```sh
bazel build //my_app:my_rocks --platforms=//myapp:marble_platform
@@ -773,7 +773,7 @@
ERROR: error loading package 'myapp': Package 'myapp' contains errors.
```
-Building succeeds when we comment out `sad_macro`:
+Building succeeds when you comment out `sad_macro`:
```sh
# Comment out sad_macro so it doesn't mess up the build.
