KAFKA-16303: Add upgrade notes to 3.5.0, 3.5.2, and 3.7.0 about MM2 o…

…ffset translation (#15423)

Signed-off-by: Greg Harris <[email protected]>
Reviewers: Mickael Maison <[email protected]>

docs/upgrade.html

@@ -102,6 +102,11 @@ <h5><a id="upgrade_370_notable" href="#upgrade_370_notable">Notable changes in 3
         <li>Kafka Streams ships multiple KIPs for IQv2 support.
             See the <a href="/{{version}}/documentation/streams/upgrade-guide#streams_api_changes_370">Kafka Streams upgrade section</a> for more details.
         </li>
+        <li>
+            In versions 3.5.0, 3.5.1, 3.5.2, 3.6.0, and 3.6.1, MirrorMaker 2 offset translation may not reach the end
+            of a replicated topic after the upstream consumers commit at the end of the source topic.
+            This was addressed in <a href="https://issues.apache.org/jira/browse/KAFKA-15906">KAFKA-15906</a>.
+        </li>
         <li>All the notable changes are present in the <a href="https://kafka.apache.org/blog#apache_kafka_370_release_announcement">blog post announcing the 3.7.0 release.</a>
         </li>
     </ul>
@@ -225,6 +230,11 @@ <h5><a id="upgrade_352_notable" href="#upgrade_352_notable">Notable changes in 3
         during rolling upgrade. This issue will impact the availability of the topic partition.
         See <a href="https://issues.apache.org/jira/browse/KAFKA-15353">KAFKA-15353</a> for more details.
     </li>
+    <li>
+        In 3.5.0 and 3.5.1, there was an issue where MirrorMaker 2 offset translation produced an earlier offset than needed,
+        substantially increasing the re-delivery of data when starting a consumer from the downstream consumer offsets.
+        See <a href="https://issues.apache.org/jira/browse/KAFKA-15202">KAFKA-15202</a> for more details.
+    </li>
 </ul>
 
 <h4><a id="upgrade_3_5_1" href="#upgrade_3_5_1">Upgrading to 3.5.1 from any version 0.8.x through 3.4.x</a></h4>
@@ -334,6 +344,12 @@ <h5><a id="upgrade_350_notable" href="#upgrade_350_notable">Notable changes in 3
             The 'kafka.tools' package is deprecated and will change to 'org.apache.kafka.tools' in the next major release.
             See <a href="https://issues.apache.org/jira/browse/KAFKA-14525">KAFKA-14525</a> for more details.
         </li>
+        <li>In versions earlier than 3.5.0 and 3.4.1, MirrorMaker 2 offset translation could incorrectly translate offsets for topics using compaction, transactional producers, and filter SMTs.
+            In 3.5.0 and 3.4.1, offset translation has changed for all topics in order to ensure at-least-once delivery when a consumer is failed-over to the translated offsets.
+            Translated offsets will be earlier than in previous versions, so consumers using downstream offsets may initially have more lag, and re-deliver more data after failing-over.
+            See <a href="https://issues.apache.org/jira/browse/KAFKA-12468">KAFKA-12468</a> and linked tickets, and <a href="https://github.com/apache/kafka/pull/13178">PR #13178</a> for more details.
+            Further improvements to the offset translation  are included in later releases to reduce the lag introduced by this change, so consider upgrading MM2 to the latest version available.
+        </li>
     </ul>
 
 <h4><a id="upgrade_3_4_0" href="#upgrade_3_4_0">Upgrading to 3.4.0 from any version 0.8.x through 3.3.x</a></h4>