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

9 files changed, 429 insertions, 17 deletions

diff --git a/src/main/java/com/google/devtools/build/lib/BUILD b/src/main/java/com/google/devtools/build/lib/BUILD
index ca9f117d3e..c0c72c71ca 100644
--- a/src/main/java/com/google/devtools/build/lib/BUILD
+++ b/src/main/java/com/google/devtools/build/lib/BUILD
@@ -630,6 +630,7 @@ java_library(
         "//src/main/java/com/google/devtools/common/options",
         "//src/main/protobuf:extra_actions_base_java_proto",
         "//src/main/protobuf:invocation_policy_java_proto",
+        "//src/main/protobuf:option_filters_java_proto",
         "//src/main/protobuf:test_status_java_proto",
         "//third_party:auto_value",
         "//third_party:guava",
@@ -1180,6 +1181,7 @@ java_library(
         "//src/main/protobuf:command_server_java_grpc",
         "//src/main/protobuf:command_server_java_proto",
         "//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:joda_time",
diff --git a/src/main/java/com/google/devtools/build/lib/buildtool/BuildRequest.java b/src/main/java/com/google/devtools/build/lib/buildtool/BuildRequest.java
index 41ef44291c..ed9c1f6e9a 100644
--- a/src/main/java/com/google/devtools/build/lib/buildtool/BuildRequest.java
+++ b/src/main/java/com/google/devtools/build/lib/buildtool/BuildRequest.java
@@ -37,11 +37,14 @@ import com.google.devtools.build.lib.vfs.PathFragment;
 import com.google.devtools.common.options.Converters;
 import com.google.devtools.common.options.Converters.RangeConverter;
 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.OptionsClassProvider;
 import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions;
 import com.google.devtools.common.options.OptionsParsingException;
 import com.google.devtools.common.options.OptionsProvider;
+import com.google.devtools.common.options.proto.OptionFilters.OptionEffectTag;
+import com.google.devtools.common.options.proto.OptionFilters.OptionMetadataTag;
 import java.util.ArrayList;
 import java.util.List;
 import java.util.UUID;
@@ -73,6 +76,8 @@ public class BuildRequest implements OptionsClassProvider {
       abbrev = 'j',
       defaultValue = "auto",
       category = "strategy",
+      documentationCategory = OptionDocumentationCategory.EXECUTION_STRATEGY,
+      effectTags = {OptionEffectTag.HOST_MACHINE_RESOURCE_OPTIMIZATIONS, OptionEffectTag.EXECUTION},
       converter = JobsConverter.class,
       help =
           "The number of concurrent jobs to run. 0 means build sequentially."
@@ -89,6 +94,8 @@ public class BuildRequest implements OptionsClassProvider {
       name = "progress_report_interval",
       defaultValue = "0",
       category = "verbosity",
+      documentationCategory = OptionDocumentationCategory.LOGGING,
+      effectTags = {OptionEffectTag.AFFECTS_OUTPUTS},
       converter = ProgressReportIntervalConverter.class,
       help =
           "The number of seconds to wait between two reports on still running jobs. The "
@@ -100,6 +107,8 @@ public class BuildRequest implements OptionsClassProvider {
       name = "explain",
       defaultValue = "null",
       category = "verbosity",
+      documentationCategory = OptionDocumentationCategory.LOGGING,
+      effectTags = {OptionEffectTag.AFFECTS_OUTPUTS},
       converter = OptionsUtils.PathFragmentConverter.class,
       help =
           "Causes the build system to explain each executed step of the "
@@ -111,6 +120,8 @@ public class BuildRequest implements OptionsClassProvider {
       name = "verbose_explanations",
       defaultValue = "false",
       category = "verbosity",
+      documentationCategory = OptionDocumentationCategory.LOGGING,
+      effectTags = {OptionEffectTag.AFFECTS_OUTPUTS},
       help =
           "Increases the verbosity of the explanations issued if --explain is enabled. "
               + "Has no effect if --explain is not enabled."
@@ -122,6 +133,8 @@ public class BuildRequest implements OptionsClassProvider {
       converter = Converters.RegexPatternConverter.class,
       defaultValue = "null",
       category = "flags",
+      documentationCategory = OptionDocumentationCategory.LOGGING,
+      effectTags = {OptionEffectTag.AFFECTS_OUTPUTS},
       help = "Only shows warnings for rules with a name matching the provided regular expression."
     )
     public Pattern outputFilter;
@@ -130,6 +143,8 @@ public class BuildRequest implements OptionsClassProvider {
     @Option(
       name = "dump_makefile",
       defaultValue = "false",
+      effectTags = {OptionEffectTag.NO_OP},
+      metadataTags = {OptionMetadataTag.DEPRECATED},
       optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
       help = "this flag has no effect."
     )
@@ -139,6 +154,8 @@ public class BuildRequest implements OptionsClassProvider {
     @Option(
       name = "dump_action_graph",
       defaultValue = "false",
+      effectTags = {OptionEffectTag.NO_OP},
+      metadataTags = {OptionMetadataTag.DEPRECATED},
       optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
       help = "this flag has no effect."
     )
@@ -149,6 +166,8 @@ public class BuildRequest implements OptionsClassProvider {
       name = "dump_action_graph_for_package",
       allowMultiple = true,
       defaultValue = "",
+      effectTags = {OptionEffectTag.NO_OP},
+      metadataTags = {OptionMetadataTag.DEPRECATED},
       optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
       help = "this flag has no effect."
     )
@@ -158,6 +177,8 @@ public class BuildRequest implements OptionsClassProvider {
     @Option(
       name = "dump_action_graph_with_middlemen",
       defaultValue = "true",
+      effectTags = {OptionEffectTag.NO_OP},
+      metadataTags = {OptionMetadataTag.DEPRECATED},
       optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
       help = "this flag has no effect."
     )
@@ -167,6 +188,8 @@ public class BuildRequest implements OptionsClassProvider {
     @Option(
       name = "dump_providers",
       defaultValue = "false",
+      effectTags = {OptionEffectTag.NO_OP},
+      metadataTags = {OptionMetadataTag.DEPRECATED},
       optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
       help = "This is a no-op."
     )
@@ -176,6 +199,8 @@ public class BuildRequest implements OptionsClassProvider {
     @Option(
       name = "dump_targets",
       defaultValue = "null",
+      effectTags = {OptionEffectTag.NO_OP},
+      metadataTags = {OptionMetadataTag.DEPRECATED},
       optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
       help = "this flag has no effect."
     )
@@ -185,6 +210,8 @@ public class BuildRequest implements OptionsClassProvider {
     @Option(
       name = "dump_host_deps",
       defaultValue = "true",
+      effectTags = {OptionEffectTag.NO_OP},
+      metadataTags = {OptionMetadataTag.DEPRECATED},
       optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
       help = "Deprecated"
     )
@@ -194,6 +221,8 @@ public class BuildRequest implements OptionsClassProvider {
     @Option(
       name = "dump_to_stdout",
       defaultValue = "false",
+      effectTags = {OptionEffectTag.NO_OP},
+      metadataTags = {OptionMetadataTag.DEPRECATED},
       optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
       help = "Deprecated"
     )
@@ -202,6 +231,11 @@ public class BuildRequest implements OptionsClassProvider {
     @Option(
       name = "analyze",
       defaultValue = "true",
+      effectTags = {
+        OptionEffectTag.LOADING_AND_ANALYSIS,
+        OptionEffectTag.EAGERNESS_TO_EXIT,
+        OptionEffectTag.AFFECTS_OUTPUTS
+      },
       optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
       help =
           "Execute the analysis phase; this is the usual behaviour. Specifying --noanalyze causes "
@@ -214,6 +248,12 @@ public class BuildRequest implements OptionsClassProvider {
       name = "build",
       defaultValue = "true",
       category = "what",
+      documentationCategory = OptionDocumentationCategory.OUTPUT_SELECTION,
+      effectTags = {
+        OptionEffectTag.EXECUTION,
+        OptionEffectTag.EAGERNESS_TO_EXIT,
+        OptionEffectTag.AFFECTS_OUTPUTS
+      },
       help =
           "Execute the build; this is the usual behaviour. "
               + "Specifying --nobuild causes the build to stop before executing the build "
@@ -226,6 +266,8 @@ public class BuildRequest implements OptionsClassProvider {
       name = "output_groups",
       converter = Converters.CommaSeparatedOptionListConverter.class,
       allowMultiple = true,
+      documentationCategory = OptionDocumentationCategory.OUTPUT_SELECTION,
+      effectTags = {OptionEffectTag.EXECUTION, OptionEffectTag.AFFECTS_OUTPUTS},
       defaultValue = "",
       help =
           "Specifies which output groups of the top-level targets to build. If omitted, a default "
@@ -239,6 +281,8 @@ public class BuildRequest implements OptionsClassProvider {
       name = "show_result",
       defaultValue = "1",
       category = "verbosity",
+      documentationCategory = OptionDocumentationCategory.LOGGING,
+      effectTags = {OptionEffectTag.AFFECTS_OUTPUTS},
       help =
           "Show the results of the build.  For each target, state whether or not it was brought "
               + "up-to-date, and if so, a list of output files that were built.  The printed files "
@@ -253,6 +297,8 @@ public class BuildRequest implements OptionsClassProvider {
     @Option(
       name = "experimental_show_artifacts",
       defaultValue = "false",
+      documentationCategory = OptionDocumentationCategory.LOGGING,
+      effectTags = {OptionEffectTag.AFFECTS_OUTPUTS},
       optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
       help =
           "Output a list of all top level artifacts produced by this build."
@@ -266,6 +312,8 @@ public class BuildRequest implements OptionsClassProvider {
       name = "announce",
       defaultValue = "false",
       category = "verbosity",
+      documentationCategory = OptionDocumentationCategory.LOGGING,
+      effectTags = {OptionEffectTag.AFFECTS_OUTPUTS},
       help = "Deprecated. No-op.",
       deprecationWarning = "This option is now deprecated and is a no-op"
     )
@@ -275,6 +323,8 @@ public class BuildRequest implements OptionsClassProvider {
       name = "symlink_prefix",
       defaultValue = "null",
       category = "misc",
+      documentationCategory = OptionDocumentationCategory.OUTPUT_PARAMETERS,
+      effectTags = {OptionEffectTag.AFFECTS_OUTPUTS},
       help =
           "The prefix that is prepended to any of the convenience symlinks that are created "
               + "after a build. If '/' is passed, then no symlinks are created and no warning is "
@@ -288,6 +338,9 @@ public class BuildRequest implements OptionsClassProvider {
       allowMultiple = true,
       defaultValue = "",
       category = "semantics",
+      documentationCategory = OptionDocumentationCategory.OUTPUT_PARAMETERS,
+      effectTags = {OptionEffectTag.AFFECTS_OUTPUTS},
+      metadataTags = {OptionMetadataTag.EXPERIMENTAL},
       help =
           "This flag allows specifying multiple target CPUs. If this is specified, "
               + "the --cpu option is ignored."
@@ -298,6 +351,7 @@ public class BuildRequest implements OptionsClassProvider {
       name = "output_tree_tracking",
       oldName = "experimental_output_tree_tracking",
       defaultValue = "true",
+      effectTags = {OptionEffectTag.BAZEL_INTERNAL_CONFIGURATION},
       optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
       help =
           "If set, tell the output service (if any) to track when files in the output "
@@ -311,6 +365,7 @@ public class BuildRequest implements OptionsClassProvider {
       name = "aspects",
       converter = Converters.CommaSeparatedOptionListConverter.class,
       defaultValue = "",
+      documentationCategory = OptionDocumentationCategory.OUTPUT_PARAMETERS,
       allowMultiple = true,
       help =
           "Comma-separated list of aspects to be applied to top-level targets. All aspects "
@@ -318,7 +373,6 @@ public class BuildRequest implements OptionsClassProvider {
               + "the form <bzl-file-label>%<aspect_name>, "
               + "for example '//tools:my_def.bzl%my_aspect', where 'my_aspect' is a top-level "
               + "value from from a file tools/my_def.bzl"
-
     )
     public List<String> aspects;
 
@@ -329,6 +383,11 @@ public class BuildRequest implements OptionsClassProvider {
     @Option(
       name = "use_action_cache",
       defaultValue = "true",
+      documentationCategory = OptionDocumentationCategory.EXECUTION_STRATEGY,
+      effectTags = {
+        OptionEffectTag.BAZEL_INTERNAL_CONFIGURATION,
+        OptionEffectTag.HOST_MACHINE_RESOURCE_OPTIMIZATIONS
+      },
       optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
       help = "Whether to use the action cache"
     )
diff --git a/src/main/java/com/google/devtools/build/lib/runtime/BlazeServerStartupOptions.java b/src/main/java/com/google/devtools/build/lib/runtime/BlazeServerStartupOptions.java
index 02933499d4..8e242f012d 100644
--- a/src/main/java/com/google/devtools/build/lib/runtime/BlazeServerStartupOptions.java
+++ b/src/main/java/com/google/devtools/build/lib/runtime/BlazeServerStartupOptions.java
@@ -18,8 +18,11 @@ import com.google.devtools.build.lib.util.OptionsUtils;
 import com.google.devtools.build.lib.vfs.PathFragment;
 import com.google.devtools.common.options.Converter;
 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.OptionUsageRestrictions;
+import com.google.devtools.common.options.proto.OptionFilters.OptionEffectTag;
+import com.google.devtools.common.options.proto.OptionFilters.OptionMetadataTag;
 import java.util.Map;
 
 /**
@@ -78,6 +81,8 @@ public class BlazeServerStartupOptions extends OptionsBase {
   @Option(
     name = "install_base",
     defaultValue = "", // NOTE: purely decorative!  See class docstring.
+    documentationCategory = OptionDocumentationCategory.BAZEL_CLIENT_OPTIONS,
+    effectTags = {OptionEffectTag.CHANGES_INPUTS, OptionEffectTag.LOSES_INCREMENTAL_STATE},
     optionUsageRestrictions = OptionUsageRestrictions.HIDDEN,
     converter = OptionsUtils.PathFragmentConverter.class,
     help = "This launcher option is intended for use only by tests."
@@ -91,6 +96,11 @@ public class BlazeServerStartupOptions extends OptionsBase {
   @Option(
     name = "install_md5",
     defaultValue = "", // NOTE: purely decorative!  See class docstring.
+    documentationCategory = OptionDocumentationCategory.BAZEL_CLIENT_OPTIONS,
+    effectTags = {
+      OptionEffectTag.LOSES_INCREMENTAL_STATE,
+      OptionEffectTag.BAZEL_MONITORING
+    },
     optionUsageRestrictions = OptionUsageRestrictions.HIDDEN,
     help = "This launcher option is intended for use only by tests."
   )
@@ -105,6 +115,8 @@ public class BlazeServerStartupOptions extends OptionsBase {
     name = "output_base",
     defaultValue = "null", // NOTE: purely decorative!  See class docstring.
     category = "server startup",
+    documentationCategory = OptionDocumentationCategory.BAZEL_CLIENT_OPTIONS,
+    effectTags = {OptionEffectTag.AFFECTS_OUTPUTS, OptionEffectTag.LOSES_INCREMENTAL_STATE},
     converter = OptionsUtils.PathFragmentConverter.class,
     valueHelp = "<path>",
     help =
@@ -128,6 +140,8 @@ public class BlazeServerStartupOptions extends OptionsBase {
     name = "output_user_root",
     defaultValue = "null", // NOTE: purely decorative!  See class docstring.
     category = "server startup",
+    documentationCategory = OptionDocumentationCategory.BAZEL_CLIENT_OPTIONS,
+    effectTags = {OptionEffectTag.AFFECTS_OUTPUTS, OptionEffectTag.LOSES_INCREMENTAL_STATE},
     converter = OptionsUtils.PathFragmentConverter.class,
     valueHelp = "<path>",
     help =
@@ -140,6 +154,8 @@ public class BlazeServerStartupOptions extends OptionsBase {
   @Option(
     name = "workspace_directory",
     defaultValue = "",
+    documentationCategory = OptionDocumentationCategory.BAZEL_CLIENT_OPTIONS,
+    effectTags = {OptionEffectTag.CHANGES_INPUTS, OptionEffectTag.LOSES_INCREMENTAL_STATE},
     optionUsageRestrictions = OptionUsageRestrictions.HIDDEN,
     converter = OptionsUtils.PathFragmentConverter.class,
     help =
@@ -152,6 +168,8 @@ public class BlazeServerStartupOptions extends OptionsBase {
     name = "max_idle_secs",
     defaultValue = "" + (3 * 3600), // NOTE: purely decorative!  See class docstring.
     category = "server startup",
+    documentationCategory = OptionDocumentationCategory.BAZEL_CLIENT_OPTIONS,
+    effectTags = {OptionEffectTag.EAGERNESS_TO_EXIT, OptionEffectTag.LOSES_INCREMENTAL_STATE},
     valueHelp = "<integer>",
     help =
         "The number of seconds the build server will wait idling before shutting down. Zero "
@@ -163,6 +181,11 @@ public class BlazeServerStartupOptions extends OptionsBase {
     name = "batch",
     defaultValue = "false", // NOTE: purely decorative!  See class docstring.
     category = "server startup",
+    documentationCategory = OptionDocumentationCategory.BAZEL_CLIENT_OPTIONS,
+    effectTags = {
+      OptionEffectTag.LOSES_INCREMENTAL_STATE,
+      OptionEffectTag.BAZEL_INTERNAL_CONFIGURATION
+    },
     help =
         "If set, Blaze will be run as just a client process without a server, instead of in "
             + "the standard client/server mode."
@@ -173,6 +196,8 @@ public class BlazeServerStartupOptions extends OptionsBase {
     name = "deep_execroot",
     defaultValue = "true", // NOTE: purely decorative!  See class docstring.
     category = "server startup",
+    documentationCategory = OptionDocumentationCategory.BAZEL_CLIENT_OPTIONS,
+    effectTags = {OptionEffectTag.LOSES_INCREMENTAL_STATE, OptionEffectTag.EXECUTION},
     help =
         "If set, the execution root will be under $OUTPUT_BASE/execroot instead of "
             + "$OUTPUT_BASE."
@@ -183,6 +208,8 @@ public class BlazeServerStartupOptions extends OptionsBase {
     name = "experimental_oom_more_eagerly",
     defaultValue = "false", // NOTE: purely decorative!  See class docstring.
     category = "server startup",
+    documentationCategory = OptionDocumentationCategory.BAZEL_CLIENT_OPTIONS,
+    effectTags = {OptionEffectTag.LOSES_INCREMENTAL_STATE, OptionEffectTag.EAGERNESS_TO_EXIT},
     help =
         "If set, attempt to detect Java heap OOM conditions and exit before thrashing. Only "
             + "honored when --batch is also passed. In some cases, builds that previously "
@@ -194,6 +221,8 @@ public class BlazeServerStartupOptions extends OptionsBase {
     name = "experimental_oom_more_eagerly_threshold",
     defaultValue = "100", // NOTE: purely decorative!  See class docstring.
     category = "server startup",
+    documentationCategory = OptionDocumentationCategory.BAZEL_CLIENT_OPTIONS,
+    effectTags = {OptionEffectTag.LOSES_INCREMENTAL_STATE, OptionEffectTag.EAGERNESS_TO_EXIT},
     help =
         "If this flag is set, Blaze will OOM if, after two full GC's, more than this "
             + "percentage of the (old gen) heap is still occupied."
@@ -204,6 +233,8 @@ public class BlazeServerStartupOptions extends OptionsBase {
     name = "block_for_lock",
     defaultValue = "true", // NOTE: purely decorative!  See class docstring.
     category = "server startup",
+    documentationCategory = OptionDocumentationCategory.BAZEL_CLIENT_OPTIONS,
+    effectTags = {OptionEffectTag.EAGERNESS_TO_EXIT},
     help =
         "When --noblock_for_lock is passed, Blaze does not wait for a running command to "
             + "complete, but instead exits immediately."
@@ -214,6 +245,8 @@ public class BlazeServerStartupOptions extends OptionsBase {
     name = "io_nice_level",
     defaultValue = "-1", // NOTE: purely decorative!
     category = "server startup",
+    documentationCategory = OptionDocumentationCategory.BAZEL_CLIENT_OPTIONS,
+    effectTags = {OptionEffectTag.HOST_MACHINE_RESOURCE_OPTIMIZATIONS},
     valueHelp = "{-1,0,1,2,3,4,5,6,7}",
     help =
         "Only on Linux; set a level from 0-7 for best-effort IO scheduling using the "
@@ -227,6 +260,8 @@ public class BlazeServerStartupOptions extends OptionsBase {
     name = "batch_cpu_scheduling",
     defaultValue = "false", // NOTE: purely decorative!
     category = "server startup",
+    documentationCategory = OptionDocumentationCategory.BAZEL_CLIENT_OPTIONS,
+    effectTags = {OptionEffectTag.HOST_MACHINE_RESOURCE_OPTIMIZATIONS},
     help =
         "Only on Linux; use 'batch' CPU scheduling for Blaze. This policy is useful for "
             + "workloads that are non-interactive, but do not want to lower their nice value. "
@@ -238,6 +273,8 @@ public class BlazeServerStartupOptions extends OptionsBase {
     name = "blazerc",
     defaultValue = "null", // NOTE: purely decorative!
     category = "misc",
+    documentationCategory = OptionDocumentationCategory.BAZEL_CLIENT_OPTIONS,
+    effectTags = {OptionEffectTag.CHANGES_INPUTS},
     valueHelp = "<path>",
     help =
         "The location of the .%{product}rc file containing default values of "
@@ -252,6 +289,8 @@ public class BlazeServerStartupOptions extends OptionsBase {
     name = "master_blazerc",
     defaultValue = "true", // NOTE: purely decorative!
     category = "misc",
+    documentationCategory = OptionDocumentationCategory.BAZEL_CLIENT_OPTIONS,
+    effectTags = {OptionEffectTag.CHANGES_INPUTS},
     help = "If this option is false, the master %{product}rc next to the binary is not read."
   )
   public boolean masterBlazerc;
@@ -260,6 +299,7 @@ public class BlazeServerStartupOptions extends OptionsBase {
     name = "fatal_event_bus_exceptions",
     defaultValue = "false", // NOTE: purely decorative!
     optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+    effectTags = {OptionEffectTag.EAGERNESS_TO_EXIT, OptionEffectTag.LOSES_INCREMENTAL_STATE},
     help = "Whether or not to exit if an exception is thrown by an internal EventBus handler."
   )
   public boolean fatalEventBusExceptions;
@@ -268,6 +308,8 @@ public class BlazeServerStartupOptions extends OptionsBase {
     name = "option_sources",
     converter = OptionSourcesConverter.class,
     defaultValue = "",
+    documentationCategory = OptionDocumentationCategory.BAZEL_CLIENT_OPTIONS,
+    effectTags = {OptionEffectTag.AFFECTS_OUTPUTS},
     optionUsageRestrictions = OptionUsageRestrictions.HIDDEN,
     help = ""
   )
@@ -279,6 +321,8 @@ public class BlazeServerStartupOptions extends OptionsBase {
     name = "watchfs",
     defaultValue = "false",
     category = "server startup",
+    documentationCategory = OptionDocumentationCategory.BAZEL_CLIENT_OPTIONS,
+    metadataTags = OptionMetadataTag.DEPRECATED,
     help =
         "If true, %{product} tries to use the operating system's file watch service for local "
             + "changes instead of scanning every file for a change."
@@ -288,6 +332,8 @@ public class BlazeServerStartupOptions extends OptionsBase {
   @Option(
     name = "invocation_policy",
     defaultValue = "",
+    documentationCategory = OptionDocumentationCategory.BAZEL_CLIENT_OPTIONS,
+    effectTags = {OptionEffectTag.CHANGES_INPUTS},
     optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
     help =
         "A base64-encoded-binary-serialized or text-formated "
@@ -299,6 +345,11 @@ public class BlazeServerStartupOptions extends OptionsBase {
   @Option(
     name = "command_port",
     defaultValue = "0",
+    documentationCategory = OptionDocumentationCategory.BAZEL_CLIENT_OPTIONS,
+    effectTags = {
+      OptionEffectTag.LOSES_INCREMENTAL_STATE,
+      OptionEffectTag.BAZEL_INTERNAL_CONFIGURATION
+    },
     optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
     help = "Port to start up the gRPC command server on. If 0, let the kernel choose."
   )
@@ -307,6 +358,12 @@ public class BlazeServerStartupOptions extends OptionsBase {
   @Option(
     name = "product_name",
     defaultValue = "bazel", // NOTE: purely decorative!
+    documentationCategory = OptionDocumentationCategory.BAZEL_CLIENT_OPTIONS,
+    effectTags = {
+      OptionEffectTag.LOSES_INCREMENTAL_STATE,
+      OptionEffectTag.AFFECTS_OUTPUTS,
+      OptionEffectTag.BAZEL_MONITORING
+    },
     optionUsageRestrictions = OptionUsageRestrictions.HIDDEN,
     help =
         "The name of the build system. It is used as part of the name of the generated "
@@ -319,6 +376,8 @@ public class BlazeServerStartupOptions extends OptionsBase {
     name = "exoblaze",
     defaultValue = "false",
     category = "server startup",
+    documentationCategory = OptionDocumentationCategory.BAZEL_CLIENT_OPTIONS,
+    effectTags = {OptionEffectTag.LOSES_INCREMENTAL_STATE},
     help = "If true, Blaze runs as Exoblaze"
   )
   public boolean exoblaze;
@@ -327,6 +386,8 @@ public class BlazeServerStartupOptions extends OptionsBase {
   @Option(
     name = "write_command_log",
     defaultValue = "true",
+    documentationCategory = OptionDocumentationCategory.BAZEL_CLIENT_OPTIONS,
+    effectTags = {OptionEffectTag.AFFECTS_OUTPUTS, OptionEffectTag.LOSES_INCREMENTAL_STATE},
     optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
     help = "Whether or not to write the command.log file"
   )
@@ -336,6 +397,8 @@ public class BlazeServerStartupOptions extends OptionsBase {
     name = "client_debug",
     defaultValue = "false", // NOTE: purely decorative!
     category = "server startup",
+    documentationCategory = OptionDocumentationCategory.BAZEL_CLIENT_OPTIONS,
+    effectTags = {OptionEffectTag.AFFECTS_OUTPUTS, OptionEffectTag.BAZEL_MONITORING},
     help = "If true, log debug information from the client to stderr"
   )
   public boolean clientDebug;
@@ -344,6 +407,8 @@ public class BlazeServerStartupOptions extends OptionsBase {
     name = "connect_timeout_secs",
     defaultValue = "10",
     category = "server startup",
+    documentationCategory = OptionDocumentationCategory.BAZEL_CLIENT_OPTIONS,
+    effectTags = {OptionEffectTag.BAZEL_INTERNAL_CONFIGURATION},
     help = "The amount of time the client waits for each attempt to connect to the server"
   )
   public int connectTimeoutSecs;
diff --git a/src/main/java/com/google/devtools/build/lib/runtime/CommonCommandOptions.java b/src/main/java/com/google/devtools/build/lib/runtime/CommonCommandOptions.java
index 97bec45979..bb784a8b06 100644
--- a/src/main/java/com/google/devtools/build/lib/runtime/CommonCommandOptions.java
+++ b/src/main/java/com/google/devtools/build/lib/runtime/CommonCommandOptions.java
@@ -18,9 +18,12 @@ import com.google.devtools.build.lib.vfs.PathFragment;
 import com.google.devtools.common.options.Converter;
 import com.google.devtools.common.options.Converters;
 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.OptionUsageRestrictions;
 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 java.util.Map;
 import java.util.logging.Level;
@@ -97,12 +100,13 @@ public class CommonCommandOptions extends OptionsBase {
     }
   }
 
-
   // To create a new incompatible change, see the javadoc for AllIncompatibleChangesExpansion.
   @Option(
     name = "all_incompatible_changes",
     defaultValue = "null",
     category = "misc",
+    effectTags = {OptionEffectTag.UNKNOWN},
+    metadataTags = {OptionMetadataTag.INCOMPATIBLE_CHANGE},
     expansionFunction = AllIncompatibleChangesExpansion.class,
     help =
         "Enables all options of the form --incompatible_*. Use this option to find places where "
@@ -114,6 +118,7 @@ public class CommonCommandOptions extends OptionsBase {
     name = "config",
     defaultValue = "",
     category = "misc",
+    effectTags = {OptionEffectTag.UNKNOWN},
     allowMultiple = true,
     help =
         "Selects additional config sections from the rc files; for every <command>, it "
@@ -129,6 +134,8 @@ public class CommonCommandOptions extends OptionsBase {
     name = "logging",
     defaultValue = "3", // Level.INFO
     category = "verbosity",
+    documentationCategory = OptionDocumentationCategory.LOGGING,
+    effectTags = {OptionEffectTag.AFFECTS_OUTPUTS},
     converter = Converters.LogLevelConverter.class,
     help = "The logging level."
   )
@@ -138,16 +145,19 @@ public class CommonCommandOptions extends OptionsBase {
     name = "client_env",
     defaultValue = "",
     optionUsageRestrictions = OptionUsageRestrictions.HIDDEN,
+    effectTags = {OptionEffectTag.CHANGES_INPUTS},
     converter = Converters.AssignmentConverter.class,
     allowMultiple = true,
     help = "A system-generated parameter which specifies the client's environment"
   )
   public List<Map.Entry<String, String>> clientEnv;
 
+  @Deprecated
   @Option(
     name = "ignore_client_env",
     defaultValue = "false",
     optionUsageRestrictions = OptionUsageRestrictions.HIDDEN,
+    metadataTags = OptionMetadataTag.DEPRECATED,
     deprecationWarning = "Deprecated, no-op.",
     help = "Deprecated, no-op."
   )
@@ -159,6 +169,7 @@ public class CommonCommandOptions extends OptionsBase {
     name = "client_cwd",
     defaultValue = "",
     optionUsageRestrictions = OptionUsageRestrictions.HIDDEN,
+    effectTags = {OptionEffectTag.CHANGES_INPUTS},
     converter = OptionsUtils.PathFragmentConverter.class,
     help = "A system-generated parameter which specifies the client's working directory"
   )
@@ -168,6 +179,8 @@ public class CommonCommandOptions extends OptionsBase {
     name = "announce_rc",
     defaultValue = "false",
     category = "verbosity",
+    documentationCategory = OptionDocumentationCategory.LOGGING,
+    effectTags = {OptionEffectTag.AFFECTS_OUTPUTS},
     help = "Whether to announce rc options."
   )
   public boolean announceRcOptions;
@@ -181,6 +194,7 @@ public class CommonCommandOptions extends OptionsBase {
     name = "default_override",
     defaultValue = "",
     allowMultiple = true,
+    effectTags = {OptionEffectTag.CHANGES_INPUTS},
     optionUsageRestrictions = OptionUsageRestrictions.HIDDEN,
     converter = OptionOverrideConverter.class,
     help = ""
@@ -192,6 +206,7 @@ public class CommonCommandOptions extends OptionsBase {
     name = "rc_source",
     defaultValue = "",
     allowMultiple = true,
+    effectTags = {OptionEffectTag.CHANGES_INPUTS},
     optionUsageRestrictions = OptionUsageRestrictions.HIDDEN,
     help = ""
   )
@@ -200,6 +215,7 @@ public class CommonCommandOptions extends OptionsBase {
   @Option(
     name = "always_profile_slow_operations",
     defaultValue = "true",
+    effectTags = {OptionEffectTag.AFFECTS_OUTPUTS, OptionEffectTag.BAZEL_INTERNAL_CONFIGURATION},
     optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
     help = "Whether profiling slow operations is always turned on"
   )
@@ -209,6 +225,7 @@ public class CommonCommandOptions extends OptionsBase {
     name = "allow_undefined_configs",
     defaultValue = "true",
     category = "flags",
+    effectTags = {OptionEffectTag.EAGERNESS_TO_EXIT},
     help = "Do not throw an error when the config is not defined."
   )
   public boolean allowUndefinedConfigs;
@@ -217,6 +234,8 @@ public class CommonCommandOptions extends OptionsBase {
     name = "profile",
     defaultValue = "null",
     category = "misc",
+    documentationCategory = OptionDocumentationCategory.LOGGING,
+    effectTags = {OptionEffectTag.AFFECTS_OUTPUTS, OptionEffectTag.BAZEL_MONITORING},
     converter = OptionsUtils.PathFragmentConverter.class,
     help =
         "If set, profile Blaze and write data to the specified "
@@ -227,6 +246,8 @@ public class CommonCommandOptions extends OptionsBase {
   @Option(
     name = "record_full_profiler_data",
     defaultValue = "false",
+    documentationCategory = OptionDocumentationCategory.LOGGING,
+    effectTags = {OptionEffectTag.AFFECTS_OUTPUTS, OptionEffectTag.BAZEL_MONITORING},
     optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
     help =
         "By default, Blaze profiler will record only aggregated data for fast but numerous "
@@ -239,15 +260,19 @@ public class CommonCommandOptions extends OptionsBase {
   @Option(
     name = "memory_profile",
     defaultValue = "null",
+    documentationCategory = OptionDocumentationCategory.LOGGING,
+    effectTags = {OptionEffectTag.AFFECTS_OUTPUTS, OptionEffectTag.BAZEL_MONITORING},
     optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
     converter = OptionsUtils.PathFragmentConverter.class,
-    help = "If set, write memory usage data to the specified " + "file at phase ends."
+    help = "If set, write memory usage data to the specified file at phase ends."
   )
   public PathFragment memoryProfilePath;
 
+  @Deprecated
   @Option(
     name = "gc_watchdog",
     defaultValue = "false",
+    metadataTags = {OptionMetadataTag.DEPRECATED},
     optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
     deprecationWarning = "Ignoring: this option is no longer supported",
     help = "Deprecated."
@@ -257,6 +282,8 @@ public class CommonCommandOptions extends OptionsBase {
   @Option(
     name = "startup_time",
     defaultValue = "0",
+    documentationCategory = OptionDocumentationCategory.LOGGING,
+    effectTags = {OptionEffectTag.AFFECTS_OUTPUTS, OptionEffectTag.BAZEL_MONITORING},
     optionUsageRestrictions = OptionUsageRestrictions.HIDDEN,
     help = "The time in ms the launcher spends before sending the request to the blaze server."
   )
@@ -265,6 +292,8 @@ public class CommonCommandOptions extends OptionsBase {
   @Option(
     name = "extract_data_time",
     defaultValue = "0",
+    documentationCategory = OptionDocumentationCategory.LOGGING,
+    effectTags = {OptionEffectTag.AFFECTS_OUTPUTS, OptionEffectTag.BAZEL_MONITORING},
     optionUsageRestrictions = OptionUsageRestrictions.HIDDEN,
     help = "The time in ms spent on extracting the new blaze version."
   )
@@ -273,6 +302,8 @@ public class CommonCommandOptions extends OptionsBase {
   @Option(
     name = "command_wait_time",
     defaultValue = "0",
+    documentationCategory = OptionDocumentationCategory.LOGGING,
+    effectTags = {OptionEffectTag.AFFECTS_OUTPUTS, OptionEffectTag.BAZEL_MONITORING},
     optionUsageRestrictions = OptionUsageRestrictions.HIDDEN,
     help = "The time in ms a command had to wait on a busy Blaze server process."
   )
@@ -282,6 +313,8 @@ public class CommonCommandOptions extends OptionsBase {
     name = "tool_tag",
     defaultValue = "",
     category = "misc",
+    documentationCategory = OptionDocumentationCategory.LOGGING,
+    effectTags = {OptionEffectTag.AFFECTS_OUTPUTS, OptionEffectTag.BAZEL_MONITORING},
     help = "A tool name to attribute this Blaze invocation to."
   )
   public String toolTag;
@@ -289,6 +322,8 @@ public class CommonCommandOptions extends OptionsBase {
   @Option(
     name = "restart_reason",
     defaultValue = "no_restart",
+    documentationCategory = OptionDocumentationCategory.LOGGING,
+    effectTags = {OptionEffectTag.AFFECTS_OUTPUTS, OptionEffectTag.BAZEL_MONITORING},
     optionUsageRestrictions = OptionUsageRestrictions.HIDDEN,
     help = "The reason for the server restart."
   )
@@ -297,6 +332,8 @@ public class CommonCommandOptions extends OptionsBase {
   @Option(
     name = "binary_path",
     defaultValue = "",
+    documentationCategory = OptionDocumentationCategory.LOGGING,
+    effectTags = {OptionEffectTag.AFFECTS_OUTPUTS, OptionEffectTag.BAZEL_MONITORING},
     optionUsageRestrictions = OptionUsageRestrictions.HIDDEN,
     help = "The absolute path of the blaze binary."
   )
@@ -305,6 +342,8 @@ public class CommonCommandOptions extends OptionsBase {
   @Option(
     name = "experimental_allow_project_files",
     defaultValue = "false",
+    effectTags = {OptionEffectTag.CHANGES_INPUTS},
+    metadataTags = {OptionMetadataTag.EXPERIMENTAL},
     optionUsageRestrictions = OptionUsageRestrictions.HIDDEN,
     help = "Enable processing of +<file> parameters."
   )
@@ -313,11 +352,11 @@ public class CommonCommandOptions extends OptionsBase {
   @Option(
     name = "block_for_lock",
     defaultValue = "true",
+    effectTags = {OptionEffectTag.BAZEL_INTERNAL_CONFIGURATION},
     optionUsageRestrictions = OptionUsageRestrictions.HIDDEN,
     help =
         "If set (the default), a command will block if there is another one running. If "
             + "unset, these commands will immediately return with an error."
   )
   public boolean blockForLock;
-
 }
diff --git a/src/main/java/com/google/devtools/common/options/BUILD b/src/main/java/com/google/devtools/common/options/BUILD
index 45cdf205b0..ccea13d237 100644
--- a/src/main/java/com/google/devtools/common/options/BUILD
+++ b/src/main/java/com/google/devtools/common/options/BUILD
@@ -8,6 +8,7 @@ java_library(
     srcs = glob(["*.java"]),
     deps = [
         "//src/main/protobuf:invocation_policy_java_proto",
+        "//src/main/protobuf:option_filters_java_proto",
         "//third_party:guava",
         "//third_party:jsr305",
         "//third_party/protobuf:protobuf_java",
diff --git a/src/main/java/com/google/devtools/common/options/Option.java b/src/main/java/com/google/devtools/common/options/Option.java
index e040046624..7489bd668d 100644
--- a/src/main/java/com/google/devtools/common/options/Option.java
+++ b/src/main/java/com/google/devtools/common/options/Option.java
@@ -14,6 +14,8 @@
 package com.google.devtools.common.options;
 
 import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions;
+import com.google.devtools.common.options.proto.OptionFilters.OptionEffectTag;
+import com.google.devtools.common.options.proto.OptionFilters.OptionMetadataTag;
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
@@ -72,11 +74,21 @@ public @interface Option {
   String defaultValue();
 
   /**
-   * A string describing the role of the option. Some existing categories are "input," "output,"
-   * "config," "semantics," and "strategy," among others.
+   * This category field is deprecated. Bazel is in the process of migrating all options to use the
+   * better defined enums in OptionDocumentationCategory and the tags in the option_filters.proto
+   * file. It will still be used for the usage documentation until a sufficient proportion of
+   * options are using the new system.
    *
-   * <p>The category of options that this belongs to dictates how options are grouped by {@link
-   * OptionsParser#describeOptions}, for the usage documentation.
+   * <p>Please leave the old category field in existing options to minimize disruption to the Help
+   * output during the transition period. All uses of this field will be removed when transition is
+   * complete. This category field has no effect on the other fields below, having both set is not a
+   * problem.
+   */
+  @Deprecated
+  String category() default "misc";
+
+  /**
+   * Grouping categories used for usage documentation. See the enum's definition for details.
    *
    * <p>For undocumented flags that aren't listed anywhere, this is currently a no-op. Feel free to
    * set the value that it would have if it were documented, which might be helpful if a flag is
@@ -86,7 +98,27 @@ public @interface Option {
    * <p>For hidden or internal options, use the category field only if it is helpful for yourself or
    * other Bazel developers.
    */
-  String category() default "misc";
+  OptionDocumentationCategory documentationCategory() default
+      OptionDocumentationCategory.UNCATEGORIZED;
+
+  /**
+   * Tag about the intent or effect of this option. Unless this option is a no-op (and the reason
+   * for this should be documented) all options should have some effect, so this needs to have at
+   * least one value.
+   *
+   * <p>No option should list NO_OP_OR_UNKNOWN with other effects listed, but all other combinations
+   * are allowed.
+   */
+  OptionEffectTag[] effectTags() default {OptionEffectTag.UNKNOWN};
+
+  /**
+   * Tag about the state of this option, such as if it gates an experimental feature, or is
+   * deprecated.
+   *
+   * <p>If one or more of the OptionMetadataTag values apply, please include, but otherwise, this
+   * list can be left blank.
+   */
+  OptionMetadataTag[] metadataTags() default {};
 
   /**
    * Options have multiple uses, some flags, some not. For user-visible flags, they are
diff --git a/src/main/java/com/google/devtools/common/options/OptionDocumentationCategory.java b/src/main/java/com/google/devtools/common/options/OptionDocumentationCategory.java
new file mode 100644
index 0000000000..eb39871ca6
--- /dev/null
+++ b/src/main/java/com/google/devtools/common/options/OptionDocumentationCategory.java
@@ -0,0 +1,54 @@
+// Copyright 2017 The Bazel Authors. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//    http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+package com.google.devtools.common.options;
+
+/**
+ * These categories are used to logically group options in generated documentation, both the command
+ * line output for the standard HelpCommand and the html output used for command-line-reference on
+ * the website.
+ *
+ * <p>Grouping things is only a useful exercise if the group includes multiple units. Please only
+ * add categories that group a useful subset of options. (>2, <200, let's say)
+ */
+public enum OptionDocumentationCategory {
+  /**
+   * A category to aid transition, to make it obvious that an option needs to be categorized. Note:
+   * Do NOT add this to new flags!
+   */
+  UNCATEGORIZED,
+
+  /**
+   * Startup options appear before the command and are parsed by the client. Changing them may cause
+   * a server restart, see OptionEffectTag.LOSES_INCREMENTAL_STATE.
+   */
+  BAZEL_CLIENT_OPTIONS,
+
+  /** This option's primary purpose is to affect the verbosity, format or location of logging. */
+  LOGGING,
+
+  /** This option deals with how to go about executing the build. */
+  EXECUTION_STRATEGY,
+
+  /**
+   * This option lets a user specify WHICH output they wish the command to have. It might be a
+   * selective filter on the outputs, or a blanket on/off switch.
+   */
+  OUTPUT_SELECTION,
+
+  /**
+   * This option lets a user configure the outputs. Unlike OUTPUT_SELECTION, which specifies whether
+   * or not an output is built, this specifies qualities of the output.
+   */
+  OUTPUT_PARAMETERS,
+}
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",
     ],
 )
diff --git a/src/main/protobuf/option_filters.proto b/src/main/protobuf/option_filters.proto
new file mode 100644
index 0000000000..059d414c5c
--- /dev/null
+++ b/src/main/protobuf/option_filters.proto
@@ -0,0 +1,136 @@
+// Copyright 2017 The Bazel Authors. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//    http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+syntax = "proto3";
+package options;
+
+option java_package = "com.google.devtools.common.options.proto";
+
+// IMPORTANT NOTE: Changing this proto has specific compatibility requirements.
+// ** Waved during the transition phase **
+//    This enum is not yet depended on externally and none of these constraints
+//    matter until that flip is switched.
+// TODO(bazel-team) Remove the wave of compatibility requirements after the
+// transition period is over.
+//
+// These tags are used for flag filtering. They are consumed by tools that
+// process bazel's output, and for this reason must be kept backwards compatible
+// until the build horizon has passed.
+// - To add a new tag, add it here and to all flags it applies to. If you cannot
+//   do this in a single change, mark it as "deprecated" until it has been
+//   applied everywhere. Once it can be relied upon, remove the deprecation
+//   mark.
+// - To remove a tag, remove it from all flags and mark it as deprecated for 6
+//   months before removing it entirely from the list below.
+// - To change the intent of a tag (i.e. to tighten or loosen its definition),
+//   make sure that the new scope doesn't include untagged options or exclude
+//   options that still have this tag. Please try not to do this.
+//   Create a new value and deprecate the old one instead, to avoid confusion.
+
+// These tags should describe the intent and effects of option.
+//
+// These will be used for filtering noise in long and complex command-lines, to
+// help provide an overview of which options were likely to have an effect on an
+// issue. This would be mostly useful while debugging, to help identify a
+// command line capable of reproducing an error, so the lists of options tagged
+// with each EffectTag should be as close to complete and correct as we can
+// keep them.
+enum OptionEffectTag {
+  // This option's effect or intent is unknown.
+  //
+  // Please do not use this value for new flags. This is meant to aid transition
+  // and for a very specific set of flags that actually have unknown effect,
+  // such as --config and --all_incompatible_changes, where the effect depends
+  // on what other options are triggered.
+  UNKNOWN = 0;
+
+  // This flag has literally no effect. Kept here for completeness and for
+  // deprecated flags. No new flag should set this tag.
+  NO_OP = 1;
+
+  // Using this option causes blaze to lose potentially significant incremental
+  // state, which may make this or following builds slower. State could be lost
+  // due to a server restart or to invalidation of a large part of the
+  // dependency graph.
+  LOSES_INCREMENTAL_STATE = 2;
+
+  // This option affects the inputs to the command. For example, it might affect
+  // Bazel's interaction with repository versions, or be a meta-option that
+  // affects the options set for a given invocation.
+  //
+  // Yes, all options are technically inputs, but only options that affect
+  // inputs other than itself should be tagged.
+  CHANGES_INPUTS = 3;
+
+  // This option affects bazel's outputs. Which outputs exist and where they
+  // go are both relevant here.
+  //
+  // This tag is intentionally broad, as many different types of flags will
+  // affect the output of the invocation.
+  AFFECTS_OUTPUTS = 4;
+
+  // This option affects the semantics of BUILD or bzl files.
+  BUILD_FILE_SEMANTICS = 5;
+
+  // This option affects settings of Bazel-internal machinery. This tag does
+  // not, on its own, mean that external artifacts are affected, but the route
+  // taken to make them might have differed.
+  BAZEL_INTERNAL_CONFIGURATION = 6;
+
+  // This option affects the loading and analysis of dependencies, and the
+  // building of the dependency graph.
+  LOADING_AND_ANALYSIS = 7;
+
+  // This option affects the execution phase. Sandboxing or remote execution
+  // related options should use this category.
+  EXECUTION = 8;
+
+  // This option triggers an optimization that may be machine specific and is
+  // not guaranteed to work on all machines. Depending on what is being
+  // optimized for, this could be a tradeoff with other aspects of performance,
+  // such as memory or cpu cost.
+  HOST_MACHINE_RESOURCE_OPTIMIZATIONS = 9;
+
+  // This option changes how eagerly a Bazel invocation will exit from a
+  // failure.
+  EAGERNESS_TO_EXIT = 10;
+
+  // This option is used for the purposes of monitoring Bazel behavior or
+  // performance. The information collected might have effect on logging output,
+  // but should not be relevant for the majority of Bazel users that aren't also
+  // Bazel developers.
+  BAZEL_MONITORING = 11;
+}
+
+// On top of categorizing options by their intended purpose, these tags should
+// identify options that are either not supported or are intended to break old
+// behavior.
+enum OptionMetadataTag {
+  // This option triggers an experimental feature with no guarantees of
+  // functionality
+  //
+  // Note: this is separate from UNDOCUMENTED flags, which are flags we don't
+  // want listed and shouldn't be widely used. Experimental flags should
+  // probably also be undocumented, but not all undocumented flags should be
+  // 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
+  // migration readiness or get early access to the feature.
+  INCOMPATIBLE_CHANGE = 1;
+
+  // This flag is deprecated. It might either no longer have any effect, or
+  // might no longer be supported.
+  DEPRECATED = 2;
+}