Add annotation @BehaviorChangeSince for behavior-change flags

build-logic/src/main/kotlin/polaris-java.gradle.kts

@@ -160,6 +160,46 @@ tasks.withType(Jar::class).configureEach {
   }
 }
 
+class StaleBehaviorChangeConfigurationChecker(private val appVersion: String) : FormatterFunc {
+
+  // Helper function for spotless to check for stale BehaviorChangeConfigurations
+  fun isStaleVersion(
+    annotatedVersion: String,
+    expiresVersion: String?,
+    polarisVersion: String,
+  ): Boolean {
+    if (expiresVersion == null) {
+      val (majorA, minorA, _) = annotatedVersion.split(".").map { it.toInt() }
+      return isStaleVersion(annotatedVersion, "${majorA + 1}.${minorA}.0", polarisVersion) ||
+                isStaleVersion(annotatedVersion, "${majorA}.${minorA + 2}.0", polarisVersion);
+    } else {
+      val (majorA, minorA, patchA) = expiresVersion.split(".").map { it.toInt() }
+      val (majorB, minorB, patchB) = polarisVersion.split(".").map { it.toInt() }
+      return (majorA > majorB ||
+        (majorA == majorB && minorA > minorB) ||
+        (majorA == majorB && minorA == minorB && patchA > patchB))
+    }
+  }
+
+  override fun apply(input: String): String {
+    val versionRegex =
+      """@BehaviorChangeScope\s*\(\s*since\s*=\s*"(\d+\.\d+\.\d+)"(?:\s*,\s*expires\s*=\s*"(\d+\.\d+\.\d+)")?\s*\)"""
+        .toRegex()
+    val matcher = versionRegex.findAll(input)
+    matcher.forEach { matchResult ->
+      val sinceVersion = matchResult.groupValues[1]
+      val expiresVersion = matchResult.groupValues.getOrNull(2)
+      if (isStaleVersion(sinceVersion, expiresVersion, appVersion)) {
+        throw GradleException(
+          "Outdated behavior change annotation detected. Consider removing the configuration, " +
+            " promoting it to a feature configuration, or disabling this check for the configuration."
+        )
+      }
+    }
+    return input
+  }
+}
+
 spotless {
   java {
     target("src/main/java/**/*.java", "src/testFixtures/java/**/*.java", "src/test/java/**/*.java")
@@ -178,6 +218,16 @@ spotless {
         }
       },
     )
+    val polarisVersion =
+      File(rootProject.projectDir, "version.txt").readText().trim().substringBefore("-")
+    custom(
+      "checkStaleBehaviorChangeFlags",
+      object : Serializable, FormatterFunc {
+        override fun apply(text: String): String {
+          return StaleBehaviorChangeConfigurationChecker(polarisVersion).apply(text)
+        }
+      },
+    )
     toggleOffOn()
   }
   kotlinGradle {
@@ -193,6 +243,23 @@ spotless {
     // getting the license-header delimiter right is a bit tricky.
     // licenseHeaderFile(rootProject.file("codestyle/copyright-header.xml"), '<^[!?].*$')
   }
+  format("enforceBehaviorChangeFlagLocations") {
+    target("**/*.java")
+    targetExclude("**/BehaviorChangeConfiguration.java", "**/PolarisConfigurationStoreTest.java")
+    custom(
+      "enforceBehaviorChangeFlags",
+      object : Serializable, FormatterFunc {
+        override fun apply(text: String): String {
+          if (".buildBehaviorChangeConfiguration()" in text) {
+            throw GradleException(
+              "Usage of buildBehaviorChangeConfiguration() is restricted to BehaviorChangeConfiguration.java"
+            )
+          }
+          return text
+        }
+      },
+    )
+  }
 }
 
 dependencies { errorprone(versionCatalogs.named("libs").findLibrary("errorprone").get()) }

polaris-core/src/main/java/org/apache/polaris/core/config/BehaviorChange.java

@@ -0,0 +1,47 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you 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 org.apache.polaris.core.config;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * An annotation that should be applied to all BehaviorChangeConfiguration instances. Spotless will
+ * enforce that these flags are not around too long. When the flag expires, the linter will prompt
+ * the person attempting to do the release to take 1 of 3 actions:
+ *
+ * <pre>
+ * <ul>
+ *     <li>Remove the flag</li>
+ *     <li>Promote the flag to a feature flag</li>
+ *     <li>Disable the linter for this flag for an "extension"</li>
+ * </ul>
+ * </pre>
+ */
+@Target(ElementType.FIELD)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface BehaviorChange {
+  static final String AUTOMATIC_EXPIRES = "auto";
+
+  String since();
+
+  String expires() default AUTOMATIC_EXPIRES;
+}

polaris-core/src/main/java/org/apache/polaris/core/config/BehaviorChangeConfiguration.java

@@ -37,9 +37,10 @@ protected BehaviorChangeConfiguration(
     super(key, description, defaultValue, catalogConfig);
   }
 
+  @BehaviorChange(since = "1.0.0")
   public static final BehaviorChangeConfiguration<Boolean> VALIDATE_VIEW_LOCATION_OVERLAP =
       PolarisConfiguration.<Boolean>builder()
-          .key("STORAGE_CREDENTIAL_CACHE_DURATION_SECONDS")
+          .key("VALIDATE_VIEW_LOCATION_OVERLAP")
           .description("If true, validate that view locations don't overlap when views are created")
           .defaultValue(true)
           .buildBehaviorChangeConfiguration();

polaris-core/src/main/java/org/apache/polaris/core/config/BehaviorChangeProcessor.java

@@ -0,0 +1,89 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you 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 org.apache.polaris.core.config;
+
+import java.util.Set;
+import javax.annotation.processing.AbstractProcessor;
+import javax.annotation.processing.RoundEnvironment;
+import javax.annotation.processing.SupportedAnnotationTypes;
+import javax.annotation.processing.SupportedSourceVersion;
+import javax.lang.model.SourceVersion;
+import javax.lang.model.element.Element;
+import javax.lang.model.element.ElementKind;
+import javax.lang.model.element.TypeElement;
+import javax.lang.model.element.VariableElement;
+import javax.lang.model.type.TypeMirror;
+import javax.lang.model.util.Elements;
+import javax.tools.Diagnostic;
+
+@SupportedAnnotationTypes("BehaviorChange")
+@SupportedSourceVersion(SourceVersion.RELEASE_8)
+public class BehaviorChangeProcessor extends AbstractProcessor {
+
+  @Override
+  public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) {
+
+    Elements elementUtils = processingEnv.getElementUtils();
+
+    for (Element element : roundEnv.getRootElements()) {
+      if (element.getKind() == ElementKind.CLASS) {
+        TypeElement typeElement = (TypeElement) element;
+        for (Element enclosedElement : typeElement.getEnclosedElements()) {
+          if (enclosedElement.getKind() == ElementKind.FIELD) {
+            VariableElement field = (VariableElement) enclosedElement;
+            TypeMirror fieldType = field.asType();
+
+            if (isBehaviorChangeConfiguration(fieldType, elementUtils)) {
+              if (field.getAnnotation(BehaviorChange.class) == null) {
+                processingEnv
+                    .getMessager()
+                    .printMessage(
+                        Diagnostic.Kind.ERROR,
+                        "Field "
+                            + field.getSimpleName()
+                            + " of type BehaviorChangeConfiguration<?> must be annotated with @BehaviorChange",
+                        field);
+              } else {
+                processingEnv
+                    .getMessager()
+                    .printMessage(
+                        Diagnostic.Kind.NOTE,
+                        "Field "
+                            + field.getSimpleName()
+                            + " is correctly annotated with @BehaviorChange",
+                        field);
+              }
+            }
+          }
+        }
+      }
+    }
+    return true;
+  }
+
+  private boolean isBehaviorChangeConfiguration(TypeMirror typeMirror, Elements elementUtils) {
+    TypeElement typeElement =
+        (TypeElement) elementUtils.getTypeElement("BehaviorChangeConfiguration");
+    if (typeElement == null) {
+      return false;
+    }
+    TypeMirror behaviorChangeConfigurationType = typeElement.asType();
+    return processingEnv.getTypeUtils().isAssignable(typeMirror, behaviorChangeConfigurationType);
+  }
+}

polaris-core/src/main/resources/META-INF/services/javax.annotation.processing.Processor

@@ -0,0 +1 @@
+org.apache.polaris.core.config.BehaviorChangeProcessor