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.