bazel-contrib · bazel-docs-pull-requestor · Aug 12, 2026
diff --git a/about/faq.mdx b/about/faq.mdx
@@ -155,7 +155,7 @@ For other IDEs, check out the [blog post](https://blog.bazel.build/2016/06/10/id
 
 Bazel returns a non-zero exit code if the build or test invocation fails, and this should be enough for basic CI integration. Since Bazel does not need clean builds for correctness, the CI system should not be configured to clean before starting a build/test run.
 
-Further details on exit codes are in the [Scripts guide](/run/scripts#exit-codes).
+Further details on exit codes are in the [User Manual](/docs/user-manual).
 
 ## Can I use Bazel for my INSERT LANGUAGE HERE project?
 

diff --git a/configure/coverage.mdx b/configure/coverage.mdx
@@ -13,7 +13,9 @@ This page documents the general process for creating and viewing
 coverage reports, and also features some language-specific notes for
 languages whose configuration is well-known. It is best read by first
 reading [the general section](#creating-a-coverage-report), and then
-reading about the requirements for a specific language.
+reading about the requirements for a specific language. Note also the
+[remote execution section](#remote-execution), which requires some
+additional considerations.
 
 While a lot of customization is possible, this document focuses on
 producing and consuming [`lcov`][lcov] reports, which is currently the
@@ -83,6 +85,32 @@ To view the result, simply open the `index.html` file produced in the
 For further help and information around the `genhtml` tool, or the
 `lcov` coverage format, see [the lcov project][lcov].
 
+## Remote execution {#remote-execution}
+
+Running with remote test execution currently has a few caveats:
+
+- The report combination action cannot yet run remotely. This is
+  because Bazel does not consider the coverage output files as part of
+  its graph (see [this issue][remote_report_issue]), and can therefore
+  not correctly treat them as inputs to the combination action. To
+  work around this, use `--strategy=CoverageReport=local`.
+  - Note: It may be necessary to specify something like
+    `--strategy=CoverageReport=local,remote` instead, if Bazel is set
+    up to try `local,remote`, due to how Bazel resolves strategies.
+- `--remote_download_minimal` and similar flags can also not be used
+  as a consequence of the former.
+- Bazel will currently fail to create coverage information if tests
+  have been cached previously. To work around this,
+  `--nocache_test_results` can be set specifically for coverage runs,
+  although this of course incurs a heavy cost in terms of test times.
+- `--experimental_split_coverage_postprocessing` and
+  `--experimental_fetch_all_coverage_outputs`
+  - Usually coverage is run as part of the test action, and so by
+    default, we don't get all coverage back as outputs of the remote
+    execution by default. These flags override the default and obtain
+    the coverage data. See [this issue][split_coverage_issue] for more
+    details.
+
 ## Language-specific configuration
 
 ### C++
@@ -116,3 +144,5 @@ for additional steps needed to enable coverage support in Python.
 
 [lcov]: https://github.com/linux-test-project/lcov
 [bazel_toolchains]: https://github.com/bazelbuild/bazel-toolchains
+[remote_report_issue]: https://github.com/bazelbuild/bazel/issues/4685
+[split_coverage_issue]: https://github.com/bazelbuild/bazel/issues/4685
diff --git a/contribute/codebase.mdx b/contribute/codebase.mdx
@@ -260,7 +260,7 @@ on Windows, where file names are case-insensitive.
 
 Packages are independent of each other: changes to the `BUILD` file of a package
 cannot cause other packages to change. The addition or removal of `BUILD` files
-_can_ change other packages, since recursive globs stop at package boundaries
+_can _change other packages, since recursive globs stop at package boundaries
 and thus the presence of a `BUILD` file stops the recursion.
 
 The evaluation of a `BUILD` file is called "package loading". It's implemented
@@ -305,7 +305,7 @@ Packages are composed of targets, which have the following types:
     Bazel parlance, we call them _artifacts_ (discussed elsewhere). Not all
     files created during the build are targets; it's common for an output of
     Bazel not to have an associated label.
-2.  **Rules:** these describe steps to derive their outputs from their inputs. They
+2.  **Rules:** these describe steps to derive its outputs from its inputs. They
     are generally associated with a programming language (such as `cc_library`,
     `java_library` or `py_library`), but there are some language-agnostic ones
     (such as `genrule` or `filegroup`)
@@ -353,7 +353,7 @@ of that type.
 
 The evaluation framework underlying Bazel is called Skyframe. Its model is that
 everything that needs to be built during a build is organized into a directed
-acyclic graph with edges pointing from any piece of data to its dependencies,
+acyclic graph with edges pointing from any pieces of data to its dependencies,
 that is, other pieces of data that need to be known to construct it.
 
 The nodes in the graph are called `SkyValue`s and their names are called
@@ -398,7 +398,7 @@ around this issue by:
     limit the number of restarts.
 2.  Breaking up a `SkyValue` into separate pieces computed by different
     `SkyFunction`s, so that they can be computed and cached independently. This
-    should be done strategically, since it has the potential to increase memory
+    should be done strategically, since it has the potential to increases memory
     usage.
 3.  Storing state between restarts, either using
     `SkyFunction.Environment.getState()`, or keeping an ad hoc static cache
@@ -414,7 +414,7 @@ around this issue by:
 
 [statemachine_example]: https://developers.google.com/devsite/reference/markdown/links#reference_links
 
-Fundamentally, Bazel needs these types of workarounds because hundreds of
+Fundamentally, Bazel need these types of workarounds because hundreds of
 thousands of in-flight Skyframe nodes is common, and Java's support of
 lightweight threads [does not outperform][virtual_threads] the
 `StateMachine` implementation as of 2023.
@@ -526,9 +526,9 @@ affects test targets (we have plans to "trim" configurations so that this is
 not the case, but it's not ready yet).
 
 When a rule implementation needs part of the configuration, it needs to declare
-it in its definition using `RuleClass.Builder.requiresConfigurationFragments()`.
-This is both to avoid mistakes (such as Python rules using the Java fragment) and
-to facilitate configuration trimming so that if Python options change, C++
+it in its definition using `RuleClass.Builder.requiresConfigurationFragments()`
+. This is both to avoid mistakes (such as Python rules using the Java fragment) and
+to facilitate configuration trimming so that such as if Python options change, C++
 targets don't need to be re-analyzed.
 
 The configuration of a rule is not necessarily the same as that of its "parent"
@@ -559,7 +559,7 @@ Configuration transitions can also be implemented in Starlark (documentation
 
 ### Transitive info providers {#transitive-info-providers}
 
-Transitive info providers are a way (and the _only_ way) for configured targets
+Transitive info providers are a way (and the _only _way) for configured targets
 to learn things about other configured targets that they depend on, and the only
 way to tell things about themselves to other configured targets that depend on
 them. The reason why "transitive" is in their name is that this is usually some
@@ -713,13 +713,13 @@ The concept of _toolchain_ comes from the fact that depending on what platforms
 the build is running on and what platforms are targeted, one may need to use
 different compilers; for example, a particular C++ toolchain may run on a
 specific OS and be able to target some other OSes. Bazel must determine the C++
-compiler that is used based on the set execution and target platforms
+compiler that is used based on the set execution and target platform
 (documentation for toolchains
 [here](/extending/toolchains)).
 
 In order to do this, toolchains are annotated with the set of execution and
 target platform constraints they support. In order to do this, the definition of
-a toolchain is split into two parts:
+a toolchain are split into two parts:
 
 1.  A `toolchain()` rule that describes the set of execution and target
     constraints a toolchain supports and tells what kind (such as C++ or Java) of
@@ -895,7 +895,7 @@ In order to get around this problem, we came up with the concept of a
 `NestedSet`. It's a data structure that is composed of other `NestedSet`
 instances and some members of its own, thereby forming a directed acyclic graph
 of sets. They are immutable and their members can be iterated over. We define
-multiple iteration orders (`NestedSet.Order`): preorder, postorder, topological
+multiple iteration order (`NestedSet.Order`): preorder, postorder, topological
 (a node always comes after its ancestors) and "don't care, but it should be the
 same each time".
 
@@ -1062,7 +1062,7 @@ the set of inputs of an action come in two forms:
 *   An action may discover new inputs before its execution or decide that some
     of its inputs are not actually necessary. The canonical example is C++,
     where it's better to make an educated guess about what header files a C++
-    file uses from its transitive closure so that we don't need to send every
+    file uses from its transitive closure so that we don't heed to send every
     file to remote executors; therefore, we have an option not to register every
     header file as an "input", but scan the source file for transitively
     included headers and only mark those header files as inputs that are
@@ -1147,7 +1147,7 @@ More information about strategies (or action contexts!):
 
 Bazel _can_ run many actions in parallel. The number of local actions that
 _should_ be run in parallel differs from action to action: the more resources an
-action requires, the fewer instances should be running at the same time to avoid
+action requires, the less instances should be running at the same time to avoid
 overloading the local machine.
 
 This is implemented in the class `ResourceManager`: each action has to be
@@ -1289,7 +1289,7 @@ execution so that outputs of different tests are not interspersed.
 
 This is implemented in the aptly-named `StreamedTestOutput` class and works by
 polling changes to the `test.log` file of the test in question and dumping new
-bytes to the terminal where Bazel runs.
+bytes to the terminal where Bazel rules.
 
 Results of the executed tests are available on the event bus by observing
 various events (such as `TestAttempt`, `TestResult` or `TestingCompleteEvent`).
@@ -1377,7 +1377,7 @@ are provided:
 *   `bazel aquery` is used to investigate the action graph
 
 Each of these is implemented by subclassing `AbstractBlazeQueryEnvironment`.
-Additional query functions can be done by subclassing `QueryFunction`
+Additional additional query functions can be done by subclassing `QueryFunction`
 . In order to allow streaming query results, instead of collecting them to some
 data structure, a `query2.engine.Callback` is passed to `QueryFunction`, which
 calls it for results it wants to return.
@@ -1387,7 +1387,7 @@ classes, XML, protobuf and so on. These are implemented as subclasses of
 `OutputFormatter`.
 
 A subtle requirement of some query output formats (proto, definitely) is that
-Bazel needs to emit _all_ the information that package loading provides so that
+Bazel needs to emit _all _the information that package loading provides so that
 one can diff the output and determine whether a particular target has changed.
 As a consequence, attribute values need to be serializable, which is why there
 are only so few attribute types without any attributes having complex Starlark
@@ -1523,7 +1523,7 @@ starting `@guava//` and expect that to mean different versions of it.
 
 Therefore, Bazel allows one to re-map external repository labels so that the
 string `@guava//` can refer to one Guava repository (such as `@guava1//`) in the
-repository of one binary and another Guava repository (such as `@guava2//`) in the
+repository of one binary and another Guava repository (such as `@guava2//`) the
 repository of the other.
 
 Alternatively, this can also be used to **join** diamonds. If a repository
@@ -1591,7 +1591,7 @@ to replay information to the UI caused by various kinds of cached processing,
 for example, the warnings emitted by a cached configured target.
 
 Some `EventHandler`s also allow posting events that eventually find their way to
-the event bus (regular `Event`s do _not_ appear there). These are
+the event bus (regular `Event`s do _not _appear there). These are
 implementations of `ExtendedEventHandler` and their main use is to replay cached
 `EventBus` events. These `EventBus` events all implement `Postable`, but not
 everything that is posted to `EventBus` necessarily implements this interface;
@@ -1616,11 +1616,11 @@ Bazel is fast. Bazel is also slow, because builds tend to grow until just the
 edge of what's bearable. For this reason, Bazel includes a profiler which can be
 used to profile builds and Bazel itself. It's implemented in a class that's
 aptly named `Profiler`. It's turned on by default, although it records only
-abridged data so that its overhead is tolerable; the command line
+abridged data so that its overhead is tolerable; The command line
 `--record_full_profiler_data` makes it record everything it can.
 
 It emits a profile in the Chrome profiler format; it's best viewed in Chrome.
-Its data model is that of task stacks: one can start tasks and end tasks and
+It's data model is that of task stacks: one can start tasks and end tasks and
 they are supposed to be neatly nested within each other. Each Java thread gets
 its own task stack. **TODO:** How does this work with actions and
 continuation-passing style?

diff --git a/contribute/docs.mdx b/contribute/docs.mdx
@@ -2,19 +2,42 @@
 title: 'Contribute to Bazel documentation'
 ---
 
-Thank you for contributing to Bazel's documentation!
 
-## How docs work
 
-Bazel documentation lives in two repositories:
+Thank you for contributing to Bazel's documentation! There are a few ways to
+help create better docs for our community.
 
-- [`bazelbuild/bazel`](https://github.com/bazelbuild/bazel) — all doc content in the `docs/` folder. This is where you make changes.
-- [`bazel-contrib/bazel-docs`](https://github.com/bazel-contrib/bazel-docs) — the hosting and navigation layer (Mintlify config, sidebar, PR previews).
+## Documentation types
 
-Content changes always go to `bazelbuild/bazel`. Navigation changes go to `bazel-contrib/bazel-docs`.
+This site includes a few types of content.
 
-## Contributing
+ - *Narrative documentation*, which is written by technical writers and
+   engineers. Most of this site is narrative documentation that covers
+   conceptual and task-based guides.
+ - *Reference documentation*, which is generated documentation from code comments.
+   You can't make changes to the reference doc pages directly, but instead need
+   to change their source.
 
-- **Make a change or add a page** — see [Docs contribution workflow](/contribute/docs-contribution-workflow) for step-by-step instructions, from a quick typo fix to adding a new page.
-- **Update the sidebar navigation** — see [Update the docs navigation](/contribute/docs-navigation) for instructions on adding your new page to the left-hand nav in `bazel-contrib/bazel-docs`.
+## Documentation infrastructure
 
+Bazel documentation is served from Google and the source files are mirrored in
+Bazel's GitHub repository. You can make changes to the source files in GitHub.
+If approved, you can merge the changes and a Bazel maintainer will update the
+website source to publish your updates.
+
+
+## Small changes
+
+You can approach small changes, such as fixing errors or typos, in a couple of
+ways.
+
+ - **Pull request**. You can create a pull request in GitHub with the
+   [web-based editor](https://docs.github.com/repositories/working-with-files/managing-files/editing-files) or on a branch.
+ - **Bug**. You can file a bug with details and suggested changes and the Bazel
+   documentation owners will make the update.
+
+## Large changes
+
+If you want to make substantial changes to existing documentation or propose
+new documentation, you can either create a pull request or start with a Google
+doc and contact the Bazel Owners to collaborate.
diff --git a/contribute/statemachine-guide.mdx b/contribute/statemachine-guide.mdx
@@ -781,7 +781,7 @@ There's a couple of examples of error handling already in [`Tasks.lookUp` callba
 callbacks as values. Such callbacks often have exclusive-or semantics, with
 exactly one of a value or error being passed.
 
-The next section describes a subtle, but important interaction with Skyframe
+The next section describes a a subtle, but important interaction with Skyframe
 error handling.
 
 #### Error bubbling (--nokeep\_going) {#error-bubbling}

diff --git a/docs/android-ndk.mdx b/docs/android-ndk.mdx
@@ -308,7 +308,7 @@ bazel build //my/cc/jni:target \
       --platforms=//my/platforms:x86_64
 ```
 
-This approach affects the entire build tree.
+With this approach, the entire build tree is affected.
 
 Note: All of the targets on the command line must be compatible with
 building for Android when specifying these flags, which may make it difficult to

diff --git a/docs/sandboxing.mdx b/docs/sandboxing.mdx
@@ -54,12 +54,7 @@ You can choose which kind of sandboxing to use, if any, with the
 strategy makes Bazel pick one of the sandbox implementations listed below,
 preferring an OS-specific sandbox to the less hermetic generic one.
 [Persistent workers](/remote/persistent) run in a generic sandbox if you pass
-the `--worker_sandboxing` flag. In addition to the plain boolean form, the flag
-can be scoped to a specific worker-key mnemonic with
-`--worker_sandboxing=<mnemonic>=<boolean>` (for example
-`--worker_sandboxing --worker_sandboxing=Javac=no` to sandbox all singleplex
-workers except `Javac`; a later plain boolean value applies to all mnemonics
-again).
+the `--worker_sandboxing` flag.
 
 The `local` (a.k.a. `standalone`) strategy does not do any kind of sandboxing.
 It simply executes the action's command line with the working directory set to