Move update guide to documentation part of the website.
Also cross-reference from backwards compatibility policy.
Closes #8958.
PiperOrigin-RevId: 260804595
diff --git a/site/docs/updating-bazel.md b/site/docs/updating-bazel.md
new file mode 100644
index 0000000..4e1e637
--- /dev/null
+++ b/site/docs/updating-bazel.md
@@ -0,0 +1,55 @@
+---
+layout: documentation
+title: Updating Bazel
+---
+
+# 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.
+
+
+## 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.
+
+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
+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 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.
+
+
+### 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
+
+
+## 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
