diff --git a/docs/upgrade.html b/docs/upgrade.html
index be717aee920..91d660484b4 100644
--- a/docs/upgrade.html
+++ b/docs/upgrade.html
@@ -21,10 +21,15 @@
 
 <h5><a id="upgrade_250_notable" href="#upgrade_250_notable">Notable changes in 2.5.0</a></h5>
 <ul>
+    <li>When <code>RebalanceProtocol#COOPERATIVE</code> is used, <code>Consumer#poll</code> can still return data
+        while it is in the middle of a rebalance for those partitions still owned by the consumer; in addition
+        <code>Consumer#commitSync</code> now may throw a non-fatal <code>RebalanceInProgressException</code> to notify
+        users of such an event, in order to distinguish from the fatal <code>CommitFailedException</code> and allow
+        users to complete the ongoing rebalance and then reattempt committing offsets for those still-owned partitions.</li>
     <li>For improved resiliency in typical network environments, the default value of
         <code>zookeeper.session.timeout.ms</code> has been increased from 6s to 18s and
         <code>replica.lag.time.max.ms</code> from 10s to 30s.</li>
-    <li>New DSL operator <code>cogroup()</code> has been added for aggregating multiple streams together at once</li>
+    <li>New DSL operator <code>cogroup()</code> has been added for aggregating multiple streams together at once.</li>
     <li>Scala 2.11 is no longer supported. See
         <a href="https://cwiki.apache.org/confluence/display/KAFKA/KIP-531%3A+Drop+support+for+Scala+2.11+in+Kafka+2.5">KIP-531</a>
         for details.</li>