From d3e0028267b74506f4d4b0f799ba28e3d2250d85 Mon Sep 17 00:00:00 2001 From: Dmitry Lomov Date: Fri, 11 Jan 2019 18:26:18 +0100 Subject: [PATCH 1/8] Add documentation for incompatible change process. Change-Id: I6129e587ffde66fd7d4ba26c147ae7c12409f3d2 --- site/_layouts/documentation.html | 2 +- site/docs/backward-compatibility.md | 82 +++++++++++++++++++++ site/docs/skylark/backward-compatibility.md | 9 +-- 3 files changed, 86 insertions(+), 7 deletions(-) create mode 100644 site/docs/backward-compatibility.md diff --git a/site/_layouts/documentation.html b/site/_layouts/documentation.html index 5e4d4f993375e4..b5ca332f97f819 100644 --- a/site/_layouts/documentation.html +++ b/site/_layouts/documentation.html @@ -44,7 +44,7 @@

Home

  • Bazel Overview
  • Bazel Vision
  • Getting Started
    • -
  • Backward Compatibility
    • +
  • Backward Compatibility

    • Using Bazel

    diff --git a/site/docs/backward-compatibility.md b/site/docs/backward-compatibility.md new file mode 100644 index 00000000000000..e5cfff0f7c5ebd --- /dev/null +++ b/site/docs/backward-compatibility.md @@ -0,0 +1,82 @@ +--- +layout: documentation +title: Backward Compatibility +--- + +# Backward Compatibility + +Bazel is evolving, and we will make changes to Bazel that at times will be +incompatible and require some changes from Bazel users. + +## 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 we have a github issue explaining + the change in behavior and giving a migration recipe. +1. The migration window is at least one release long and is set by the author of the incompatible change. +1. We announce what set of flags we flip with the next release one release in advance. +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. + +## What is stable functionality? + +In general, if an API or a behavior is available in Bazel without +`--experimental_...` flag, we consider it a stable, supported feature. +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 we introduce an incompatible change, we try to make it easier for Bazel +users to updatre their code. We do this by means of _migration windows_ and +_migration recipes_. + +Migration window is one or more release of Bazel during which a migration from +old funcitonality to new functionality is possible, according to a migration +recipe. + +During the migration window, both the old funcitonality and the new functionality +are available in the Bazel release. For every incompatible change, we provide +a _migration recipe_ 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 of), 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 name of the flag controlling the incompatible change +* the description of the changed functionality +* the migration recipe + +The incompatible change issue is closed when the incompatible flag is flipped at +HEAD. + +All the incompatible changes for which a Bazel releaze 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)). + + diff --git a/site/docs/skylark/backward-compatibility.md b/site/docs/skylark/backward-compatibility.md index 5d83e15ab89550..8a6d8e7ca1b88e 100644 --- a/site/docs/skylark/backward-compatibility.md +++ b/site/docs/skylark/backward-compatibility.md @@ -1,15 +1,12 @@ --- layout: documentation -title: Backward Compatibility +title: Starlark Incompatible CHnages --- -# Backward Compatibility -Bazel is still in Beta and new releases may include backward incompatible -changes. As we make changes and polish the extension mechanism, old features -may be removed and new features that are not backward compatible may be added. +# Backward Compatibility -Backward incompatible changes are introduced gradually: +Backward incompatible changes in Starlark are introduced gradually: 1. The backward incompatible change is introduced behind a flag with its default value set to `false`. From 7d0e66c443b6e792af3da1b6ac1dba449ea55c07 Mon Sep 17 00:00:00 2001 From: Dmitry Lomov Date: Fri, 11 Jan 2019 22:58:41 +0100 Subject: [PATCH 2/8] Typos --- site/docs/backward-compatibility.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/site/docs/backward-compatibility.md b/site/docs/backward-compatibility.md index e5cfff0f7c5ebd..9db5e73b0c1050 100644 --- a/site/docs/backward-compatibility.md +++ b/site/docs/backward-compatibility.md @@ -33,14 +33,14 @@ This includes: ## Incompatible changes and migration recipes When we introduce an incompatible change, we try to make it easier for Bazel -users to updatre their code. We do this by means of _migration windows_ and +users to update their code. We do this by means of _migration windows_ and _migration recipes_. Migration window is one or more release of Bazel during which a migration from old funcitonality to new functionality is possible, according to a migration recipe. -During the migration window, both the old funcitonality and the new functionality +During the migration window, both the old functionality and the new functionality are available in the Bazel release. For every incompatible change, we provide a _migration recipe_ 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 From 0a739cd1893f1c4e73586b4e9c5b25c20e80f938 Mon Sep 17 00:00:00 2001 From: Dmitry Lomov Date: Fri, 11 Jan 2019 22:59:23 +0100 Subject: [PATCH 3/8] typos --- site/docs/backward-compatibility.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/docs/backward-compatibility.md b/site/docs/backward-compatibility.md index 9db5e73b0c1050..11b84da1a8ae75 100644 --- a/site/docs/backward-compatibility.md +++ b/site/docs/backward-compatibility.md @@ -37,7 +37,7 @@ users to update their code. We do this by means of _migration windows_ and _migration recipes_. Migration window is one or more release of Bazel during which a migration from -old funcitonality to new functionality is possible, according to a migration +old functionality to new functionality is possible, according to a migration recipe. During the migration window, both the old functionality and the new functionality From 06d21799a05082f16bebf2c3961b3f0db31eacfc Mon Sep 17 00:00:00 2001 From: Jingwen Date: Tue, 15 Jan 2019 09:26:34 +0100 Subject: [PATCH 4/8] Update site/docs/backward-compatibility.md Co-Authored-By: dslomov --- site/docs/backward-compatibility.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/docs/backward-compatibility.md b/site/docs/backward-compatibility.md index 11b84da1a8ae75..95a24857f7457e 100644 --- a/site/docs/backward-compatibility.md +++ b/site/docs/backward-compatibility.md @@ -12,7 +12,7 @@ incompatible and require some changes from Bazel users. 1. Every breaking change is guarded with an `--incompatible_*` flag. 1. Newly introduced incompatible flags default to off. -1. For every `--incompatible_*` flag we have a github issue explaining +1. For every `--incompatible_*` flag we have a GitHub issue explaining the change in behavior and giving a migration recipe. 1. The migration window is at least one release long and is set by the author of the incompatible change. 1. We announce what set of flags we flip with the next release one release in advance. From fa5a99746a24991443181e3c344b8322b6b12f48 Mon Sep 17 00:00:00 2001 From: Jingwen Date: Tue, 15 Jan 2019 09:28:49 +0100 Subject: [PATCH 5/8] Update site/docs/backward-compatibility.md Co-Authored-By: dslomov --- site/docs/backward-compatibility.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/docs/backward-compatibility.md b/site/docs/backward-compatibility.md index 95a24857f7457e..afefab72ef2a6d 100644 --- a/site/docs/backward-compatibility.md +++ b/site/docs/backward-compatibility.md @@ -61,7 +61,7 @@ In other words, during a migration window for an incompatible change `foo`: ## 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+). +marked with an ["incompatible-change" label](https://github.com/bazelbuild/bazel/issues?q=label%3Aincompatible-change). For every incompatible change, the issue specifies: * the name of the flag controlling the incompatible change From 1b0801d78da2ca638c30267360554675bab6dc1d Mon Sep 17 00:00:00 2001 From: Dmitry Lomov Date: Tue, 15 Jan 2019 09:32:31 +0100 Subject: [PATCH 6/8] Review comments --- site/docs/backward-compatibility.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/docs/backward-compatibility.md b/site/docs/backward-compatibility.md index afefab72ef2a6d..c0ed50cc282fcc 100644 --- a/site/docs/backward-compatibility.md +++ b/site/docs/backward-compatibility.md @@ -15,7 +15,7 @@ incompatible and require some changes from Bazel users. 1. For every `--incompatible_*` flag we have a GitHub issue explaining the change in behavior and giving a migration recipe. 1. The migration window is at least one release long and is set by the author of the incompatible change. -1. We announce what set of flags we flip with the next release one release in advance. +1. We announce what set of flags we indend to flip with the next release one release in advance. 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. From 3cf36e66f53469fd2b30f616d1e8b47b6d36f019 Mon Sep 17 00:00:00 2001 From: Dmitry Lomov Date: Wed, 16 Jan 2019 10:40:06 +0100 Subject: [PATCH 7/8] More fixes Change-Id: I58b3296f3a7e079984282d57f05d828a682c3c1f --- site/docs/backward-compatibility.md | 6 ++++++ site/docs/skylark/backward-compatibility.md | 23 ++++----------------- 2 files changed, 10 insertions(+), 19 deletions(-) diff --git a/site/docs/backward-compatibility.md b/site/docs/backward-compatibility.md index c0ed50cc282fcc..edf923b2d7bed8 100644 --- a/site/docs/backward-compatibility.md +++ b/site/docs/backward-compatibility.md @@ -8,6 +8,12 @@ title: Backward Compatibility Bazel is evolving, and we will make changes 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** (e.g. [**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** (e.g. [**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. diff --git a/site/docs/skylark/backward-compatibility.md b/site/docs/skylark/backward-compatibility.md index 8a6d8e7ca1b88e..9edda3bed25e35 100644 --- a/site/docs/skylark/backward-compatibility.md +++ b/site/docs/skylark/backward-compatibility.md @@ -1,31 +1,16 @@ --- layout: documentation -title: Starlark Incompatible CHnages +title: Starlark Incompatible Chnages --- # Backward Compatibility -Backward incompatible changes in Starlark are introduced gradually: +Legacy, partial list of [backward-incompatible changes](../backward-compatibility.md). -1. The backward incompatible change is introduced behind a flag with its - default value set to `false`. -2. In a later release, the flag's default value will be set to `true`. You - can still use the flag to disable the change. -3. Then in a later release, the flag will be removed and you will no longer be - able to disable the change. +Full, authorative list of incompatibvle changes is [GitHub issues with +"incompatible-change" label](https://github.com/bazelbuild/bazel/issues?q=is%3Aissue+label%3Aincompatible-change) -To check if your code will be compatible with future releases you can: - -* Build your code with the flag `--all_incompatible_changes`. This flag - enables all backward incompatible changes, and so you can ensure your code - is compatible with upcoming changes. -* Use boolean flags to enable/disable specific backward incompatible changes. - -## Current backward incompatible changes - -The following are the backward incompatible changes that are implemented and -guarded behind flags in the current release: General Starlark From 0a41e9941e8561e0d6486b668a20cefeb44c0688 Mon Sep 17 00:00:00 2001 From: Dmitry Lomov Date: Wed, 16 Jan 2019 10:52:13 +0100 Subject: [PATCH 8/8] Fixing some more typos. Change-Id: Ib1c98ff4bbb3a999b7ea28ae67445c25fec0d1a0 --- site/docs/skylark/backward-compatibility.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/site/docs/skylark/backward-compatibility.md b/site/docs/skylark/backward-compatibility.md index 9edda3bed25e35..8668844e4bb3de 100644 --- a/site/docs/skylark/backward-compatibility.md +++ b/site/docs/skylark/backward-compatibility.md @@ -1,14 +1,14 @@ --- layout: documentation -title: Starlark Incompatible Chnages +title: Legacy Incompatible Changes List --- -# Backward Compatibility +# Legacy Incompatible Changes List Legacy, partial list of [backward-incompatible changes](../backward-compatibility.md). -Full, authorative list of incompatibvle changes is [GitHub issues with +Full, authorative list of incompatible changes is [GitHub issues with "incompatible-change" label](https://github.com/bazelbuild/bazel/issues?q=is%3Aissue+label%3Aincompatible-change)