Tasks: Document that status is not semvered (#34270)

The `status` part of the tasks API reflects the internal status of a
running task. In general, we do not make backwards breaking changes to
the `status` but because it is internal we reserve the right to do so. I
suspect we will very rarely excercise that right but it is important
that we have it so we're not boxed into any particular implementation
for a request.

In some sense this is policy making by documentation change. In another
it is clarification of the way we've always thought of this field.

I also reflect the documentation change into the Javadoc in a few
places. There I acknowledge Kibana's "special relationship" with
Elasticsearch. Kibana parses `_reindex`'s `status` field and, because
we're friends with those folks, we should talk to them before we make
backwards breaking changes to it. We *want* to be friends with everyone
but there is only so much time in the day and we don't *want* to make
backwards breaking fields to `status` at all anyway. So we hope that
breaking changes documentation should be enough for other folks.

Relates to #34245.

Author: nik9000

docs/reference/cluster/tasks.asciidoc

@@ -132,6 +132,19 @@ number of requests and the destination indices. Many requests will only have an
 empty description because more detailed information about the request is not
 easily available or particularly helpful in identifying the request.
 
+[IMPORTANT]
+==============================
+
+`_tasks` requests with `detailed` may also return a `status`. This is a report
+of the internal status of the task. As such its format varies from task to task.
+While we try to keep the `status` for a particular task consistent from version
+to version this isn't always possible because we sometimes change the
+implementation. In that case we might remove fields from the `status` for a
+particular request so any parsing you do of the status might break in minor
+releases.
+
+==============================
+
 The task API can also be used to wait for completion of a particular task. The
 following call will block for 10 seconds or until the task with id
 `oTUltX4IQMOUUVeiohTt8A:12345` is completed.

server/src/main/java/org/elasticsearch/index/reindex/BulkByScrollTask.java

@@ -319,6 +319,14 @@ public Status buildStatus() {
         }
     }
 
+    /**
+     * Status of the reindex, update by query, or delete by query. While in
+     * general we allow {@linkplain Task.Status} implementations to make
+     * backwards incompatible changes to their {@link Task.Status#toXContent}
+     * implementations, this one has become defacto standardized because Kibana
+     * parses it. As such, we should be very careful about removing things from
+     * this.
+     */
     public static class Status implements Task.Status, SuccessfullyProcessed {
         public static final String NAME = "bulk-by-scroll";
 

server/src/main/java/org/elasticsearch/tasks/Task.java

@@ -157,9 +157,20 @@ public Status getStatus() {
         return null;
     }
 
+    /**
+     * Report of the internal status of a task. These can vary wildly from task
+     * to task because each task is implemented differently but we should try
+     * to keep each task consistent from version to version where possible.
+     * That means each implementation of {@linkplain Task.Status#toXContent}
+     * should avoid making backwards incompatible changes to the rendered
+     * result. But if we change the way a request is implemented it might not
+     * be possible to preserve backwards compatibility. In that case, we
+     * <b>can</b> change this on version upgrade but we should be careful
+     * because some statuses (reindex) have become defacto standardized because
+     * they are used by systems like Kibana.
+     */
     public interface Status extends ToXContentObject, NamedWriteable {}
 
-
     /**
      * Returns stored task header associated with the task
      */