Misc style improvements
- Upgrades / downgrades some section header sizes to clearer positions
- Mild reorganization for clearer content flow
- Capitalization typo fixes
Serves https://github.com/bazelbuild/bazel/issues/10794
Closes #10820.
PiperOrigin-RevId: 296229327
diff --git a/site/docs/backward-compatibility.md b/site/docs/backward-compatibility.md
index 500f1a0..a3df992 100644
--- a/site/docs/backward-compatibility.md
+++ b/site/docs/backward-compatibility.md
@@ -26,9 +26,9 @@
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.
-### How to follow this policy
+## How to follow this policy
-* [For Bazel Users - how to update
+* [For Bazel users - how to update
Bazel](updating-bazel.html)
* [For contributors - best practices for incompatible changes](https://bazel.build/breaking-changes-guide.html)
* <a href='https://github.com/bazelbuild/continuous-integration/tree/master/docs/release-playbook.%6D%64'>For release managers - how to update issue labels and release</a>
diff --git a/site/docs/configurable-attributes.md b/site/docs/configurable-attributes.md
index 2c74ca8..4ecf439 100644
--- a/site/docs/configurable-attributes.md
+++ b/site/docs/configurable-attributes.md
@@ -90,6 +90,7 @@
<td><code>[":generic_lib"]</code></td>
</tr>
</table>
+
`select()` serves as a placeholder for a value that will be chosen based on
*configuration conditions*. These conditions are labels that refer to
[`config_setting`](be/general.html#config_setting) targets. By using `select()`
@@ -733,7 +734,7 @@
## FAQ
-## <a name="macros-select"></a>Why doesn't select() work in macros?
+### <a name="macros-select"></a>Why doesn't select() work in macros?
select() *does* work in rules! See [Rules compatibility](#rules) for
details.
@@ -844,7 +845,7 @@
DEBUG: /myworkspace/myproject/defs.bzl:15:3: My name is sad_macro_less_sad with custom message: FIRST STRING.
```
-## <a name="boolean-select"></a>Why does select() always return true?
+### <a name="boolean-select"></a>Why does select() always return true?
Because *macros* (but not rules) by definition
[can't evaluate select(s)](#macros-select), any attempt to do so
usually produces an error:
@@ -888,7 +889,7 @@
[Pythonic](https://docs.python.org/release/2.5.2/lib/truth.html) design
standards, all objects aside from a very small number of exceptions
automatically return true.
-## <a name="inspectable-select"></a>Can I read select() like a dict?
+### <a name="inspectable-select"></a>Can I read select() like a dict?
Fine. Macros [can't](#macros-select) evaluate select(s) because
macros are evaluated before Bazel knows what the command line flags are.
@@ -946,7 +947,7 @@
)
```
-## <a name="bind-select"></a>Why doesn't select() work with bind()?
+### <a name="bind-select"></a>Why doesn't select() work with bind()?
Because [`bind()`](be/workspace.html#bind) is a WORKSPACE rule, not a BUILD rule.
diff --git a/site/docs/test-encyclopedia.html b/site/docs/test-encyclopedia.html
index cde88be..2536fa5 100644
--- a/site/docs/test-encyclopedia.html
+++ b/site/docs/test-encyclopedia.html
@@ -41,7 +41,7 @@
specification takes precedence.</p>
-<h3>Purpose of Tests</h3>
+<h2>Purpose of Tests</h2>
<p>The purpose of Bazel tests is to confirm some property of the source files
checked into the repository. (In this document, "source files" includes test data,
@@ -62,7 +62,7 @@
<p>Currently, such behavior is not enforced. However, test runners reserve the
right to add such enforcement in the future.</p>
-<h3>Role of the Build System</h3>
+<h2>Role of the Build System</h2>
<p>Test rules are analogous to binary rules in that each must yield an
executable program. For some languages, this is a stub program which combines
@@ -79,7 +79,7 @@
image provided by the test runner, rather than hardcoded references to absolute
locations in the source or output tree.</p>
-<h3>Role of the Test Runner</h3>
+<h2>Role of the Test Runner</h2>
<p>From the point of view of the test runner, each test is a program which can
be invoked with <code>execve()</code>. There may be other ways to execute
@@ -193,7 +193,7 @@
<p>When executing a test, the test runner must establish certain initial
conditions.</p>
-<h3>Initial Conditions</h3>
+<h2>Initial Conditions</h2>
<p>The test runner must invoke each test with the path to the test
executable in <code>argv[0]</code>. This path must be relative and
@@ -310,7 +310,7 @@
<p>The initial scheduling policy and priority are unspecified.</p>
-<h3>Role of the Host System</h3>
+<h2>Role of the Host System</h2>
<p>In addition to the aspects of user context under direct control of the
test runner, the operating system on which tests execute must satisfy certain
@@ -380,7 +380,7 @@
<p>X Windows may or may not be available. Tests that need an X server should
start Xvfb.</p>
-<h3>Test interaction with the filesystem</h3>
+<h2>Test interaction with the filesystem</h2>
<p>All file paths specified in test environment variables point to
somewhere on the local filesystem, unless otherwise specified.</p>
@@ -423,7 +423,7 @@
Bazel sees the file when the test finishes, it will assume that the test exited
prematurely and mark it as having failed.</p>
-<h3 id="tag-conventions">Tag conventions</h3>
+<h2 id="tag-conventions">Tag conventions</h2>
<p>
Some tags in the test rules have a special
@@ -478,7 +478,7 @@
</table>
*Note: bazel <code>query</code> does not respect the manual tag.
-<h3>Runfiles</h3>
+<h2>Runfiles</h2>
<p>In the following, assume there is a *_binary() rule labeled <code>//foo/bar:unittest</code>,
with a run-time dependency on the rule labeled <code>//deps/server:server</code>.</p>
diff --git a/site/docs/updating-bazel.md b/site/docs/updating-bazel.md
index 4e1e637..3c41ef8 100644
--- a/site/docs/updating-bazel.md
+++ b/site/docs/updating-bazel.md
@@ -5,33 +5,56 @@
# Updating Bazel
-Bazel defined a [backwards compatibility policy](https://docs.bazel.build/versions/master/backward-compatibility.html)
-(see [guidance for rolling out incompatible changes](https://www.bazel.build/breaking-changes-guide.html) if you are the author of one).
-This page summarized best practices on how to test and migrate your project with upcoming incompatible
-changes and how to provide feedback to the incompatible change authors.
+The Bazel project has a [backwards compatibility
+policy](https://docs.bazel.build/versions/master/backward-compatibility.html)
+(see [guidance for rolling out incompatible
+changes](https://www.bazel.build/breaking-changes-guide.html) if you are the
+author of one). That page summarizes best practices on how to test and migrate
+your project with upcoming incompatible changes and how to provide feedback to
+the incompatible change authors.
+## Managing Bazel versions with Bazelisk
+
+The Bazel team implemented a Bazel wrapper called
+[bazelisk](https://github.com/bazelbuild/bazelisk) that helps you manage Bazel
+versions.
+
+Bazelisk can:
+* Auto-update Bazel to the latest version
+* Build the project with a Bazel version specified in the .bazelversion
+ file. Check in that file into your version control to ensure reproducibility
+ of your builds.
+* Help migrate your project for incompatible changes (see above)
+* Easily try release candidates
## Recommended migration process
-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.
+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:
-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
+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
2. Find all incompatible changes for which the migration can be started: they are marked with
- "migration-\<release\>" label on GitHub, for example "[migration-0.26](https://github.com/bazelbuild/bazel/issues?utf8=%E2%9C%93&q=label%3Amigration-0.26+)".
-3. Each of those issues has an associated `--incompatible_*` flag. For each of them, build your project
- with that flag enabled, and if the build is unsuccessful, fix the project according to
- [migration recipe](https://docs.bazel.build/versions/master/backward-compatibility.html#incompatible-changes-and-migration-recipes) as specified in the corresponding GitHub issue:
+ "migration-\<release\>" label on GitHub, for example
+ "[migration-0.26](https://github.com/bazelbuild/bazel/issues?utf8=%E2%9C%93&q=label%3Amigration-0.26+)".
+3. Each of those issues has an associated `--incompatible_*` flag. For each of
+ them, build your project with that flag enabled, and if the build is
+ unsuccessful, fix the project according to [migration
+ recipe](https://docs.bazel.build/versions/master/backward-compatibility.html#incompatible-changes-and-migration-recipes)
+ as specified in the corresponding GitHub issue:
* Migration guidance is available in the associated GitHub issue.
* Migration is always possible in such a way that the project continues to build with and without the flag.
- * For some of the incompatible changes migration tooling is available, for example as part of [buildifier](https://github.com/bazelbuild/buildtools/releases). Be sure to check the GitHub issue for migration instructions.
+ * For some of the incompatible changes migration tooling is available, for
+ example as part of
+ [buildifier](https://github.com/bazelbuild/buildtools/releases). Be sure
+ to check the GitHub issue for migration instructions.
* Please report any migration problems by commenting associated GitHub issue.
-4. After all changes are migrated, you can continue to build your project without any flags:
- it will be ready for the next Bazel release.
+4. After all changes are migrated, you can continue to build your project
+ without any flags: it will be ready for the next Bazel release.
### Migrating with Bazelisk
@@ -39,17 +62,7 @@
[Bazelisk](https://github.com/bazelbuild/bazelisk) can
greatly simplify the migration process described above.
-* `bazelisk --strict` will build given targets with all incompatible flags for changes with appropriate migration-* labels.
-* `bazelisk --migrate` will do even more: it will try every flag and report those for which the build was unsuccessful
-
-
-## Managing Bazel versions with Bazelisk
-
-Bazel team implemented a Bazel wrapper called [bazelisk](https://github.com/bazelbuild/bazelisk) that helps you
-manage Bazel versions.
-
-Bazelisk can:
-* Autoupdate Bazel to the latest version
-* Build the project with a Bazel version specified in the .bazelversion file. Check in that file into your version control to ensure reproducibility of your builds.
-* Help migrate your project for incompatible changes (see above)
-* Easily try release candidates
+* `bazelisk --strict` will build given targets with all incompatible flags for
+ changes with appropriate migration-* labels.
+* `bazelisk --migrate` will do even more: it will try every flag and report
+ those for which the build was unsuccessful