Clarify that akka-protobuf-v3 is not for applications, #26181 (#27520)

* Clarify that akka-protobuf-v3 is not for applications, #26181
* Update akka-docs/src/main/paradox/project/migration-guide-2.5.x-2.6.x.md

akka-docs/src/main/paradox/common/binary-compatibility-rules.md

@@ -87,13 +87,17 @@ If you accidentally mix Akka versions, for example through transitive
 dependencies, you might get a warning at run time such as:
 
 ```
-Detected possible incompatible versions on the classpath. Please note that a given Akka version MUST be the same across all modules of Akka that you are using, e.g. if you use [2.5.17] all other modules that are released together MUST be of the same version. Make sure you're using a compatible set of libraries. Possibly conflicting versions [2.5.4, 2.5.17] in libraries [akka-protobuf:2.5.4, akka-actor:2.5.17, akka-stream:2.5.4]
+Detected possible incompatible versions on the classpath. Please note that a given Akka version MUST be the same
+across all modules of Akka that you are using, e.g. if you use [2.5.20] all other modules that are released together
+MUST be of the same version. Make sure you're using a compatible set of libraries. Possibly conflicting versions
+[2.5.19, 2.5.20] in libraries [akka-persistence:2.5.19, akka-cluster-sharding:2.5.19, akka-protobuf:2.5.19,
+akka-persistence-query:2.5.19, akka-actor:2.5.20, akka-slf4j:2.5.19, akka-remote:2.5.19, akka-cluster:2.5.19,
+akka-distributed-data:2.5.19, akka-stream:2.5.19, akka-cluster-tools:2.5.19]
 ```
 
 The fix is typically to pick the highest Akka version, and add explicit
 dependencies to your project as needed. For example, in the example above
-you might want to add dependencies on akka-protobuf:2.5.17 and
-akka-stream:2.5.17.
+you might want to add dependencies for 2.5.20.
 
 @@@ note
 

akka-docs/src/main/paradox/project/migration-guide-2.5.x-2.6.x.md

@@ -202,6 +202,14 @@ Classic remoting is deprecated but can be used in `2.6.` Explicitly disable Arte
 specific to classic remoting needs to be moved to `akka.remote.classic`. To see which configuration options
 are specific to classic search for them in: [`akka-remote/reference.conf`](/akka-remote/src/main/resources/reference.conf)
 
+### akka-protobuf
+
+`akka-protobuf` was never intended to be used by end users but perhaps this was not well-documented.
+Applications should use standard Protobuf dependency instead of `akka-protobuf`. The artifact is still
+published, but the transitive dependency to `akka-protobuf` has been removed.
+
+Akka is now using Protobuf version 3.9.0 for serialization of messages defined by Akka.
+
 ## Java Serialization
 
 Java serialization is known to be slow and [prone to attacks](https://community.hpe.com/t5/Security-Research/The-perils-of-Java-deserialization/ba-p/6838995)

akka-docs/src/main/paradox/serialization.md

@@ -234,6 +234,13 @@ Java
 
 The recommended approach to do deep serialization of internal actor state is to use Akka @ref:[Persistence](persistence.md).
 
+## Serialization of Akka's messages
+
+Akka is using a Protobuf 3 for serialization of messages defined by Akka. This dependency is
+shaded in the `akka-protobuf-v3` artifact so that applications can use another version of Protobuf.
+
+Applications should use standard Protobuf dependency and not `akka-protobuf-v3`.
+
 ## Java serialization
 
 Java serialization is known to be slow and [prone to attacks](https://community.hpe.com/t5/Security-Research/The-perils-of-Java-deserialization/ba-p/6838995)

akka-protobuf/src/main/java/akka/protobuf/GeneratedMessage.java

@@ -57,7 +57,13 @@ import java.util.TreeMap;
  * the Message interface directly.
  *
  * @author kenton@google.com Kenton Varda
+ *
+ * @deprecated akka-protobuf was never intended to be used by end users.
+ *   It is deprecated since 2.6.0 in favor of using Protobuf v3.
+ *   Applications should use standard Protobuf dependency instead of
+ *   akka-protobuf or akka-protobuf-v3.
  */
+@Deprecated
 public abstract class GeneratedMessage extends AbstractMessage
     implements Serializable {
   private static final long serialVersionUID = 1L;