Replace "experimental" with "may change" (#22326)

* Replacing "experimental" with "may change" #22305

* Right syntax for links

* Correct annotation name

* Final small changes

CONTRIBUTING.md

@@ -300,11 +300,12 @@ You can read up on `remaining` and friends in [TestKit.scala](https://github.com
 
 For external contributions of entire features, the normal way is to establish it
 as a stand-alone feature first, to show that there is a need for the feature. The
-next step would be to add it to Akka as an "experimental feature" (in the
+next step would be to add it to Akka as an "may change"-feature (in the
-akka-contrib subproject), then when the feature is hardened, well documented and
+akka-contrib subproject) and marking it's public api with the `ApiMayChange` annotation, 
+then when the feature is hardened, well documented and
 tested it becomes an officially supported Akka feature.
 
-[List of experimental Akka features](http://doc.akka.io/docs/akka/current/experimental/index.html)
+[List of Akka features marked as may change](http://doc.akka.io/docs/akka/current/common/may-change.html)
 
 # Supporting infrastructure
 

akka-docs/rst/additional/index.rst

@@ -5,6 +5,7 @@ Additional Information
    :maxdepth: 2
 
    ../common/binary-compatibility-rules
+   ../common/may-change
    faq
    books
    osgi

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

@@ -20,7 +20,7 @@ Binary compatibility is maintained between:
 Binary compatibility is **NOT** maintained between:
 
 - **major** versions
-- any versions of **experimental** modules – read :ref:`meaning-of-experimental` for details
+- any versions of **may change** modules – read :ref:`may-change` for details
 - a few notable exclusions explained below
 
 Specific examples (please read :ref:`24versioningChange` to understand the difference in "before 2.4 era" and "after 2.4 era")::
@@ -47,7 +47,7 @@ Some modules are excluded from the binary compatibility guarantees, such as:
   - ``*-tck`` modules     - since they may want to add new tests (or force configuring something), in order to discover possible 
                             failures in an existing implementation that the TCK is supposed to be testing. 
                             Compatibility here is not *guaranteed*, however it is attempted to make the upgrade prosess as smooth as possible.
-  - all :ref:`experimental <meaning-of-experimental>` modules - which by definition are subject to rapid iteration and change. Read more about them in :ref:`meaning-of-experimental`
+  - all :ref:`may change <may-change>` modules - which by definition are subject to rapid iteration and change. Read more about that in :ref:`may-change`
 
 .. _24versioningChange:
 
@@ -59,7 +59,7 @@ Historically, Akka has been following the Java or Scala style of versioning wher
 the second one would mean **major**, and third be the **minor**, thus: ``epoch.major.minor`` (versioning scheme followed until and during ``2.3.x``).
 
 **Currently**, since Akka ``2.4.0``, the new versioning applies which is closer to semantic versioning many have come to expect, 
-in which the version number is deciphered as ``major.minor.patch``. This also means that Akka ``2.5.x`` is binary compatible with the ``2.4`` series releases (with the exception of experimental APIs of course).
+in which the version number is deciphered as ``major.minor.patch``. This also means that Akka ``2.5.x`` is binary compatible with the ``2.4`` series releases (with the exception of "may change" APIs of course).
 
 In addition to that, Akka ``2.4.x`` has been made binary compatible with the ``2.3.x`` series,
 so there is no reason to remain on Akka 2.3.x, since upgrading is completely compatible 
@@ -80,25 +80,11 @@ thus such change is considered safe.
   We recommend keeping an ``akkaVersion`` variable in your build file, and re-use it for all 
   included modules, so when you upgrade you can simply change it in this one place.
 
-.. _meaning-of-experimental:
+The meaning of "may change"
-
+===========================
-The meaning of "experimental"
+**May change** is used in module descriptions and docs in order to signify that the API that they contain
-=============================
+is subject to change without any prior warning and is not covered by the binary compatibility promise.
-**Experimental** is a keyword used in module descriptions as well as their artifact names,
+Read more in :ref:`may-change`.
-in order to signify that the API that they contain is subject to change without any prior warning.
-
-Experimental modules are are not covered by Lightbend's Commercial Support, unless specifically stated otherwise.
-The purpose of releasing them early, as 
-experimental, is to make them easily available and improve based on 
-feedback, or even discover that the module wasn't useful.
-
-An experimental module doesn't have to obey the rule of staying binary
-compatible between micro releases. Breaking API changes may be introduced
-in minor releases without notice as we refine and simplify based on your
-feedback. An experimental module may be dropped in minor releases without 
-prior deprecation.
-
-Best effort migration guides may be provided, but this is decided on a case-by-case basis for **experimental** modules.
 
 API stability annotations and comments
 ======================================
@@ -130,11 +116,7 @@ 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 
+- ``@ApiMayChange`` – which marks APIs which are known to be not fully stable yet. Read more in :ref:`may-change`
-  "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 

akka-docs/rst/common/may-change.rst

@@ -0,0 +1,49 @@
+
+.. _may-change:
+
+###########################
+Modules marked "May Change"
+###########################
+
+To be able to introduce new modules and APIs without freezing them the moment they
+are released because of our :ref:`binary compatibility guarantees <BinCompatRules>` we have introduced
+the term **may change**.
+
+Concretely **may change** means that an API or module is in early access mode and that it:
+
+- is not covered by Lightbend's commercial support (unless specifically stated otherwise)
+- is not guaranteed to be binary compatible in minor releases
+- may have its API change in breaking ways in minor releases
+- may be entirely dropped from Akka in a minor release
+
+Complete modules can be marked as **may change**, this will can be found in their module description and in the docs.
+
+Individual public APIs can be annotated with ``akka.api.annotation.ApiMayChange`` to signal that it has less
+guarantees than the rest of the module it lives in. 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.
+
+Best effort migration guides may be provided, but this is decided on a case-by-case basis for **may change** modules.
+
+The purpose of this is to be able to release features early and
+make them easily available and improve based on feedback, or even discover
+that the module or API wasn't useful.
+
+These are the current complete modules marked as **may change**:
+
+.. toctree::
+   :maxdepth: 1
+
+   ../dev/multi-node-testing
+   ../scala/typed
+
+Another reason for marking a module as "may change" is that it's too early
+to tell if the module has a maintainer that can take the responsibility
+of the module over time. These modules live in the ``akka-contrib`` subproject:
+
+.. toctree::
+   :maxdepth: 1
+
+   ../contrib/index

akka-docs/rst/dev/multi-jvm-testing.rst

@@ -201,7 +201,7 @@ Multi Node Additions
 ====================
 
 There has also been some additions made to the ``SbtMultiJvm`` plugin to accommodate the
-:ref:`experimental <experimental>` module :ref:`multi node testing <multi-node-testing>`,
+:ref:`may change <may-change>` module :ref:`multi node testing <multi-node-testing>`,
 described in that section.
 
 .. _sample project: @samples@/tree/master/akka-sample-multi-node-scala

akka-docs/rst/experimental/index-java.rst

@@ -4,29 +4,5 @@
 Experimental Modules
 ####################
 
-The following modules of Akka are marked as experimental, which means
+The label experimental caused confusion and discomfort and has therefore been replaced with "May Change"
-that they are in early access mode, which also means that they are not
+please see :ref:`may-change`.
-covered by commercial support. The purpose of releasing them early, as 
-experimental, is to make them easily available and improve based on 
-feedback, or even discover that the module wasn't useful.
-
-An experimental module doesn't have to obey the rule of staying binary
-compatible between micro releases. Breaking API changes may be introduced
-in minor releases without notice as we refine and simplify based on your
-feedback. An experimental module may be dropped in minor releases without 
-prior deprecation.
-
-.. toctree::
-   :maxdepth: 1
-
-   ../dev/multi-node-testing
-
-Another reason for marking a module as experimental is that it's too early
-to tell if the module has a maintainer that can take the responsibility
-of the module over time. These modules live in the ``akka-contrib`` subproject:
-
-.. toctree::
-   :maxdepth: 1
-
-   ../contrib/index
-

akka-docs/rst/experimental/index.rst

@@ -4,30 +4,5 @@
 Experimental Modules
 ####################
 
-The following modules of Akka are marked as experimental, which means
+The label experimental caused confusion and discomfort and has therefore been replaced with "May Change"
-that they are in early access mode, which also means that they are not
+please see :ref:`may-change`.
-covered by commercial support. The purpose of releasing them early, as 
-experimental, is to make them easily available and improve based on 
-feedback, or even discover that the module wasn't useful.
-
-An experimental module doesn't have to obey the rule of staying binary
-compatible between micro releases. Breaking API changes may be introduced
-in minor releases without notice as we refine and simplify based on your
-feedback. An experimental module may be dropped in minor releases without 
-prior deprecation.
-
-.. toctree::
-   :maxdepth: 1
-
-   ../dev/multi-node-testing
-   ../scala/typed
-
-Another reason for marking a module as experimental is that it's too early
-to tell if the module has a maintainer that can take the responsibility
-of the module over time. These modules live in the ``akka-contrib`` subproject:
-
-.. toctree::
-   :maxdepth: 1
-
-   ../contrib/index
-

akka-docs/rst/intro/getting-started.rst

@@ -56,7 +56,7 @@ Akka is very modular and consists of several JARs containing different features.
 - ``akka-testkit`` – Toolkit for testing Actor systems
 
 In addition to these stable modules there are several which are on their way
-into the stable core but are still marked “experimental” at this point. This
+into the stable core but are still marked :ref:`may change <may-change>` at this point. This
 does not mean that they do not function as intended, it primarily means that
 their API has not yet solidified enough in order to be considered frozen. You
 can help accelerating this process by giving feedback on these modules on our

akka-docs/rst/java.rst

@@ -17,7 +17,6 @@ Java Documentation
    java/http/index
    java/howto
    java/scala-compat
-   experimental/index-java
    dev/index
    project/index
    additional/index

akka-docs/rst/java/remoting-artery.rst

@@ -6,8 +6,8 @@ Remoting (codename Artery)
 
 .. note::
 
-  This page describes the experimental remoting subsystem, codenamed *Artery* that will eventually replace the
+  This page describes the :ref:`may change <may-change>` remoting subsystem, codenamed *Artery* that will eventually
-  old remoting implementation. For the current stable remoting system please refer to :ref:`remoting-java`.
+  replace the old remoting implementation. For the current stable remoting system please refer to :ref:`remoting-java`.
 
 Remoting enables Actor systems on different hosts or JVMs to communicate with each other. By enabling remoting
 the system will start listening on a provided network address and also gains the ability to connect to other

akka-docs/rst/java/stream/stream-customize.rst

@@ -362,7 +362,7 @@ Integration with actors
 -----------------------
 
 **This section is a stub and will be extended in the next release**
-**This is an experimental feature***
+**This is a :ref:`may change <may-change>` feature***
 
 It is possible to acquire an ActorRef that can be addressed from the outside of the stage, similarly how
 :class:`AsyncCallback` allows injecting asynchronous events into a stage logic. This reference can be obtained

akka-docs/rst/project/migration-guide-2.4.x-2.5.x.rst

@@ -10,7 +10,7 @@ Actor (Java)
 AbstractActor
 -------------
 
-``AbstractActor`` has been promoted from its experimental state and while doing this we
+``AbstractActor`` has been promoted from its experimental/may change state and while doing this we
 did some small, but important, improvements to the API that will require some mechanical
 changes of your source code.
 
@@ -491,7 +491,7 @@ for Scala and :ref:`Java <stream-integrations-java>`.
 
 The consuming actor may be a plain ``Actor`` or an ``PersistentActor`` if it needs to store its own state (e.g. ``fromSequenceNr`` offset).
 
-Please note that Persistence Query is not experimental anymore in Akka ``2.5.0``, so you can safely upgrade to it.
+Please note that Persistence Query is not experimental/may-change anymore in Akka ``2.5.0``, so you can safely upgrade to it.
 
 Persistence Plugin Proxy
 ------------------------
@@ -548,3 +548,16 @@ the Agents, as they rarely are really enough and do not fit the Akka spirit of t
 We also anticipate to replace the uses of Agents by the upcoming Akka Typed, so in preparation thereof the Agents have been deprecated in 2.5.
 
 If you use Agents and would like to take over the maintanance thereof, please contact the team on gitter or github.
+
+Akka Typed
+==========
+
+With the new term :ref:`may change <may-change>` we will no longer have a different artifact for modules that are not
+stable, and ``akka-typed-experimental`` has therefore been renamed to ``akka-typed``. Note that it is still not
+promoted to a stable module.
+
+Experimental modules
+====================
+
+We have previously marked modules that we did not want to freeze the APIs of a **experimental**, such modules will
+instead be marked as :ref:`may change <may-change>` from now on.

akka-docs/rst/scala.rst

@@ -16,7 +16,6 @@ Scala Documentation
    scala/stream/index
    scala/http/index
    scala/howto
-   experimental/index
    dev/index
    project/index
    additional/index

akka-docs/rst/scala/remoting-artery.rst

@@ -6,7 +6,7 @@ Remoting (codename Artery)
 
 .. note::
 
-  This page describes the experimental remoting subsystem, codenamed *Artery* that will eventually replace the
+  This page describes the :ref:`may change <may-change>` remoting subsystem, codenamed *Artery* that will eventually replace the
   old remoting implementation. For the current stable remoting system please refer to :ref:`remoting-scala`.
 
 Remoting enables Actor systems on different hosts or JVMs to communicate with each other. By enabling remoting

akka-docs/rst/scala/stream/stream-customize.rst

@@ -367,7 +367,7 @@ Integration with actors
 -----------------------
 
 **This section is a stub and will be extended in the next release**
-**This is an experimental feature***
+**This is a :ref:`may change <may-change>` feature***
 
 It is possible to acquire an ActorRef that can be addressed from the outside of the stage, similarly how
 :class:`AsyncCallback` allows injecting asynchronous events into a stage logic. This reference can be obtained

akka-docs/rst/scala/typed.rst

@@ -6,10 +6,10 @@ Akka Typed
 
 .. warning::
 
-  This module is currently experimental in the sense of being the subject of
+  This module is currently marked as :ref:`may change <may-change>` in the sense
-  active research. This means that API or semantics can change without warning
+  of being the subject of active research. This means that API or semantics can
-  or deprecation period and it is not recommended to use this module in
+  change without warning or deprecation period and it is not recommended to use
-  production just yet—you have been warned.
+  this module in production just yet—you have been warned.
 
 As discussed in :ref:`actor-systems` (and following chapters) Actors are about
 sending messages between independent units of computation, but how does that
@@ -283,9 +283,9 @@ Status of this Project and Relation to Akka Actors
 Akka Typed is the result of many years of research and previous attempts
 (including Typed Channels in the 2.2.x series) and it is on its way to
 stabilization, but maturing such a profound change to the core concept of Akka
-will take a long time. We expect that this module will stay experimental for
+will take a long time. We expect that this module will stay marked
-multiple major releases of Akka and the plain ``akka.actor.Actor`` will not be
+:ref:`may change <may-change>` for multiple major releases of Akka and the
-deprecated or go away anytime soon.
+plain ``akka.actor.Actor`` will not be deprecated or go away anytime soon.
 
 Being a research project also entails that the reference documentation is not
 as detailed as it will be for a final version, please refer to the API

akka-multi-node-testkit/build.sbt

@@ -1,4 +1,5 @@
 import akka.{AkkaBuild, Formatting}
 
+AkkaBuild.mayChangeSettings
 AkkaBuild.defaultSettings
 Formatting.formatSettings

akka-stream/src/main/scala/akka/stream/stage/GraphStage.scala

@@ -3,17 +3,21 @@
  */
 package akka.stream.stage
 
-import java.util.concurrent.atomic.{ AtomicReference }
+import java.util.concurrent.atomic.AtomicReference
+
 import akka.NotUsed
 import java.util.concurrent.locks.ReentrantLock
+
 import akka.actor._
-import akka.japi.function.{ Effect, Procedure }
+import akka.annotation.ApiMayChange
+import akka.japi.function.{Effect, Procedure}
 import akka.stream._
 import akka.stream.impl.StreamLayout.Module
-import akka.stream.impl.fusing.{ GraphInterpreter, GraphStageModule, SubSource, SubSink }
+import akka.stream.impl.fusing.{GraphInterpreter, GraphStageModule, SubSink, SubSource}
 import akka.stream.impl.ReactiveStreamsCompliance
+
 import scala.collection.mutable.ArrayBuffer
-import scala.collection.{ immutable, mutable }
+import scala.collection.{immutable, mutable}
 import scala.concurrent.duration.FiniteDuration
 import akka.stream.actor.ActorSubscriberMessage
 
@@ -921,6 +925,7 @@ abstract class GraphStageLogic private[stream] (val inCount: Int, val outCount:
    * @return minimal actor with watch method
    */
   // FIXME: I don't like the Pair allocation :(
+  @ApiMayChange
   final protected def getStageActor(receive: ((ActorRef, Any)) ⇒ Unit): StageActor = {
     _stageActor match {
       case null ⇒

akka-typed/build.sbt

@@ -1,7 +1,7 @@
 import akka.{ AkkaBuild, Formatting }
 
 AkkaBuild.defaultSettings
-AkkaBuild.experimentalSettings
+AkkaBuild.mayChangeSettings
 Formatting.formatSettings
 
 disablePlugins(MimaPlugin)

project/AkkaBuild.scala

@@ -96,7 +96,7 @@ object AkkaBuild extends Build {
   )
 
   lazy val typed = Project(
-    id = "akka-typed-experimental",
+    id = "akka-typed",
     base = file("akka-typed"),
     dependencies = Seq(testkit % "compile;test->test")
   )
@@ -294,16 +294,16 @@ object AkkaBuild extends Build {
     publishArtifact := false
   ) ++ dontPublishSettings
 
-  lazy val experimentalSettings = Seq(
+  lazy val mayChangeSettings = Seq(
     description := """|This module of Akka is marked as
-                      |experimental, which means that it is in early
+                      |'may change', which means that it is in early
                       |access mode, which also means that it is not covered
-                      |by commercial support. An experimental module doesn't
+                      |by commercial support. An module marked 'may change' doesn't
                       |have to obey the rule of staying binary compatible
                       |between minor releases. Breaking API changes may be
                       |introduced in minor releases without notice as we
-                      |refine and simplify based on your feedback. An
+                      |refine and simplify based on your feedback. Additionally
-                      |experimental module may be dropped in major releases
+                      |such a module may be dropped in major releases
                       |without prior deprecation.
                       |""".stripMargin
   )

project/ValidatePullRequest.scala

@@ -83,7 +83,6 @@ object ValidatePullRequest extends AutoPlugin {
   def changedDirectoryIsDependency(changedDirs: Set[String],
                                     name: String,
                                     graphsToTest: Seq[(Configuration, ModuleGraph)])(log: Logger): Boolean = {
-    val dirsOrExperimental = changedDirs.flatMap(dir => Set(dir, s"$dir-experimental"))
     graphsToTest exists { case (ivyScope, deps) =>
       log.debug(s"Analysing [$ivyScope] scoped dependencies...")
 
@@ -92,7 +91,7 @@ object ValidatePullRequest extends AutoPlugin {
       // if this project depends on a modified module, we must test it
       deps.nodes.exists { m =>
         // match just by name, we'd rather include too much than too little
-        val dependsOnModule = dirsOrExperimental.find(m.id.name contains _)
+        val dependsOnModule = changedDirs.find(m.id.name contains _)
         val depends = dependsOnModule.isDefined
         if (depends) log.info(s"Project [$name] must be verified, because depends on [${dependsOnModule.get}]")
         depends