+doc document DoNotInherit and ApiMayChange

akka-actor/src/main/java/akka/annotation/DoNotInherit.java

@@ -23,5 +23,4 @@ import java.lang.annotation.*;
 @Retention(RetentionPolicy.CLASS) // to be accessible by MiMa
 @Target({ElementType.TYPE})
 public @interface DoNotInherit {
-  String description();
 }

akka-actor/src/main/scala/akka/actor/AbstractActor.scala

@@ -4,6 +4,8 @@
 
 package akka.actor
 
+import akka.annotation.ApiMayChange
+
 /**
  * Java API: compatible with lambda expressions
  *
@@ -44,6 +46,7 @@ object AbstractActor {
  *
  * This is an EXPERIMENTAL feature and is subject to change until it has received more real world testing.
  */
+@ApiMayChange
 abstract class AbstractActor extends Actor {
 
   private var _receive: Receive = null

akka-actor/src/main/scala/akka/actor/AbstractFSM.scala

@@ -4,6 +4,8 @@
 
 package akka.actor
 
+import akka.annotation.ApiMayChange
+
 import scala.concurrent.duration.FiniteDuration
 
 /**
@@ -11,6 +13,7 @@ import scala.concurrent.duration.FiniteDuration
  *
  * This is an EXPERIMENTAL feature and is subject to change until it has received more real world testing.
  */
+@ApiMayChange
 object AbstractFSM {
   /**
    * A partial function value which does not match anything and can be used to

akka-docs/rst/common/binary-compatibility-rules.rst

@@ -100,11 +100,20 @@ prior deprecation.
 
 Best effort migration guides may be provided, but this is decided on a case-by-case basis for **experimental** modules.
 
-The meaning of INTERNAL API
+API stability annotations and comments
-===========================
+======================================
+
+Akka gives a very strong binary compatibility promise to end-users. However some parts of Akka are excluded 
+from these rules, for example internal or known evolving APIs may be marked as such and shipped as part of 
+an overall stable module. As general rule any breakage is avoided and handled via deprecation and additional method,
+however certain APIs which are known to not yet be fully frozen (or are fully internal) are marked as such and subject 
+to change at any time (even if best-effort is taken to keep them compatible).
+
+The INTERNAL API and `@InternalAPI` marker
+------------------------------------------
 When browsing the source code and/or looking for methods available to be called, especially from Java which does not
 have as rich of an access protection system as Scala has, you may sometimes find methods or classes annotated with
-the ``/** INTERNAL API */`` comment. 
+the ``/** INTERNAL API */`` comment or the ``@akka.annotation.InternalApi`` annotation. 
 
 No compatibility guarantees are given about these classes, they may change or even disapear in minor versions, 
 and user code is not supposed to be calling (or even touching) them.
@@ -116,6 +125,25 @@ as metadata stored in the classfile. Thus, such methods are safely guarded from
 however Java users will not be warned about this fact by the ``javac`` compiler. Please be aware of this and do not call
 into Internal APIs, as they are subject to change without any warning.
 
+The ``@DoNotInherit`` and ``@ApiMayChange`` markers
+---------------------------------------------------
+
+In addition to the special internal API marker two annotations exist in Akka and specifically address the following use cases:
+
+- ``@ApiMayChange`` – which marks APIs which are known to be not fully stable yet. For example, when while introducing 
+  "new" Java 8 APIs into existing stable modules, these APIs may be marked with this annotation to signal that they are
+  not frozen yet. Please use such methods and classes with care, however if you see such APIs that is the best point in 
+  time to try them out and provide feedback (e.g. using the akka-user mailing list, github issues or gitter) before they 
+  are frozen as fully stable API.
+- ``@DoNotInherit`` – which marks APIs that are designed under an closed-world assumption, and thus must not be 
+  extended outside Akka itself (or such code will risk facing binary incompatibilities). E.g. an interface may be 
+  marked using this annotation, and while the type is public, it is not meant for extension by user-code. This allows 
+  adding new methods to these interfaces without risking to break client code. Examples of such API are the ``FlowOps`` 
+  trait or the Akka HTTP domain model.
+
+Please note that a best-effort approach is always taken when having to change APIs and breakage is avoided as much as 
+possible, however these markers allow to experiment, gather feedback and stabilize the best possible APIs we could build.
+
 Binary Compatibility Checking Toolchain
 =======================================
 Akka uses the Lightbend maintained `Migration Manager <https://github.com/typesafehub/migration-manager>`_, 

akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala

@@ -11,14 +11,15 @@ import akka.stream.impl._
 import akka.stream.impl.fusing._
 import akka.stream.stage._
 import org.reactivestreams.{Processor, Publisher, Subscriber, Subscription}
+
 import scala.annotation.unchecked.uncheckedVariance
 import scala.collection.immutable
 import scala.concurrent.Future
 import scala.concurrent.duration.FiniteDuration
 import scala.language.higherKinds
 import akka.stream.impl.fusing.FlattenMerge
-
 import akka.NotUsed
+import akka.annotation.DoNotInherit
 
 /**
  * A `Flow` is a set of stream processing steps that has one open input and one open output.
@@ -369,6 +370,7 @@ final case class RunnableGraph[+Mat](val module: StreamLayout.Module) extends Gr
  *
  * Binary compatibility is only maintained for callers of this trait’s interface.
  */
+@DoNotInherit
 trait FlowOps[+Out, +Mat] {
   import akka.stream.impl.Stages._
   import GraphDSL.Implicits._