Move update guide to documentation part of the website.

Also cross-reference from backwards compatibility policy.

Closes #8958.

PiperOrigin-RevId: 260804595

site/_layouts/documentation.html

@@ -68,6 +68,10 @@ <h3>Installing and Using Bazel</h3>
                 </ul>
               </li>
 
+              <li class="sidebar-nav">
+                <a href="/versions/{{ current_version }}/updating-bazel.html">Updating Bazel</a>
+              </li>
+
               <li>
                 <a class="sidebar-nav-heading" data-toggle="collapse"
                     href="#using-menu" aria-expanded="false"

site/docs/backward-compatibility.md

@@ -28,6 +28,8 @@ incompatible and require some changes from Bazel users.
 
 ### How to follow this policy
 
+* [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>
 

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