src/main/java/com/google/devtools/build/lib/runtime/AllIncompatibleChangesExpansion.java

// 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.build.lib.runtime;

import com.google.common.collect.Iterables;
import com.google.devtools.common.options.Converter;
import com.google.devtools.common.options.ExpansionFunction;
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 java.lang.reflect.Field;
import java.util.ArrayList;
import java.util.Map;

/**
 * Expansion function for {@code --all_incompatible_changes}. Expands to all options of form {@code
 * --incompatible_*} that are declared in the {@link OptionsBase} subclasses that are passed to the
 * parser.
 *
 * <p>The incompatible changes system provides users with a uniform way of opting into backwards-
 * incompatible changes, in order to test whether their builds will be broken by an upcoming
 * release. When adding a new breaking change to Bazel, prefer to use this mechanism for guarding
 * the behavior.
 *
 * <p>An {@link Option}-annotated field that is considered an incompatible change must satisfy the
 * following requirements.
 *
 * <ul>
 *   <li>the {@link Option#name} must be prefixed with "incompatible_"
 *   <li>the {@link Option#category} must be "incompatible changes"
 *   <li>the {@link Option#help} field must be set, and must refer the user to information about
 *       what the change does and how to migrate their code
 *   <li>the following fields may not be used: {@link Option#abbrev}, {@link Option#valueHelp},
 *       {@link Option#converter}, {@link Option#allowMultiple}, {@link Option#oldName}, and {@link
 *       Option#wrapperOption}
 * </ul>
 *
 * Example:
 *
 * <pre>{@code
 * @Option(
 *   name = "incompatible_foo",
 *   category = "incompatible changes",
 *   defaultValue = "false",
 *   help = "Deprecates bar and changes the semantics of baz. To migrate your code see [...].")
 * public boolean incompatibleFoo;
 * }</pre>
 *
 * All options that satisfy either the name or category requirement will be validated using the
 * above criteria. Any failure will cause {@link IllegalArgumentException} to be thrown, which will
 * cause the construction of the {@link OptionsParser} to fail with the <i>unchecked</i> exception
 * {@link OptionsParser.ConstructionException}. Therefore, when adding a new incompatible change, be
 * aware that an error in the specification of the {@code @Option} will exercise failure code paths
 * in the early part of the Bazel server execution.
 *
 * <p>After the breaking change has been enabled unconditionally, it is recommended (required?) that
 * its corresponding incompatible change option be left as a valid no-op option, rather than
 * removed. This helps avoid breaking invocations of Bazel upon upgrading to a new release. Just as
 * for other options, names of incompatible change options must never be reused for a different
 * option.
 */
// Javadoc can't resolve inner classes.
@SuppressWarnings("javadoc")
public class AllIncompatibleChangesExpansion implements ExpansionFunction {

  // The reserved prefix for all incompatible change option names.
  public static final String INCOMPATIBLE_NAME_PREFIX = "incompatible_";
  // The reserved category for all incompatible change options.
  public static final String INCOMPATIBLE_CATEGORY = "incompatible changes";

  /**
   * Ensures that the given option satisfies all the requirements on incompatible change options
   * enumerated above.
   *
   * <p>If any of these requirements are not satisfied, {@link IllegalArgumentException} is thrown,
   * as this constitutes an internal error in the declaration of the option.
   */
  private static void validateIncompatibleChange(Field field, Option annotation) {
    String prefix = "Incompatible change option '--" + annotation.name() + "' ";

    // To avoid ambiguity, and the suggestion of using .isEmpty().
    String defaultString = "";

    // Validate that disallowed fields aren't used. These will need updating if the default values
    // in Option ever change, and perhaps if new fields are added.
    if (annotation.abbrev() != '\0') {
      throw new IllegalArgumentException(prefix + "must not use the abbrev field");
    }
    if (!annotation.valueHelp().equals(defaultString)) {
      throw new IllegalArgumentException(prefix + "must not use the valueHelp field");
    }
    if (annotation.converter() != Converter.class) {
      throw new IllegalArgumentException(prefix + "must not use the converter field");
    }
    if (annotation.allowMultiple()) {
      throw new IllegalArgumentException(prefix + "must not use the allowMultiple field");
    }
    if (annotation.implicitRequirements().length > 0) {
      throw new IllegalArgumentException(prefix + "must not use the implicitRequirements field");
    }
    if (!annotation.oldName().equals(defaultString)) {
      throw new IllegalArgumentException(prefix + "must not use the oldName field");
    }
    if (annotation.wrapperOption()) {
      throw new IllegalArgumentException(prefix + "must not use the wrapperOption field");
    }

    // Validate the fields that are actually allowed.
    if (!annotation.name().startsWith(INCOMPATIBLE_NAME_PREFIX)) {
      throw new IllegalArgumentException(prefix + "must have name starting with \"incompatible_\"");
    }
    if (!annotation.category().equals(INCOMPATIBLE_CATEGORY)) {
      throw new IllegalArgumentException(prefix + "must have category \"incompatible changes\"");
    }
    if (!IsolatedOptionsData.isExpansionOption(annotation)) {
      if (!field.getType().equals(Boolean.TYPE)) {
        throw new IllegalArgumentException(
            prefix + "must have boolean type (unless it's an expansion option)");
      }
    }
    if (annotation.help().equals(defaultString)) {
      throw new IllegalArgumentException(
          prefix
              + "must have a \"help\" string that refers the user to "
              + "information about this change and how to migrate their code");
    }
  }

  @Override
  public String[] getExpansion(IsolatedOptionsData optionsData) {
    // Grab all registered options that are identified as incompatible changes by either name or
    // by category. Ensure they satisfy our requirements.
    ArrayList<String> incompatibleChanges = new ArrayList<>();
    for (Map.Entry<String, Field> entry : optionsData.getAllNamedFields()) {
      Field field = entry.getValue();
      Option annotation = field.getAnnotation(Option.class);
      if (annotation.name().startsWith(INCOMPATIBLE_NAME_PREFIX)
          || annotation.category().equals(INCOMPATIBLE_CATEGORY)) {
        validateIncompatibleChange(field, annotation);
        incompatibleChanges.add("--" + annotation.name());
      }
    }
    // Sort to get a deterministic canonical order. This probably isn't necessary because the
    // options parser will do its own sorting when canonicalizing, but it seems like it can't hurt.
    incompatibleChanges.sort(null);
    return Iterables.toArray(incompatibleChanges, String.class);
  }
}