| Dmitry Lomov | 4285b4b | 2019-07-30 15:10:38 -0700 | [diff] [blame] | 1 | --- |
| 2 | layout: documentation |
| 3 | title: Updating Bazel |
| daroberts | 223aebd | 2021-02-18 17:53:30 -0800 | [diff] [blame] | 4 | category: getting-started |
| Dmitry Lomov | 4285b4b | 2019-07-30 15:10:38 -0700 | [diff] [blame] | 5 | --- |
| 6 | |
| 7 | # Updating Bazel |
| 8 | |
| Googler | 630941e | 2020-12-23 17:13:31 -0800 | [diff] [blame] | 9 | This page covers how to automatically update your Bazel version using Bazelisk. |
| 10 | |
| daroberts | 917e119 | 2020-06-08 16:36:50 -0700 | [diff] [blame] | 11 | The Bazel project has a [backward compatibility |
| aiuto | 4e9a77e | 2021-06-15 08:55:11 -0700 | [diff] [blame] | 12 | policy](https://docs.bazel.build/versions/main/backward-compatibility.html) |
| Greg Estren | e821cfa | 2020-02-20 09:34:56 -0800 | [diff] [blame] | 13 | (see [guidance for rolling out incompatible |
| Googler | 630941e | 2020-12-23 17:13:31 -0800 | [diff] [blame] | 14 | changes](https://www.bazel.build/maintaining/breaking-changes-guide.html) if you |
| 15 | are the author of one). That page summarizes best practices on how to test and |
| 16 | migrate your project with upcoming incompatible changes and how to provide |
| 17 | feedback to the incompatible change authors. |
| Dmitry Lomov | 4285b4b | 2019-07-30 15:10:38 -0700 | [diff] [blame] | 18 | |
| Greg Estren | e821cfa | 2020-02-20 09:34:56 -0800 | [diff] [blame] | 19 | ## Managing Bazel versions with Bazelisk |
| 20 | |
| ranjanih | 4538481 | 2021-04-14 09:23:43 -0700 | [diff] [blame] | 21 | [Bazelisk](https://github.com/bazelbuild/bazelisk) helps you manage Bazel |
| Greg Estren | e821cfa | 2020-02-20 09:34:56 -0800 | [diff] [blame] | 22 | versions. |
| 23 | |
| 24 | Bazelisk can: |
| ranjanih | 4538481 | 2021-04-14 09:23:43 -0700 | [diff] [blame] | 25 | * Auto-update Bazel to the latest LTS or rolling release. |
| Greg Estren | e821cfa | 2020-02-20 09:34:56 -0800 | [diff] [blame] | 26 | * Build the project with a Bazel version specified in the .bazelversion |
| 27 | file. Check in that file into your version control to ensure reproducibility |
| 28 | of your builds. |
| 29 | * Help migrate your project for incompatible changes (see above) |
| 30 | * Easily try release candidates |
| Dmitry Lomov | 4285b4b | 2019-07-30 15:10:38 -0700 | [diff] [blame] | 31 | |
| 32 | ## Recommended migration process |
| 33 | |
| ranjanih | 4538481 | 2021-04-14 09:23:43 -0700 | [diff] [blame] | 34 | Within minor updates to any LTS release, any |
| 35 | project can be prepared for the next release without breaking |
| 36 | compatibility with the current release. However, there may be |
| 37 | backward-incompatible changes between major LTS versions. |
| Dmitry Lomov | 4285b4b | 2019-07-30 15:10:38 -0700 | [diff] [blame] | 38 | |
| ranjanih | 4538481 | 2021-04-14 09:23:43 -0700 | [diff] [blame] | 39 | Follow this process to migrate from one major version to another: |
| Dmitry Lomov | 4285b4b | 2019-07-30 15:10:38 -0700 | [diff] [blame] | 40 | |
| ranjanih | 4538481 | 2021-04-14 09:23:43 -0700 | [diff] [blame] | 41 | 1. Read the release notes to get advice on how to migrate to the next version. |
| 42 | 1. Major incompatible changes should have an associated `--incompatible_*` flag |
| 43 | and a corresponding GitHub issue: |
| Dmitry Lomov | 4285b4b | 2019-07-30 15:10:38 -0700 | [diff] [blame] | 44 | * Migration guidance is available in the associated GitHub issue. |
| ranjanih | 4538481 | 2021-04-14 09:23:43 -0700 | [diff] [blame] | 45 | * Tooling is available for some of incompatible changes migration. For |
| 46 | example, [buildifier](https://github.com/bazelbuild/buildtools/releases). |
| 47 | * Report migration problems by commenting on the associated GitHub issue. |
| Dmitry Lomov | 4285b4b | 2019-07-30 15:10:38 -0700 | [diff] [blame] | 48 | |
| ranjanih | 4538481 | 2021-04-14 09:23:43 -0700 | [diff] [blame] | 49 | After migration, you can continue to build your projects without worrying about |
| 50 | backward-compatibility until the next major release. |
