site/docs/backward-compatibility.md

---
layout: documentation
title: Backward compatibility
category: getting-started
---

# Backward Compatibility

This page provides information on how to handle backward compatibility,
including migration requirements and how to communicate incompatible changes.
It also covers policy information and guidelines to follow these policies.

Bazel is evolving, and changes will be made to Bazel that at times will be
incompatible and require some changes from Bazel users.

## GitHub labels

* All incompatible changes: label [**incompatible-change**](https://github.com/bazelbuild/bazel/issues?q=label%3Aincompatible-change)
* Expected breaking change in release X.Y: label **breaking-change-X.Y** (for example: [**breaking-change-0.21**](https://github.com/bazelbuild/bazel/issues?utf8=%E2%9C%93&q=is%3Aissue+label%3Abreaking-change-0.21))
* Release X.Y is in a migration window: label **migration-X.Y** (for example: [**migration-0.21**](https://github.com/bazelbuild/bazel/issues?utf8=%E2%9C%93&q=is%3Aissue+label%3Amigration-0.21))


## At a glance

1. Every breaking change is guarded with an `--incompatible_*` flag.
1. Newly introduced incompatible flags default to off.
1. For every `--incompatible_*` flag, there is a GitHub issue that explains
   the change in behavior and provides a migration recipe.
1. The migration window is at least one release long and is set by the author of the incompatible change.
1. APIs and behavior guarded by an `--experimental_*` flag can change at any time.
1. Users should never run their production builds with `--experimental_*`  or `--incompatible_*` flags.

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


## What is stable functionality?

In general, APIs or behaviors without `--experimental_...` flags are considered
stable, supported features in Bazel.

This includes:

* Starlark language and APIs
* Rules bundled with Bazel
* Bazel APIs such as Remote Execution APIs or Build Event Protocol
* Flags and their semantics

## Incompatible changes and migration recipes

When a release contains an incompatible change, the Bazel team provides
_migration windows_ and _migration recipes_ to make it easier for Bazel users
to update their code.

Migration window is one or more release of Bazel during which a migration from
old functionality to new functionality is possible, according to a migration
recipe.

During the migration window, both the old and new functionality
are available in the Bazel release. For every incompatible change, a
_migration recipe_ is provided that allows updating the user code
(`BUILD` and `.bzl` files, as well as any Bazel usage in scripts,
usage of Bazel API, and so on) in such a way that **it works simultaneously
without any flags with old and new functionality**.

In other words, during a migration window for an incompatible change `foo`:

1. `--incompatible_foo` flag is available in Bazel release and defaults to off.
1. User code can be updated in such a way that it works simultaneously with
   that flag being on or off.
1. After the code is migrated, the users can check whether they migrated
   successfully by building with `--incompatible_foo=true`. However, their
   code will continue to work in the same release in default state (where
   `--incompatible_foo` is off), as well after the migration window is over
   (at which point the flag will be effectively on).

## Communicating incompatible changes

The primary source of information about incompatible changes are GitHub issues
marked with an ["incompatible-change" label](https://github.com/bazelbuild/bazel/issues?q=label%3Aincompatible-change).

For every incompatible change, the issue specifies the following:
* Name of the flag controlling the incompatible change
* Description of the changed functionality
* Migration recipe

The incompatible change issue is closed when the incompatible flag is flipped at
HEAD.

All the incompatible changes for which a Bazel release X.Y is part of a
migration window are marked with a label "migration-X.Y" label (for example
[migration-0.21](https://github.com/bazelbuild/bazel/issues?utf8=%E2%9C%93&q=is%3Aissue+label%3Amigration-0.21)).

All the incompatible changes that are expected to happen in release X.Y
are marked with a label "breaking-change-X.Y" (for example
[breaking-change-0.21](https://github.com/bazelbuild/bazel/issues?utf8=%E2%9C%93&q=is%3Aissue+label%3Abreaking-change-0.21)).