chore: update documentation from upstream Bazel repo [skip ci]

Synchronized pre-converted MDX files from upstream Bazel repository.

Author: github-actions[bot]

about/faq.mdx

@@ -157,6 +157,10 @@ Bazel returns a non-zero exit code if the build or test invocation fails, and th
 
 Further details on exit codes are in the [User Manual](/docs/user-manual).
 
+## What future features can we expect in Bazel?
+
+See our [Roadmaps](/about/roadmap).
+
 ## Can I use Bazel for my INSERT LANGUAGE HERE project?
 
 Bazel is extensible. Anyone can add support for new languages. Many languages are supported: see the [build encyclopedia](/reference/be/overview) for a list of recommendations and [awesomebazel.com](https://awesomebazel.com/) for a more comprehensive list.

about/intro.mdx

@@ -9,7 +9,7 @@ It uses a human-readable, high-level build language. Bazel supports projects in
 multiple languages and builds outputs for multiple platforms. Bazel supports
 large codebases across multiple repositories, and large numbers of users.
 
-## Benefits {#benefits}
+## Benefits
 
 Bazel offers the following advantages:
 
@@ -38,7 +38,7 @@ Bazel offers the following advantages:
     supported, and you can extend Bazel to support any other language or
     framework.
 
-## Using Bazel {#using-bazel}
+## Using Bazel
 
 To build or test a project with Bazel, you typically do the following:
 
@@ -71,7 +71,7 @@ In addition to building, you can also use Bazel to run
 [tests](/reference/test-encyclopedia) and [query](/query/guide) the build
 to trace dependencies in your code.
 
-## Bazel build process {#bazel-build-process}
+## Bazel build process
 
 When running a build or a test, Bazel does the following:
 
@@ -91,7 +91,7 @@ correctness, you can set up Bazel to run builds and tests
 [hermetically](/basics/hermeticity) through sandboxing, minimizing skew
 and maximizing [reproducibility](/run/build#correct-incremental-rebuilds).
 
-### Action graph {#action-graph}
+### Action graph
 
 The action graph represents the build artifacts, the relationships between them,
 and the build actions that Bazel will perform. Thanks to this graph, Bazel can
@@ -100,7 +100,7 @@ file content as well as changes to actions, such as build or test commands, and
 know what build work has previously been done. The graph also enables you to
 easily [trace dependencies](/query/guide) in your code.
 
-## Getting started tutorials {#getting-started-tutorials}
+## Getting started tutorials
 
 To get started with Bazel, see [Getting Started](/start/) or jump
 directly to the Bazel tutorials:

about/vision.mdx

@@ -45,7 +45,7 @@ Bazel's abstraction layer — instructions specific to languages, platforms, and
 toolchains implemented in a simple extensibility language — allows it to be
 easily applied to any context.
 
-## Bazel core competencies {#bazel-core-competencies}
+## Bazel core competencies
 
 1.  Bazel supports **multi-language, multi-platform** builds and tests. You can
     run a single command to build and test your entire source tree, no matter
@@ -62,7 +62,7 @@ easily applied to any context.
     possible. Bazel interfaces with de-facto standard tools for a given
     language/platform.
 
-## Serving language communities {#language-communities}
+## Serving language communities
 
 Software engineering evolves in the context of language communities — typically,
 self-organizing groups of people who use common tools and practices.
@@ -73,7 +73,7 @@ available that integrate with the workflows and conventions of that community.
 Bazel is committed to be extensible and open, and to support good rulesets for
 any language.
 
-###  Requirements of a good ruleset {#ruleset-requirements}
+###  Requirements of a good ruleset
 
 1.  The rules need to support efficient **building and testing** for the
     language, including code coverage.

about/why.mdx

@@ -9,7 +9,7 @@ build tool with [integrated testing](#integrated-testing) that supports multiple
 [languages](#multi-language), [repositories](#multi-repository), and
 [platforms](#multi-platform) in an industry-leading [ecosystem](#ecosystem).
 
-## Bazel is fast {#fast}
+## Bazel is fast
 
 Bazel knows exactly what input files each build command needs, avoiding
 unnecessary work by re-running only when the set of input files have
@@ -22,7 +22,7 @@ This is supported by multiple caching layers, in memory, on disk and on the
 remote build farm, if available. At Google, we routinely achieve cache hit rates
 north of 99%.
 
-## Bazel is correct {#correct}
+## Bazel is correct
 
 Bazel ensures that your binaries are built *only* from your own
 source code. Bazel actions run in individual sandboxes and Bazel tracks
@@ -34,7 +34,7 @@ by bit.
 Say goodbye to endless `make clean` invocations and to chasing phantom bugs
 that were in fact resolved in source code that never got built.
 
-## Bazel is extensible {#extensible}
+## Bazel is extensible
 
 Harness the full power of Bazel by writing your own rules and macros to
 customize Bazel for your specific needs across a wide range of projects.
@@ -44,7 +44,7 @@ in-house programming language that's a subset of Python. Starlark makes
 rule-writing accessible to most developers, while also creating rules that can
 be used across the ecosystem.
 
-## Integrated testing {#integrated-testing}
+## Integrated testing
 
 Bazel's [integrated test runner](/docs/user-manual#running-tests)
 knows and runs only those tests needing to be re-run, using remote execution
@@ -55,28 +55,28 @@ Bazel [provides facilities](/remote/bep) to upload test results to a central
 location, thereby facilitating efficient communication of test outcomes, be it
 on CI or by individual developers.
 
-## Multi-language support {#multi-language}
+## Multi-language support
 
 Bazel supports many common programming languages including C++, Java,
 Kotlin, Python, Go, and Rust. You can build multiple binaries (for example,
 backend, web UI and mobile app) in the same Bazel invocation without being
 constrained to one language's idiomatic build tool.
 
-## Multi-repository support {#multi-repository}
+## Multi-repository support
 
 Bazel can [gather source code from multiple locations](/external/overview): you
 don't need to vendor your dependencies (but you can!), you can instead point
 Bazel to the location of your source code or prebuilt artifacts (e.g. a git
 repository or Maven Central), and it takes care of the rest.
 
-## Multi-platform support {#multi-platform}
+## Multi-platform support
 
 Bazel can simultaneously build projects for multiple platforms including Linux,
 macOS, Windows, and Android. It also provides powerful
 [cross-compilation capabilities](/extending/platforms) to build code for one
 platform while running the build on another.
 
-## Wide ecosystem {#ecosystem}
+## Wide ecosystem
 
 [Industry leaders](/community/users) love Bazel, building a large
 community of developers who use and contribute to Bazel. Find a tools, services

advanced/performance/build-performance-metrics.mdx

@@ -23,7 +23,7 @@ how you can use these metrics to detect and fix build performance issues.
 
 There are a few main ways to extract metrics from your Bazel builds, namely:
 
-## Build Event Protocol (BEP) {#build-event-protocol}
+## Build Event Protocol (BEP)
 
 Bazel outputs a variety of protocol buffers
 [`build_event_stream.proto`](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/buildeventstream/proto/build_event_stream.proto)
@@ -32,7 +32,7 @@ can be aggregated by a backend specified by you. Depending on your use cases,
 you might decide to aggregate the metrics in various ways, but here we will go
 over some concepts and proto fields that would be useful in general to consider.
 
-## Bazel’s query / cquery / aquery commands {#bazel-commands-query-cquery-aquery}
+## Bazel’s query / cquery / aquery commands
 
 Bazel provides 3 different query modes ([query](/query/quickstart),
 [cquery](/query/cquery) and [aquery](/query/aquery)) that allow users
@@ -41,14 +41,14 @@ respectively. The query language provides a
 [suite of functions](/query/language#functions) usable across the different
 query modes, that allows you to customize your queries according to your needs.
 
-## JSON Trace Profiles {#json-trace-profiles}
+## JSON Trace Profiles
 
 For every build-like Bazel invocation, Bazel writes a trace profile in JSON
 format. The [JSON trace profile](/advanced/performance/json-trace-profile) can
 be very useful to quickly understand what Bazel spent time on during the
 invocation.
 
-## Execution Log {#execution-log}
+## Execution Log
 
 The [execution log](/remote/cache-remote) can help you to troubleshoot and fix
 missing remote cache hits due to machine and environment differences or
@@ -60,7 +60,7 @@ make comparisons between local and remote machine performance or to find out
 which part of the spawn execution is consistently slower than expected (for
 example due to queuing).
 
-## Execution Graph Log {#execution-graph-log}
+## Execution Graph Log
 
 While the JSON trace profile contains the critical path information, sometimes
 you need additional information on the dependency graph of the executed actions.
@@ -76,7 +76,7 @@ by removing a particular node from the execution graph.
 The data helps you predict the impact of changes to the build and action graph
 before you actually do them.
 
-## Benchmarking with bazel-bench {#bazel-bench}
+## Benchmarking with bazel-bench
 
 [Bazel bench](https://github.com/bazelbuild/bazel-bench) is a
 benchmarking tool for Git projects to benchmark build performance in the

advanced/performance/iteration-speed.mdx

@@ -7,7 +7,7 @@ title: 'Optimize Iteration Speed'
 This page describes how to optimize Bazel's build performance when running Bazel
 repeatedly.
 
-## Bazel's Runtime State {#bazel-runtime-state}
+## Bazel's Runtime State
 
 A Bazel invocation involves several interacting parts.
 
@@ -32,7 +32,7 @@ A Bazel invocation involves several interacting parts.
 
 *   The result of the Bazel invocation is made available in the output tree.
 
-## Running Bazel Iteratively {#run-iteratively}
+## Running Bazel Iteratively
 
 In a typical developer workflow, it is common to build (or run) a piece of code
 repeatedly, often at a very high frequency (e.g. to resolve some compilation
@@ -64,7 +64,7 @@ cache can be kept locally
 [remotely](https://bazel.build/remote/caching). The cache can be shared among
 Bazel servers, and indeed among developers.
 
-## Avoid discarding the analysis cache {#avoid-discarding-cache}
+## Avoid discarding the analysis cache
 
 Bazel will print a warning if either the analysis cache was discarded or the
 server was restarted. Either of these should be avoided during iterative use:

advanced/performance/json-trace-profile.mdx

@@ -76,7 +76,7 @@ $ zcat $(../bazel-6.0.0rc1-linux-x86_64 info output_base)/command.profile.gz | j
 [...]
 ```
 
-## Profile information {#profile-information}
+## Profile information
 
 The profile contains multiple rows. Usually the bulk of rows represent Bazel
 threads and their corresponding events, but some special rows are also included.
@@ -99,7 +99,7 @@ Figure 1 shows a profile created with Bazel v5.3.1 and includes these rows:
 *   `Garbage Collector`: Displays minor and major Garbage Collection (GC)
     pauses.
 
-## Common performance issues {#common-performance-issues}
+## Common performance issues
 
 When analyzing performance profiles, look for:
 
@@ -117,7 +117,7 @@ When analyzing performance profiles, look for:
     or Bazel itself to introduce more parallelism. This can also happen when
     there is an unusual amount of GC.
 
-## Profile file format {#profile-file-format}
+## Profile file format
 
 The top-level object contains metadata (`otherData`) and the actual tracing data
 (`traceEvents`). The metadata contains extra info, for example the invocation ID

advanced/performance/memory.mdx

@@ -6,14 +6,14 @@ title: 'Optimize Memory'
 
 This page describes how to limit and reduce the memory Bazel uses.
 
-## Running Bazel with Limited RAM {#running-bazel}
+## Running Bazel with Limited RAM
 
 In certain situations, you may want Bazel to use minimal memory. You can set the
 maximum heap via the startup flag
 [`--host_jvm_args`](/docs/user-manual#host-jvm-args),
 like `--host_jvm_args=-Xmx2g`.
 
-### Trade incremental build speeds for memory {#trade-incremental}
+### Trade incremental build speeds for memory
 
 If your builds are too big, Bazel may throw an `OutOfMemoryError` (OOM) when
 it doesn't have enough memory. You can make Bazel use less memory, at the cost
@@ -40,7 +40,7 @@ prevent most re-execution).
  incremental builds have to build from scratch (except for the on-disk action
  cache). Alone, it does not affect the high-water mark of the current build.
 
-### Trade build flexibility for memory with Skyfocus (Experimental) {#trade-flexibility}
+### Trade build flexibility for memory with Skyfocus (Experimental)
 
 If you want to make Bazel use less memory *and* retain incremental build speeds,
 you can tell Bazel the working set of files that you will be modifying, and
@@ -59,11 +59,11 @@ changes to files outside of the working set will be disallowed, until you issue
 `bazel clean` or restart the Bazel server.
 
 If you want to specify an exact set of files or directories, use the
-`--experimental_active_directories` flag, like so:
+`--experimental_working_set` flag, like so:
 
 ```sh
 bazel build //pkg:target --experimental_enable_skyfocus
---experimental_active_directories=path/to/another/dir,path/to/tests/dir
+--experimental_working_set=path/to/another/dir,path/to/tests/dir
 ```
 
 You can also pass `--experimental_skyfocus_dump_post_gc_stats` to show the
@@ -72,7 +72,7 @@ memory reduction amount:
 Putting it altogether, you should see something like this:
 
 ```none
-$ bazel test //pkg:target //tests/... --experimental_enable_skyfocus --experimental_active_directories=dir1,dir2,dir3/subdir --experimental_skyfocus_dump_post_gc_stats
+$ bazel test //pkg:target //tests/... --experimental_enable_skyfocus --experimental_working_set dir1,dir2,dir3/subdir --experimental_skyfocus_dump_post_gc_stats
 INFO: --experimental_enable_skyfocus is enabled. Blaze will reclaim memory not needed to build the working set. Run 'blaze dump --skyframe=working_set' to show the working set, after this command.
 WARNING: Changes outside of the working set will cause a build error.
 INFO: Analyzed 149 targets (4533 packages loaded, 169438 targets configured).
@@ -89,7 +89,7 @@ and incremental builds to handle changes to files under `dir1`, `dir2`, and
 `dir3/subdir` will retain their fast speeds, with the tradeoff that Bazel cannot
 rebuild changed files outside of these directories.
 
-## Memory Profiling {#memory-profiling}
+## Memory Profiling
 
 Bazel comes with a built-in memory profiler that can help you check your rule’s
 memory use. Read more about this process on the

basics/hermeticity.mdx

@@ -7,7 +7,7 @@ title: 'Hermeticity'
 This page covers hermeticity, the benefits of using hermetic builds, and
 strategies for identifying non-hermetic behavior in your builds.
 
-## Overview {#overview}
+## Overview
 
 When given the same input source code and product configuration, a hermetic
 build system always returns the same output by isolating the build from changes
@@ -30,7 +30,7 @@ The two important aspects of hermeticity are:
   unique hash code. Hermetic build systems use this hash to identify changes to
   the build's input.
 
-## Benefits {#benefits}
+## Benefits
 
 The major benefits of hermetic builds are:
 
@@ -45,7 +45,7 @@ The major benefits of hermetic builds are:
 * **Reproducibility**: Hermetic builds are good for troubleshooting because you
   know the exact conditions that produced the build.
 
-## Identifying non-hermeticity {#nonhermeticity}
+## Identifying non-hermeticity
 
 If you are preparing to switch to Bazel, migration is easier if you improve
 your existing builds' hermeticity in advance. Some common sources of
@@ -61,7 +61,7 @@ non-hermeticity in builds are:
   tree, fixing the source tree for target A. Then trying to build target B may
   fail.
 
-## Troubleshooting non-hermetic builds {#troubleshooting-nonhermeticity}
+## Troubleshooting non-hermetic builds
 
 Starting with local execution, issues that affect local cache hits reveal
 non-hermetic actions.
@@ -94,7 +94,7 @@ Note: Make your build fully hermetic when mixing remote and local execution,
 using Bazel’s “dynamic strategy” functionality. Running Bazel inside the remote
 Docker container will enable the build to execute the same in both environments.
 
-## Hermeticity with Bazel {#hermeticity-bazel}
+## Hermeticity with Bazel
 
 For more information about how other projects have had success using hermetic
 builds with Bazel, see these  BazelCon talks: