Update Bazel docs to reflect LTS
PiperOrigin-RevId: 368445249
diff --git a/site/docs/updating-bazel.md b/site/docs/updating-bazel.md
index 8d8bf77..de9be2e 100644
--- a/site/docs/updating-bazel.md
+++ b/site/docs/updating-bazel.md
@@ -18,12 +18,11 @@
## Managing Bazel versions with Bazelisk
-The Bazel team implemented a Bazel wrapper called
-[bazelisk](https://github.com/bazelbuild/bazelisk) that helps you manage Bazel
+[Bazelisk](https://github.com/bazelbuild/bazelisk) helps you manage Bazel
versions.
Bazelisk can:
-* Auto-update Bazel to the latest version
+* Auto-update Bazel to the latest LTS or rolling release.
* 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.
@@ -32,39 +31,20 @@
## 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.
+Within minor updates to any LTS release, any
+project can be prepared for the next release without breaking
+compatibility with the current release. However, there may be
+backward-incompatible changes between major LTS versions.
-Follow this process for project migration:
+Follow this process to migrate from one major version to another:
-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:
+1. Read the release notes to get advice on how to migrate to the next version.
+1. Major incompatible changes should have an associated `--incompatible_*` flag
+ and a 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.
- * 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.
+ * Tooling is available for some of incompatible changes migration. For
+ example, [buildifier](https://github.com/bazelbuild/buildtools/releases).
+ * Report migration problems by commenting on the associated GitHub issue.
-
-### Migrating with Bazelisk
-
-[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
+After migration, you can continue to build your projects without worrying about
+backward-compatibility until the next major release.
