Update incompatible change process on when to close github issue
Previously, we stated that the incompatible flag issue should be closed when the flag is removed from HEAD (instead of flipped). But this doesn't work well because it makes tracking the flag flip harder, which is problematic for two use cases
1) Using the issue as a release blocker. Before cutting a release, we only care if the flag is flipped, not if it's removed.
2) The incompatible flag pipeline should stop test the flag after it's flipped. Keeping the issue open will confuse the pipeline.
Therefore, we update the policy to close the incompatible issue when the flag is flipped, then file another issue to track the removal of the flag.
RELNOTES:
PiperOrigin-RevId: 474320452
Change-Id: Ida825a3c41575a940cc2082f4fc2cfae449a6f03
diff --git a/site/en/contribute/breaking-changes.md b/site/en/contribute/breaking-changes.md
index bbd7df0..40ba33e 100644
--- a/site/en/contribute/breaking-changes.md
+++ b/site/en/contribute/breaking-changes.md
@@ -120,14 +120,17 @@
`RELNOTES[INC]: --incompatible_name_of_flag is flipped to true. See #xyz for
details`
You can include additional information in the rest of the commit description.
-* Use `Work towards #xyz` in the description, so that the GitHub issue gets mentioned
+* Use `Fixes #xyz` in the description, so that the GitHub issue gets closed
when the commit is merged.
* Review and update documentation if needed.
+* File a new issue `#abc` to track the removal of the flag.
## Removing the flag {:#remove-flag}
-After the flag is flipped at HEAD, you can start removing the flag. The Github issue should be closed after the flag is removed from Bazel.
+After the flag is flipped at HEAD, it should be removed from Bazel eventually.
+When you plan to remove the incompatible flag:
* Consider leaving more time for users to migrate if it's a major incompatible change.
-* For the commit that removes the flag, use `Fixes #xyz` in the description
+ Ideally, the flag should be available in at least one major release.
+* For the commit that removes the flag, use `Fixes #abc` in the description
so that the GitHub issue gets closed when the commit is merged.
diff --git a/site/en/release/backward-compatibility.md b/site/en/release/backward-compatibility.md
index b39f440..c169a9f 100644
--- a/site/en/release/backward-compatibility.md
+++ b/site/en/release/backward-compatibility.md
@@ -61,4 +61,4 @@
* Description of the changed functionality
* Migration recipe
-When an incompatible change is ready for migration with Bazel at HEAD (therefore, also with the next Bazel rolling release), it should be marked with the `migration-ready` label. The incompatible change issue is closed when the incompatible flag is removed at HEAD.
+When an incompatible change is ready for migration with Bazel at HEAD (therefore, also with the next Bazel rolling release), it should be marked with the `migration-ready` label. The incompatible change issue is closed when the incompatible flag is flipped at HEAD.
