KAFKA-17825: Update docs for ByteBufferDeserializer changes in 3.6 release

clients/src/main/java/org/apache/kafka/common/serialization/Deserializer.java

@@ -63,7 +63,11 @@ default T deserialize(String topic, Headers headers, byte[] data) {
     }
 
     /**
-     * Deserialize a record value from a ByteBuffer into a value or object.
+     * Deserialize a record value from a {@link ByteBuffer} into a value or object.
+     * <p>
+     * The implementation cannot make any assumptions about the {@link ByteBuffer} like the position, limit, capacity,
+     * etc., or if it is backed by {@link ByteBuffer#hasArray() an array or not}.
+     *
      * @param topic topic associated with the data
      * @param headers headers associated with the record; may be empty.
      * @param data serialized ByteBuffer; may be null; implementations are recommended to handle null by returning a value or null rather than throwing an exception.

docs/upgrade.html

@@ -688,6 +688,10 @@ <h5><a id="upgrade_360_notable" href="#upgrade_360_notable">Notable changes in 3
             The configuration can also be updated dynamically and is applied to the broker. Workloads running on version 3.6.0 with compression can experience
             InvalidRecordExceptions and UnknownServerExceptions. Upgrading to 3.6.1 or newer or disabling the feature fixes the issue.
         </li>
+	<li>The <code>ByteBufferDeserializer</code> (<a href="https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=225152035">KIP-863</a>)
+	    was changed to avoid unnecessary deep-copies of data. This changes the behavior of the deserializer as user code cannot make any assumptions
+	    about buffer position, limit, capactiy any longer.
+        </li>
     </ul>
 
 <h4><a id="upgrade_3_5_2" href="#upgrade_3_5_2">Upgrading to 3.5.2 from any version 0.8.x through 3.4.x</a></h4>