Tasks: Document that status is not semvered

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
      */