Clarify steps for introduction of backward incompatible changes.

PiperOrigin-RevId: 170500919

1 files changed, 54 insertions, 30 deletions

diff --git a/site/docs/skylark/backward-compatibility.md b/site/docs/skylark/backward-compatibility.md
index 6ae198835c..069f5ee351 100644
--- a/site/docs/skylark/backward-compatibility.md
+++ b/site/docs/skylark/backward-compatibility.md
@@ -5,23 +5,47 @@ title: Extensions - Backward compatibility
 
 # Backward compatibility
 
-Bazel is still in Beta and we are going to do breaking changes. As we make
-changes and polish the extension mechanism, old features may be removed and new
-features that are not backwards-compatible may be added.
-
-Each release, new incompatible changes will be behind a flag with its default
-value set to `false`. In later releases, the flag will be enabled by default, or
-the flag will be removed entirely.
-
-To check if your code will be compatible with future releases:
-
-*   build your code with the flag `--all_incompatible_changes`, or
-*   use boolean flags to enable/disable specific incompatible changes.
-
-This following are the planned incompatible changes that are implemented and
-guarded behind flags.
-
-## Set constructor
+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 incompatible changes are introduced gradually:
+
+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.
+
+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 incomaptible 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:
+
+*   [Set constructor](#set-constructor)
+*   [Keyword-only arguments](#keyword-only-arguments)
+*   [Mutating `+=`](#mutating)
+*   [Dictionary concatenation](#dictionary-concatenation)
+*   [Load must appear at top of file](#load-must-appear-at-top-of-file)
+*   [Load argument is a label](#load-argument-is-a-label)
+*   [Top level `if` statements](#top-level-if-statements)
+*   [Comprehensions variables](#comprehensions-variables)
+*   [Depset is no longer iterable](#depset-is-no-longer-iterable)
+*   [String is no longer iterable](#string-is-no-longer-iterable)
+*   [Dictionary literal has no duplicates](#dictionary-literal-has-no-duplicates)
+*   [New actions API](#new-actions-api)
+*   [Checked arithmetic](#checked-arithmetic)
+*   [Descriptive string representations](#descriptive-string-representations)
+
+### Set constructor
 
 We are removing the `set` constructor. Use `depset` instead. `set` and `depset`
 are equivalent, you just need to do search and replace to update the old code.
@@ -33,7 +57,7 @@ We are doing this to reduce confusion between the specialized
 *   Default: `true`
 
 
-## Keyword-only arguments
+### Keyword-only arguments
 
 Keyword-only parameters are parameters that can be called only using their name.
 
@@ -57,7 +81,7 @@ documented).
 *   Default: `true`
 
 
-## Mutating `+=`
+### Mutating `+=`
 
 We are changing `left += right` when `left` is a list. The old behavior is
 equivalent to `left = left + right`, which creates a new list and assigns it to
@@ -80,7 +104,7 @@ issues. The `+=` operator for tuples is unaffected.
 *   Default: `false`
 
 
-## Dictionary concatenation
+### Dictionary concatenation
 
 We are removing the `+` operator on dictionaries. This includes the `+=` form
 where the left-hand side is a dictionary. This is done to improve compatibility
@@ -90,7 +114,7 @@ with Python. A possible workaround is to use the `.update` method instead.
 *   Default: `false`
 
 
-## Load must appear at top of file
+### Load must appear at top of file
 
 Previously, the `load` statement could appear anywhere in a `.bzl` file so long
 as it was at the top level. With this change, for `.bzl` files, `load` must
@@ -100,7 +124,7 @@ appear at the beginning of the file, i.e. before any other non-`load` statement.
 *   Default: `false`
 
 
-## Load argument is a label
+### Load argument is a label
 
 Historically, the first argument of `load` could be a path with an implicit
 `.bzl` suffix. We are going to require that all `load` statements use the label
@@ -115,7 +139,7 @@ load("//path:foo.bzl", "var")  # recommended
 *   Default: `false`
 
 
-## Top level `if` statements
+### Top level `if` statements
 
 This change forbids `if` statements at the top level of `.bzl` files (they are
 already forbidden in `BUILD` files). This change ensures that every global
@@ -126,7 +150,7 @@ that global values cannot be redefined.
 *   Default: `true`
 
 
-## Comprehensions variables
+### Comprehensions variables
 
 This change makes list and dict comprehensions follow Python 3's semantics
 instead of Python 2's. That is, comprehensions have their own local scopes, and
@@ -163,7 +187,7 @@ comprehension.
 *   Default: `true`
 
 
-## Depset is no longer iterable
+### Depset is no longer iterable
 
 When the flag is set to true, `depset` objects are not treated as iterable. If
 you need an iterable, call the `.to_list()` method. This affects `for` loops and
@@ -184,7 +208,7 @@ sorted(deps.to_list())  # recommended
 *   Default: `false`
 
 
-## String is no longer iterable
+### String is no longer iterable
 
 When the flag is set to true, `string` objects are not treated as iterable. This
 affects `for` loops and many functions, e.g. `list`, `tuple`, `min`, `max`,
@@ -213,7 +237,7 @@ for i in range(len(my_string)):
 *   Default: `false`
 
 
-## Dictionary literal has no duplicates
+### Dictionary literal has no duplicates
 
 When the flag is set to true, duplicated keys are not allowed in the dictionary
 literal syntax.
@@ -233,7 +257,7 @@ If you really want to override a value, use a separate statement:
 *   Default: `true`
 
 
-## New actions API
+### New actions API
 
 This change removes the old methods for registering actions within rules, and
 requires that you use the new methods instead. The deprecated methods and their
@@ -254,7 +278,7 @@ replacements are as follows.
 *   Default: `false`
 
 
-## Checked arithmetic
+### Checked arithmetic
 
 When set, arithmetic operations (`+`, `-`, `*`) will fail in case of overflow.
 All integers are stored using signed 32 bits.
@@ -263,7 +287,7 @@ All integers are stored using signed 32 bits.
 *   Default: `true`
 
 
-## Descriptive string representations
+### Descriptive string representations
 
 For certain types of objects (such as `Label`, `File`, and rule contexts), this
 flag changes the string representations returned by `str()` and `repr()` to be