Document behavior change for zero speculative execution delay

JAVA-1490 breaks legacy policy implementations if they returned 0 to
mean "no execution" (the workaround is to return a negative value
instead).

Author: olim7t

driver-core/src/main/java/com/datastax/driver/core/policies/SpeculativeExecutionPolicy.java

@@ -66,8 +66,10 @@ interface SpeculativeExecutionPlan {
      *
      * @param lastQueried the host that was just queried.
      * @return the time (in milliseconds) before a speculative query is sent to the next host. If
-     *     negative, no speculative query will be sent. If zero it will immediately send the
-     *     execution.
+     *     negative, no speculative query will be sent. If zero, it will immediately send the
+     *     execution. <em>Note that, prior to version 3.3.1, zero meant "no speculative query", so
+     *     custom policies written at that time may now start to schedule more executions than
+     *     expected; make sure you use a negative value, not zero, to stop executions.</em>
      */
     long nextExecution(Host lastQueried);
   }

upgrade_guide/README.md

@@ -79,6 +79,15 @@ you were accessing these methods using reflection in which case you need to
 account for these new parameter types.
 
 
+### 3.3.1
+
+Speculative executions can now be scheduled without delay: if
+`SpeculativeExecutionPlan.nextExecution()` returns 0, the next execution will be fired immediately.
+This allows aggressive policies that hit multiple replicas right away, in order to get the fastest
+response possible. Note that this may break existing policies that used 0 to mean "no execution";
+make sure you use a negative value instead.
+
+
 ### 3.2.0
 
 The `SSLOptions` interface is now deprecated in favor of