From b11bb272c1c605a700bd8407d21ed9eb171d2822 Mon Sep 17 00:00:00 2001
From: Nik Everett <nik9000@gmail.com>
Date: Thu, 11 Apr 2024 15:01:49 -0400
Subject: [PATCH] ESQL: More explanation for version (#107363)

This explains the ESQL version a bit and adds the magic `@UpateForV9`
annotation which has the power to control humans! It'll cause the humans
running the 9.0.0 release to read the docs on this class and update the
base version in the es-specification.
---
 .../compute/gen/ConsumeProcessor.java         |  1 +
 .../xpack/esql/version/EsqlVersion.java       | 39 +++++++++++++++++++
 2 files changed, 40 insertions(+)

diff --git a/x-pack/plugin/esql/compute/gen/src/main/java/org/elasticsearch/compute/gen/ConsumeProcessor.java b/x-pack/plugin/esql/compute/gen/src/main/java/org/elasticsearch/compute/gen/ConsumeProcessor.java
index 6b218fab7affb..1c28acfd6a23b 100644
--- a/x-pack/plugin/esql/compute/gen/src/main/java/org/elasticsearch/compute/gen/ConsumeProcessor.java
+++ b/x-pack/plugin/esql/compute/gen/src/main/java/org/elasticsearch/compute/gen/ConsumeProcessor.java
@@ -41,6 +41,7 @@ public Set<String> getSupportedAnnotationTypes() {
             "org.elasticsearch.xpack.esql.expression.function.Param",
             "org.elasticsearch.rest.ServerlessScope",
             "org.elasticsearch.xcontent.ParserConstructor",
+            "org.elasticsearch.core.UpdateForV9",
             Fixed.class.getName()
         );
     }
diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/version/EsqlVersion.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/version/EsqlVersion.java
index 9e3c43491e1e8..23f6ab6da5f16 100644
--- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/version/EsqlVersion.java
+++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/version/EsqlVersion.java
@@ -9,12 +9,51 @@
 
 import org.elasticsearch.common.Strings;
 import org.elasticsearch.common.VersionId;
+import org.elasticsearch.core.UpdateForV9;
+import org.elasticsearch.xpack.esql.expression.function.scalar.multivalue.MvAvg;
 
 import java.util.Arrays;
 import java.util.Comparator;
 import java.util.LinkedHashMap;
 import java.util.Map;
 
+/**
+ * The version of the ESQL language being processed.
+ * <p>
+ *     ESQL is a young language and we don't have the benefit of self-hosting
+ *     its compiler. So we're going to make a lot of mistakes when designing it.
+ *     As such, we expect it to change in backwards incompatible ways several
+ *     times in 2024 and 2025. Hopefully we'll have learned our lesson and we'll
+ *     settle down to one change every couple of years after that.
+ * </p>
+ * <p>
+ *     For example, maybe we realize we've made a mistake with the {@link MvAvg}
+ *     function and decide it should return the type of its input field rather
+ *     than always returning a {@code double}. If we decide to make this change
+ *     we'd have to bump the language version. We plan to batch changes like this
+ *     into the {@link EsqlVersion#SNAPSHOT} version for a while and from time to
+ *     time release them as a new version.
+ * </p>
+ * <p>
+ *     We require a version to be sent on every request to the ESQL APIs so
+ *     changing the version of a query is always opt-in. There is no REST request
+ *     you can send to any ESQL endpoint that will default to a version of ESQL.
+ *     That means we can release new versions of ESQL in a minor release of
+ *     Elasticsearch. We can and we will.
+ * </p>
+ * <p>
+ *     So users of Elasticsearch's clients don't need to think about the version
+ *     of ESQL when they are getting started they we have a concept of "base version".
+ *     This "base version" will remain constant for an entire major release of
+ *     Elasticsearch and clients will send that version with ESQL requests unless
+ *     otherwise configured.
+ * </p>
+ * <p>
+ *     This is marked with {@link UpdateForV9} to remind us that we need to
+ *     update the "base version" of ESQL in the client specification when
+ *     we cut a new major. We'll need to do that on every major - and also bump the {@link UpdateForV9} annotation.
+ * </p>
+ */
 public enum EsqlVersion implements VersionId<EsqlVersion> {
     /**
      * Breaking changes go here until the next version is released.