Clarify UseDefault behavior surrounding expansion flags.
Also warn that user values can be lost, at which point later policies won't revive them. This warning should be removed once [] is fixed.
MOS_MIGRATED_REVID=149939586
@@ -27,7 +27,11 @@ message InvocationPolicy {
// policy list first has a SetValue policy for "set --bar to z", and then has
// a SetDefault policy to set "--foo" to its default value, both --bar and
// --baz will get reset to their default values, overriding the SetValue
- // operation. The SetDefault should come before the SetValue.
+ // operation. The UseDefault should come before the SetValue.
+ //
+ // Note that currently, if user value is lost, either cleared by UseDefault
+ // or by being written over by a SetValue, a later white-listing of the user's
+ // inputted value will not restore it.
repeated FlagPolicy flag_policies = 1;
}
@@ -118,10 +122,16 @@ message SetValue {
message UseDefault {
// Use the default value of the flag, as defined by Bazel (or equivalently, do
// not allow the user to set this flag).
+ //
+ // Note on implementation: UseDefault sets the default by clearing the flag,
+ // so that when the value is requested and no flag is found, the flag parser
+ // returns the default. This is mostly relevant for expansion flags: it will
+ // erase user values in *all* flags that the expansion flag expands to. Only
+ // use this on expansion flags if this is acceptable behavior. Otherwise, make
+ // an appropriate policy for the expanded flags that you care about.
}
message DisallowValues {
-
// Obsolete new_default_value field.
reserved 2;
@@ -139,7 +149,6 @@ message DisallowValues {
repeated string disallowed_values = 1;
oneof replacement_value {
-
// If set and if the value of the flag is disallowed (including the default
// value of the flag if the user doesn't specify a value), use this value as
// the value of the flag instead of raising an error. This does not apply to
@@ -159,7 +168,6 @@ message DisallowValues {
}
message AllowValues {
-
// Obsolete new_default_value field.
reserved 2;
@@ -168,7 +176,6 @@ message AllowValues {
repeated string allowed_values = 1;
oneof replacement_value {
-
// If set and if the value of the flag is disallowed (including the default
// value of the flag if the user doesn't specify a value), use this value as
// the value of the flag instead of raising an error. This does not apply to
