MINOR: update docs for KAFKA-19668 (#721)

Author: mjsax

33/streams/developer-guide/dsl-api.html

@@ -3496,6 +3496,9 @@ <h5><a class="toc-backref" href="#id34">KTable-KTable Foreign-Key
                     </tr>
                     </tbody>
                 </table>
+
+                <p><b>CAUTION:</b> If you are using "merge repartition topics" optimization, it is not recommended to use <code>KStream#processValues</code> to avoid compatibility issues for future upgrades to newer versions of Kafka Streams.
+                    For more details, see the <a href="/40/documentation/streams/developer-guide/dsl-api.htm#transformers-removal-and-migration-to-processors">migration guide</a> in the Kafka Streams 4.0 docs.</p>
                 <p>The following example shows how to leverage, via the <code class="docutils literal"><span class="pre">KStream#process()</span></code> method, a custom <code class="docutils literal"><span class="pre">Processor</span></code> that sends an
                     email notification whenever a page view count reaches a predefined threshold.</p>
                 <p>First, we need to implement a custom stream processor, <code class="docutils literal"><span class="pre">PopularPageEmailAlert</span></code>, that implements the <code class="docutils literal"><span class="pre">Processor</span></code>

34/streams/developer-guide/dsl-api.html

@@ -3496,6 +3496,9 @@ <h5><a class="toc-backref" href="#id34">KTable-KTable Foreign-Key
                     </tr>
                     </tbody>
                 </table>
+
+                <p><b>CAUTION:</b> If you are using "merge repartition topics" optimization, it is not recommended to use <code>KStream#processValues</code> to avoid compatibility issues for future upgrades to newer versions of Kafka Streams.
+                    For more details, see the <a href="/40/documentation/streams/developer-guide/dsl-api.htm#transformers-removal-and-migration-to-processors">migration guide</a> in the Kafka Streams 4.0 docs.</p>
                 <p>The following example shows how to leverage, via the <code class="docutils literal"><span class="pre">KStream#process()</span></code> method, a custom <code class="docutils literal"><span class="pre">Processor</span></code> that sends an
                     email notification whenever a page view count reaches a predefined threshold.</p>
                 <p>First, we need to implement a custom stream processor, <code class="docutils literal"><span class="pre">PopularPageEmailAlert</span></code>, that implements the <code class="docutils literal"><span class="pre">Processor</span></code>

35/streams/developer-guide/dsl-api.html

@@ -3524,6 +3524,9 @@ <h5><a class="toc-backref" href="#id34">KTable-KTable Foreign-Key
                     </tr>
                     </tbody>
                 </table>
+
+                <p><b>CAUTION:</b> If you are using "merge repartition topics" optimization, it is not recommended to use <code>KStream#processValues</code> to avoid compatibility issues for future upgrades to newer versions of Kafka Streams.
+                    For more details, see the <a href="/40/documentation/streams/developer-guide/dsl-api.htm#transformers-removal-and-migration-to-processors">migration guide</a> in the Kafka Streams 4.0 docs.</p>
                 <p>The following example shows how to leverage, via the <code class="docutils literal"><span class="pre">KStream#process()</span></code> method, a custom <code class="docutils literal"><span class="pre">Processor</span></code> that sends an
                     email notification whenever a page view count reaches a predefined threshold.</p>
                 <p>First, we need to implement a custom stream processor, <code class="docutils literal"><span class="pre">PopularPageEmailAlert</span></code>, that implements the <code class="docutils literal"><span class="pre">Processor</span></code>

36/streams/developer-guide/dsl-api.html

@@ -3540,6 +3540,9 @@ <h5><a class="toc-backref" href="#id34">KTable-KTable Foreign-Key
                     </tr>
                     </tbody>
                 </table>
+
+                <p><b>CAUTION:</b> If you are using "merge repartition topics" optimization, it is not recommended to use <code>KStream#processValues</code> to avoid compatibility issues for future upgrades to newer versions of Kafka Streams.
+                    For more details, see the <a href="/40/documentation/streams/developer-guide/dsl-api.htm#transformers-removal-and-migration-to-processors">migration guide</a> in the Kafka Streams 4.0 docs.</p>
                 <p>The following example shows how to leverage, via the <code class="docutils literal"><span class="pre">KStream#process()</span></code> method, a custom <code class="docutils literal"><span class="pre">Processor</span></code> that sends an
                     email notification whenever a page view count reaches a predefined threshold.</p>
                 <p>First, we need to implement a custom stream processor, <code class="docutils literal"><span class="pre">PopularPageEmailAlert</span></code>, that implements the <code class="docutils literal"><span class="pre">Processor</span></code>

37/streams/developer-guide/dsl-api.html

@@ -3536,6 +3536,9 @@ <h5><a class="toc-backref" href="#id34">KTable-KTable Foreign-Key
                     </tr>
                     </tbody>
                 </table>
+
+                <p><b>CAUTION:</b> If you are using "merge repartition topics" optimization, it is not recommended to use <code>KStream#processValues</code> to avoid compatibility issues for future upgrades to newer versions of Kafka Streams.
+                    For more details, see the <a href="/40/documentation/streams/developer-guide/dsl-api.htm#transformers-removal-and-migration-to-processors">migration guide</a> in the Kafka Streams 4.0 docs.</p>
                 <p>The following example shows how to leverage, via the <code class="docutils literal"><span class="pre">KStream#process()</span></code> method, a custom <code class="docutils literal"><span class="pre">Processor</span></code> that sends an
                     email notification whenever a page view count reaches a predefined threshold.</p>
                 <p>First, we need to implement a custom stream processor, <code class="docutils literal"><span class="pre">PopularPageEmailAlert</span></code>, that implements the <code class="docutils literal"><span class="pre">Processor</span></code>

38/streams/developer-guide/dsl-api.html

@@ -3180,6 +3180,9 @@ <h5><a class="toc-backref" href="#id34">KTable-KTable Foreign-Key
                     </tr>
                     </tbody>
                 </table>
+
+                <p><b>CAUTION:</b> If you are using "merge repartition topics" optimization, it is not recommended to use <code>KStream#processValues</code> to avoid compatibility issues for future upgrades to newer versions of Kafka Streams.
+                    For more details, see the <a href="/40/documentation/streams/developer-guide/dsl-api.htm#transformers-removal-and-migration-to-processors">migration guide</a> in the Kafka Streams 4.0 docs.</p>
                 <p>The following example shows how to leverage, via the <code class="docutils literal"><span class="pre">KStream#process()</span></code> method, a custom <code class="docutils literal"><span class="pre">Processor</span></code> that sends an
                     email notification whenever a page view count reaches a predefined threshold.</p>
                 <p>First, we need to implement a custom stream processor, <code class="docutils literal"><span class="pre">PopularPageEmailAlert</span></code>, that implements the <code class="docutils literal"><span class="pre">Processor</span></code>

39/streams/developer-guide/dsl-api.html

@@ -3180,6 +3180,9 @@ <h5><a class="toc-backref" href="#id34">KTable-KTable Foreign-Key
                     </tr>
                     </tbody>
                 </table>
+
+                <p><b>CAUTION:</b> If you are using "merge repartition topics" optimization, it is not recommended to use <code>KStream#processValues</code> to avoid compatibility issues for future upgrades to newer versions of Kafka Streams.
+                    For more details, see the <a href="/40/documentation/streams/developer-guide/dsl-api.htm#transformers-removal-and-migration-to-processors">migration guide</a> in the Kafka Streams 4.0 docs.</p>
                 <p>The following example shows how to leverage, via the <code class="docutils literal"><span class="pre">KStream#process()</span></code> method, a custom <code class="docutils literal"><span class="pre">Processor</span></code> that sends an
                     email notification whenever a page view count reaches a predefined threshold.</p>
                 <p>First, we need to implement a custom stream processor, <code class="docutils literal"><span class="pre">PopularPageEmailAlert</span></code>, that implements the <code class="docutils literal"><span class="pre">Processor</span></code>

40/streams/developer-guide/dsl-api.html

@@ -3130,15 +3130,20 @@ <h4>Operations and concepts</h4>
                         <code>Processor</code> (provided by a given <code>ProcessorSupplier</code>);
                     </li>
                     <li><code>KStream#processValues</code>: Process all records in a stream, one record at a time, by applying a
-                        <code>FixedKeyProcessor</code> (provided by a given <code>FixedKeyProcessorSupplier</code>);
+                        <code>FixedKeyProcessor</code> (provided by a given <code>FixedKeyProcessorSupplier</code>)
+                        [<b>CAUTION:</b> If you are deploying a new Kafka Streams application, and you are using the
+                        "merge repartition topics" optimization, you should enable the fix for
+                        <a href="https://issues.apache.org/jira/browse/KAFKA-19668">KAFKA-19668</a> to avoid compatibility
+                        issues for future upgrades to newer versions of Kafka Streams;
+                        For more details, see the <a href="#transformers-removal-and-migration-to-processors">migration guide</a> below];
                     </li>
                     <li><code>Processor</code>: A processor of key-value pair records;</li>
                     <li><code>ContextualProcessor</code>: An abstract implementation of <code>Processor</code> that manages the
-                        <code>ProcessorContext</code> instance.
+                        <code>ProcessorContext</code> instance;
                     </li>
                     <li><code>FixedKeyProcessor</code>: A processor of key-value pair records where keys are immutable;</li>
                     <li><code>ContextualFixedKeyProcessor</code>: An abstract implementation of <code>FixedKeyProcessor</code> that
-                        manages the <code>FixedKeyProcessorContext</code> instance.
+                        manages the <code>FixedKeyProcessorContext</code> instance;
                     </li>
                     <li><code>ProcessorSupplier</code>: A processor supplier that can create one or more <code>Processor</code>
                         instances; and</li>
@@ -3456,6 +3461,25 @@ <h3>
                 </ul>
                 <p>The Processor API now serves as a unified replacement for all these methods. It simplifies the API surface
                     while maintaining support for both stateless and stateful operations.</p>
+
+                <p><b>CAUTION:</b> If you are using <code>KStream.transformValues()</code> and you have the "merge repartition topics"
+                    optimization enabled, rewriting your program to <code>KStream.processValues()</code> might not be safe due to
+                    <a href="https://issues.apache.org/jira/browse/KAFKA-19668">KAFKA-19668</a>. For this case, you should not upgrade
+                    to Kafka Streams 4.0.0 or 4.1.0, but use Kafka Streams 4.0.1 instead, which contains a fix.
+                    Note, that the fix is not enabled by default for backward compatibility reasons, and you would need to
+                    enable the fix by setting config <code>__enable.process.processValue.fix__ = true</code> and pass it
+                    into <code>StreamsBuilder()</code> constructor.</p>
+                    <pre class="line-numbers"><code class="language-java">final Properties properties = new Properties();
+properties.put(StreamsConfig.APPLICATION_ID_CONFIG, ...);
+properties.put(StreamsConfig.BOOTSTRAP_SERVERS_CONFIG, ...);
+properties.put(TopologyConfig.InternalConfig.ENABLE_PROCESS_PROCESSVALUE_FIX, true);
+
+final StreamsBuilder builder = new StreamsBuilder(new TopologyConfig(new StreamsConfig(properties)));</code></pre>
+
+                <p>It is recommended, that you compare the output of <code>Topology.describe()</code> for the old and new topology,
+                    to verify if the rewrite to <code>processValues()</code> is correct, and that it does not introduce any incompatibilities.
+                    You should also test the upgrade in a non-production environment.</p>
+
                 <h4>Migration Examples</h4>
                 <p>To migrate from the deprecated <code>transform</code>, <code>transformValues</code>, <code>flatTransform</code>, and
                     <code>flatTransformValues</code> methods to the Processor API (PAPI) in Kafka Streams, let&#39;s resume the