Add option tagging and categorizing enums.

Begin work of transferring option categorization to a sustainable, documented setup.

DocumentationCategories will replace the existing string category field, and will group flags in generated documentation. Each flag must belong to exactly 1 DocumentationCategory, whichever is most applicable or a new one.

OptionEffectTags will document the effects of tags and will be used for filtering flags. These tags, unlike the categories, should be complete. All options that do affect Bazel's output should be tagged as affecting Bazel's output, for example. This is necessary for them to be useful when trying to isolate the cause of an issue or behavior by allowing irrelevant options to be filtered out. Each flag must have at least 1 intended behavior, so should have 1+ OptionEffectTag. If no effect tag applies, find a general tag that would apply and add it to all relevant options.

OptionMetadataTags will hold information about the flag itself. Information about the lifecycle of a flag, for example, should belong in an OptionMetadataTag. It is useful for filtering, since it describes how trustworthy we might think the flag would be, but does not actually describe the “intent” or “meaning” of a flag. This can be an empty list, but options can also have multiple OptionMetadataTags

All options will be switched from the old "category" field to this new system. A few general OptionsBases are provided as an example.

PiperOrigin-RevId: 160180328

1 files changed, 32 insertions, 8 deletions

diff --git a/src/main/protobuf/BUILD b/src/main/protobuf/BUILD
index 64cbd62f1d..349880bdb8 100644
--- a/src/main/protobuf/BUILD
+++ b/src/main/protobuf/BUILD
@@ -6,21 +6,21 @@ load("//third_party/protobuf/3.2.0:protobuf.bzl", "cc_proto_library", "py_proto_
 load("//third_party/grpc:build_defs.bzl", "java_grpc_library")
 
 FILES = [
+    "android_deploy_info",
+    "apk_manifest",
     "build",
-    "deps",
-    "java_compilation",
+    "bundlemerge",
+    "command_server",
     "crosstool_config",
+    "deps",
     "extra_actions_base",
     "intellij_ide_info",
+    "invocation_policy",
+    "java_compilation",
     "package_manifest",
-    "test_status",
     "plmerge",
-    "bundlemerge",
+    "test_status",
     "worker_protocol",
-    "invocation_policy",
-    "android_deploy_info",
-    "apk_manifest",
-    "command_server",
 ]
 
 [proto_library(
@@ -38,6 +38,29 @@ FILES = [
     deps = [":" + s + "_java_proto"],
 ) for s in FILES]
 
+# This new option tagging method is in flux while being applied to the options
+# in the Bazel code base. The visibility should not be changed to allow external
+# dependencies until the interface has stabilized and can commit to maintaining
+# backwards compatibility for 6 months' time.
+# TODO(bazel-team) Make these visibility:public when the interface is stable.
+proto_library(
+    name = "option_filters_proto",
+    srcs = ["option_filters.proto"],
+    visibility = ["//visibility:private"],
+)
+
+java_proto_library(
+    name = "option_filters_java_proto",
+    visibility = ["//src:__subpackages__"],
+    deps = [":option_filters_proto"],
+)
+
+java_library_srcs(
+    name = "option_filters_java_proto_srcs",
+    visibility = ["//visibility:private"],
+    deps = [":option_filters_java_proto"],
+)
+
 cc_proto_library(
     name = "worker_protocol_cc_proto",
     srcs = ["worker_protocol.proto"],
@@ -73,5 +96,6 @@ filegroup(
     name = "dist_jars",
     srcs = [s + "_java_proto_srcs" for s in FILES] + [
         ":command_server_java_grpc_srcs",
+        ":option_filters_java_proto_srcs",
     ],
 )