Update the --incompatible_ flag requirements to use the metadata tag.

Leave the category for now as the generated docs still do not use the new categorization.

PiperOrigin-RevId: 160290297

5 files changed, 118 insertions, 7 deletions

diff --git a/src/main/java/com/google/devtools/build/lib/runtime/AllIncompatibleChangesExpansion.java b/src/main/java/com/google/devtools/build/lib/runtime/AllIncompatibleChangesExpansion.java
index 9e26da0633..3f7a193cd3 100644
--- a/src/main/java/com/google/devtools/build/lib/runtime/AllIncompatibleChangesExpansion.java
+++ b/src/main/java/com/google/devtools/build/lib/runtime/AllIncompatibleChangesExpansion.java
@@ -21,6 +21,7 @@ import com.google.devtools.common.options.IsolatedOptionsData;
 import com.google.devtools.common.options.Option;
 import com.google.devtools.common.options.OptionsBase;
 import com.google.devtools.common.options.OptionsParser;
+import com.google.devtools.common.options.proto.OptionFilters.OptionMetadataTag;
 import java.lang.reflect.Field;
 import java.util.ArrayList;
 import java.util.Map;
@@ -132,6 +133,11 @@ public class AllIncompatibleChangesExpansion implements ExpansionFunction {
     if (!annotation.category().equals(INCOMPATIBLE_CATEGORY)) {
       throw new IllegalArgumentException(prefix + "must have category \"incompatible changes\"");
     }
+    if (!ImmutableList.copyOf(annotation.metadataTags())
+        .contains(OptionMetadataTag.INCOMPATIBLE_CHANGE)) {
+      throw new IllegalArgumentException(
+          prefix + "must have metadata tag \"OptionMetadataTag.INCOMPATIBLE_CHANGE\"");
+    }
     if (!IsolatedOptionsData.isExpansionOption(annotation)) {
       if (!field.getType().equals(Boolean.TYPE)) {
         throw new IllegalArgumentException(
diff --git a/src/main/java/com/google/devtools/build/lib/syntax/SkylarkSemanticsOptions.java b/src/main/java/com/google/devtools/build/lib/syntax/SkylarkSemanticsOptions.java
index 8c69a561b6..1790411655 100644
--- a/src/main/java/com/google/devtools/build/lib/syntax/SkylarkSemanticsOptions.java
+++ b/src/main/java/com/google/devtools/build/lib/syntax/SkylarkSemanticsOptions.java
@@ -20,6 +20,7 @@ import com.google.devtools.common.options.OptionsBase;
 import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions;
 import com.google.devtools.common.options.UsesOnlyCoreTypes;
 import com.google.devtools.common.options.proto.OptionFilters.OptionEffectTag;
+import com.google.devtools.common.options.proto.OptionFilters.OptionMetadataTag;
 import java.io.Serializable;
 
 /**
@@ -53,6 +54,7 @@ public class SkylarkSemanticsOptions extends OptionsBase implements Serializable
     category = "incompatible changes",
     documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
     effectTags = {OptionEffectTag.UNKNOWN},
+    metadataTags = {OptionMetadataTag.INCOMPATIBLE_CHANGE},
     help = "If set to true, disables the deprecated `set` constructor for depsets."
   )
   public boolean incompatibleDisallowSetConstructor;
@@ -63,6 +65,7 @@ public class SkylarkSemanticsOptions extends OptionsBase implements Serializable
     category = "incompatible changes",
     documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
     effectTags = {OptionEffectTag.UNKNOWN},
+    metadataTags = {OptionMetadataTag.INCOMPATIBLE_CHANGE},
     help = "If set to true, disables the keyword-only argument syntax in function definition."
   )
   public boolean incompatibleDisallowKeywordOnlyArgs;
@@ -73,6 +76,7 @@ public class SkylarkSemanticsOptions extends OptionsBase implements Serializable
     category = "incompatible changes",
     documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
     effectTags = {OptionEffectTag.UNKNOWN},
+    metadataTags = {OptionMetadataTag.INCOMPATIBLE_CHANGE},
     help =
         "If set to true, `+=` on lists works like the `extend` method mutating the original "
             + "list. Otherwise it copies the original list without mutating it."
@@ -85,6 +89,7 @@ public class SkylarkSemanticsOptions extends OptionsBase implements Serializable
     category = "incompatible changes",
     documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
     effectTags = {OptionEffectTag.UNKNOWN},
+    metadataTags = {OptionMetadataTag.INCOMPATIBLE_CHANGE},
     help = "If set to true, the `+` becomes disabled for dicts."
   )
   public boolean incompatibleDisallowDictPlus;
@@ -95,6 +100,7 @@ public class SkylarkSemanticsOptions extends OptionsBase implements Serializable
     category = "incompatible changes",
     documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
     effectTags = {OptionEffectTag.UNKNOWN},
+    metadataTags = {OptionMetadataTag.INCOMPATIBLE_CHANGE},
     help =
         "If set to true, all `load` must be called at the top of .bzl files, before any other "
             + "statement."
@@ -107,6 +113,7 @@ public class SkylarkSemanticsOptions extends OptionsBase implements Serializable
     category = "incompatible changes",
     documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
     effectTags = {OptionEffectTag.UNKNOWN},
+    metadataTags = {OptionMetadataTag.INCOMPATIBLE_CHANGE},
     help =
         "If set to true, the first argument of 'load' statements is a label (not a path). "
             + "It must start with '//' or ':'."
@@ -119,6 +126,7 @@ public class SkylarkSemanticsOptions extends OptionsBase implements Serializable
     category = "incompatible changes",
     documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
     effectTags = {OptionEffectTag.UNKNOWN},
+    metadataTags = {OptionMetadataTag.INCOMPATIBLE_CHANGE},
     help =
         "If set to true, 'if' statements are forbidden at the top-level "
             + "(outside a function definition)"
@@ -131,6 +139,7 @@ public class SkylarkSemanticsOptions extends OptionsBase implements Serializable
     category = "incompatible changes",
     documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
     effectTags = {OptionEffectTag.UNKNOWN},
+    metadataTags = {OptionMetadataTag.INCOMPATIBLE_CHANGE},
     help =
         "If set to true, loop variables in a comprehension shadow any existing variable by "
             + "the same name. If the existing variable was declared in the same scope that "
@@ -145,6 +154,7 @@ public class SkylarkSemanticsOptions extends OptionsBase implements Serializable
     category = "incompatible changes",
     documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
     effectTags = {OptionEffectTag.UNKNOWN},
+    metadataTags = {OptionMetadataTag.INCOMPATIBLE_CHANGE},
     help =
         "If set to true, depset type is not iterable. For loops and functions expecting an "
             + "iterable will reject depset objects. Use the `.to_list` method to explicitly "
@@ -158,6 +168,7 @@ public class SkylarkSemanticsOptions extends OptionsBase implements Serializable
     category = "incompatible changes",
     documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
     effectTags = {OptionEffectTag.UNKNOWN},
+    metadataTags = {OptionMetadataTag.INCOMPATIBLE_CHANGE},
     help = "If set to true, the dictionary literal syntax doesn't allow duplicated keys."
   )
   public boolean incompatibleDictLiteralHasNoDuplicates;
diff --git a/src/main/protobuf/option_filters.proto b/src/main/protobuf/option_filters.proto
index 059d414c5c..da614796b6 100644
--- a/src/main/protobuf/option_filters.proto
+++ b/src/main/protobuf/option_filters.proto
@@ -125,9 +125,11 @@ enum OptionMetadataTag {
   // labeled experimental.
   EXPERIMENTAL = 0;
 
-  // This option triggers a breaking change that is off by default, but will be
-  // enabled in the next major Bazel version. Use this option to test your
+  // This option triggers a backwards-incompatible change. It will be off by
+  // default when the option is first introduced, and later switched on by
+  // default on a major Blaze release. Use this option to test your
   // migration readiness or get early access to the feature.
+  // The option may be deprecated some time after the feature's release.
   INCOMPATIBLE_CHANGE = 1;
 
   // This flag is deprecated. It might either no longer have any effect, or
diff --git a/src/test/java/com/google/devtools/build/lib/BUILD b/src/test/java/com/google/devtools/build/lib/BUILD
index 55282d337e..e90994734e 100644
--- a/src/test/java/com/google/devtools/build/lib/BUILD
+++ b/src/test/java/com/google/devtools/build/lib/BUILD
@@ -1040,6 +1040,7 @@ java_test(
         "//src/main/java/com/google/devtools/build/lib/buildeventstream/transports",
         "//src/main/java/com/google/devtools/common/options",
         "//src/main/protobuf:invocation_policy_java_proto",
+        "//src/main/protobuf:option_filters_java_proto",
         "//src/main/protobuf:test_status_java_proto",
         "//third_party:guava",
         "//third_party:junit4",
diff --git a/src/test/java/com/google/devtools/build/lib/runtime/AllIncompatibleChangesExpansionTest.java b/src/test/java/com/google/devtools/build/lib/runtime/AllIncompatibleChangesExpansionTest.java
index 2b3dbaa4c8..7f91d173e0 100644
--- a/src/test/java/com/google/devtools/build/lib/runtime/AllIncompatibleChangesExpansionTest.java
+++ b/src/test/java/com/google/devtools/build/lib/runtime/AllIncompatibleChangesExpansionTest.java
@@ -25,9 +25,12 @@ import com.google.devtools.common.options.ExpansionFunction;
 import com.google.devtools.common.options.InvocationPolicyEnforcer;
 import com.google.devtools.common.options.IsolatedOptionsData;
 import com.google.devtools.common.options.Option;
+import com.google.devtools.common.options.OptionDocumentationCategory;
 import com.google.devtools.common.options.OptionsBase;
 import com.google.devtools.common.options.OptionsParser;
 import com.google.devtools.common.options.OptionsParsingException;
+import com.google.devtools.common.options.proto.OptionFilters.OptionEffectTag;
+import com.google.devtools.common.options.proto.OptionFilters.OptionMetadataTag;
 import java.util.List;
 import org.junit.Test;
 import org.junit.runner.RunWith;
@@ -44,20 +47,35 @@ public class AllIncompatibleChangesExpansionTest {
   public static class ExampleOptions extends OptionsBase {
     @Option(
       name = "all",
+      documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
+      effectTags = {OptionEffectTag.NO_OP},
       defaultValue = "null",
       expansionFunction = AllIncompatibleChangesExpansion.class
     )
     public Void all;
 
-    @Option(name = "X", defaultValue = "false")
+    @Option(
+      name = "X",
+      documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
+      effectTags = {OptionEffectTag.NO_OP},
+      defaultValue = "false"
+    )
     public boolean x;
 
-    @Option(name = "Y", defaultValue = "true")
+    @Option(
+      name = "Y",
+      documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
+      effectTags = {OptionEffectTag.NO_OP},
+      defaultValue = "true"
+    )
     public boolean y;
 
     @Option(
       name = "incompatible_A",
       category = "incompatible changes",
+      metadataTags = {OptionMetadataTag.INCOMPATIBLE_CHANGE},
+      documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
+      effectTags = {OptionEffectTag.NO_OP},
       defaultValue = "false",
       help = "Migrate to A"
     )
@@ -66,6 +84,9 @@ public class AllIncompatibleChangesExpansionTest {
     @Option(
       name = "incompatible_B",
       category = "incompatible changes",
+      metadataTags = {OptionMetadataTag.INCOMPATIBLE_CHANGE},
+      documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
+      effectTags = {OptionEffectTag.NO_OP},
       defaultValue = "false",
       help = "Migrate to B"
     )
@@ -77,6 +98,9 @@ public class AllIncompatibleChangesExpansionTest {
     @Option(
       name = "incompatible_expX",
       category = "incompatible changes",
+      metadataTags = {OptionMetadataTag.INCOMPATIBLE_CHANGE},
+      documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
+      effectTags = {OptionEffectTag.NO_OP},
       defaultValue = "null",
       expansion = {"--X"},
       help = "Start using X"
@@ -94,6 +118,9 @@ public class AllIncompatibleChangesExpansionTest {
     @Option(
       name = "incompatible_expY",
       category = "incompatible changes",
+      metadataTags = {OptionMetadataTag.INCOMPATIBLE_CHANGE},
+      documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
+      effectTags = {OptionEffectTag.NO_OP},
       defaultValue = "null",
       expansionFunction = YExpansion.class,
       help = "Stop using Y"
@@ -196,6 +223,9 @@ public class AllIncompatibleChangesExpansionTest {
     @Option(
       name = "badname",
       category = "incompatible changes",
+      metadataTags = {OptionMetadataTag.INCOMPATIBLE_CHANGE},
+      documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
+      effectTags = {OptionEffectTag.NO_OP},
       defaultValue = "false",
       help = "nohelp"
     )
@@ -210,9 +240,19 @@ public class AllIncompatibleChangesExpansionTest {
             + "starting with \"incompatible_\"");
   }
 
-  /** Dummy comment (linter suppression) */
+  /**
+   * Option with the right prefix and tag, but the wrong "category." The category is deprecated and
+   * this test will be deleted when the option field is removed.
+   */
   public static class BadCategoryOptions extends OptionsBase {
-    @Option(name = "incompatible_bad", category = "badcat", defaultValue = "false", help = "nohelp")
+    @Option(
+      name = "incompatible_bad",
+      metadataTags = {OptionMetadataTag.INCOMPATIBLE_CHANGE},
+      documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
+      effectTags = {OptionEffectTag.NO_OP},
+      defaultValue = "false",
+      help = "nohelp"
+    )
     public boolean bad;
   }
 
@@ -221,11 +261,34 @@ public class AllIncompatibleChangesExpansionTest {
     assertBadness(BadCategoryOptions.class, "must have category \"incompatible changes\"");
   }
 
+  /** Option with the right prefix and "category," but the wrong metadata tag. */
+  public static class BadTagOptions extends OptionsBase {
+    @Option(
+      name = "incompatible_bad",
+      category = "incompatible changes",
+      documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
+      effectTags = {OptionEffectTag.NO_OP},
+      defaultValue = "false",
+      help = "nohelp"
+    )
+    public boolean bad;
+  }
+
+  @Test
+  public void badTag() {
+    assertBadness(
+        BadTagOptions.class,
+        "must have metadata tag \"OptionMetadataTag.INCOMPATIBLE_CHANGE\"");
+  }
+
   /** Dummy comment (linter suppression) */
   public static class BadTypeOptions extends OptionsBase {
     @Option(
       name = "incompatible_bad",
       category = "incompatible changes",
+      metadataTags = {OptionMetadataTag.INCOMPATIBLE_CHANGE},
+      documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
+      effectTags = {OptionEffectTag.NO_OP},
       defaultValue = "0",
       help = "nohelp"
     )
@@ -239,7 +302,14 @@ public class AllIncompatibleChangesExpansionTest {
 
   /** Dummy comment (linter suppression) */
   public static class BadHelpOptions extends OptionsBase {
-    @Option(name = "incompatible_bad", category = "incompatible changes", defaultValue = "false")
+    @Option(
+      name = "incompatible_bad",
+      category = "incompatible changes",
+      metadataTags = {OptionMetadataTag.INCOMPATIBLE_CHANGE},
+      documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
+      effectTags = {OptionEffectTag.NO_OP},
+      defaultValue = "false"
+    )
     public boolean bad;
   }
 
@@ -253,6 +323,9 @@ public class AllIncompatibleChangesExpansionTest {
     @Option(
       name = "incompatible_bad",
       category = "incompatible changes",
+      metadataTags = {OptionMetadataTag.INCOMPATIBLE_CHANGE},
+      documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
+      effectTags = {OptionEffectTag.NO_OP},
       defaultValue = "false",
       help = "nohelp",
       abbrev = 'x'
@@ -270,6 +343,9 @@ public class AllIncompatibleChangesExpansionTest {
     @Option(
       name = "incompatible_bad",
       category = "incompatible changes",
+      metadataTags = {OptionMetadataTag.INCOMPATIBLE_CHANGE},
+      documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
+      effectTags = {OptionEffectTag.NO_OP},
       defaultValue = "false",
       help = "nohelp",
       valueHelp = "x"
@@ -287,6 +363,9 @@ public class AllIncompatibleChangesExpansionTest {
     @Option(
       name = "incompatible_bad",
       category = "incompatible changes",
+      metadataTags = {OptionMetadataTag.INCOMPATIBLE_CHANGE},
+      documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
+      effectTags = {OptionEffectTag.NO_OP},
       defaultValue = "false",
       help = "nohelp",
       converter = Converters.BooleanConverter.class
@@ -304,6 +383,9 @@ public class AllIncompatibleChangesExpansionTest {
     @Option(
       name = "incompatible_bad",
       category = "incompatible changes",
+      metadataTags = {OptionMetadataTag.INCOMPATIBLE_CHANGE},
+      documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
+      effectTags = {OptionEffectTag.NO_OP},
       defaultValue = "null",
       help = "nohelp",
       allowMultiple = true
@@ -321,6 +403,9 @@ public class AllIncompatibleChangesExpansionTest {
     @Option(
       name = "incompatible_bad",
       category = "incompatible changes",
+      metadataTags = {OptionMetadataTag.INCOMPATIBLE_CHANGE},
+      documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
+      effectTags = {OptionEffectTag.NO_OP},
       defaultValue = "false",
       help = "nohelp",
       implicitRequirements = "--x"
@@ -339,6 +424,9 @@ public class AllIncompatibleChangesExpansionTest {
     @Option(
       name = "incompatible_bad",
       category = "incompatible changes",
+      metadataTags = {OptionMetadataTag.INCOMPATIBLE_CHANGE},
+      documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
+      effectTags = {OptionEffectTag.NO_OP},
       defaultValue = "false",
       help = "nohelp",
       oldName = "x"
@@ -356,6 +444,9 @@ public class AllIncompatibleChangesExpansionTest {
     @Option(
       name = "incompatible_bad",
       category = "incompatible changes",
+      metadataTags = {OptionMetadataTag.INCOMPATIBLE_CHANGE},
+      documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
+      effectTags = {OptionEffectTag.NO_OP},
       defaultValue = "false",
       help = "nohelp",
       wrapperOption = true