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/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
