Replace "experimental" with "may change" (#22326)
* Replacing "experimental" with "may change" #22305 * Right syntax for links * Correct annotation name * Final small changes
This commit is contained in:
Johan Andrén
Patrik Nordwall
parent
a7dfaf00a4
commit
64b35cf1f1
21 changed files with 114 additions and 114 deletions
|
|
@ -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
|
||||
akka-contrib subproject), then when the feature is hardened, well documented and
|
||||
next step would be to add it to Akka as an "may change"-feature (in the
|
||||
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
|
||||
|
||||
|
|
|
|||
|
|
@ -5,6 +5,7 @@ Additional Information
|
|||
:maxdepth: 2
|
||||
|
||||
../common/binary-compatibility-rules
|
||||
../common/may-change
|
||||
faq
|
||||
books
|
||||
osgi
|
||||
|
|
|
|||
|
|
@ -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 "experimental"
|
||||
=============================
|
||||
**Experimental** is a keyword used in module descriptions as well as their artifact names,
|
||||
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.
|
||||
The meaning of "may change"
|
||||
===========================
|
||||
**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.
|
||||
Read more in :ref:`may-change`.
|
||||
|
||||
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
|
||||
"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.
|
||||
- ``@ApiMayChange`` – which marks APIs which are known to be not fully stable yet. Read more in :ref:`may-change`
|
||||
- ``@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
|
||||
|
|
|
|||
49
akka-docs/rst/common/may-change.rst
Normal file
49
akka-docs/rst/common/may-change.rst
Normal file
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
|
@ -4,29 +4,5 @@
|
|||
Experimental Modules
|
||||
####################
|
||||
|
||||
The following modules of Akka are marked as experimental, which means
|
||||
that they are in early access mode, which also means that they are not
|
||||
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
|
||||
|
||||
The label experimental caused confusion and discomfort and has therefore been replaced with "May Change"
|
||||
please see :ref:`may-change`.
|
||||
|
|
|
|||
|
|
@ -4,30 +4,5 @@
|
|||
Experimental Modules
|
||||
####################
|
||||
|
||||
The following modules of Akka are marked as experimental, which means
|
||||
that they are in early access mode, which also means that they are not
|
||||
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
|
||||
|
||||
The label experimental caused confusion and discomfort and has therefore been replaced with "May Change"
|
||||
please see :ref:`may-change`.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -17,7 +17,6 @@ Java Documentation
|
|||
java/http/index
|
||||
java/howto
|
||||
java/scala-compat
|
||||
experimental/index-java
|
||||
dev/index
|
||||
project/index
|
||||
additional/index
|
||||
|
|
|
|||
|
|
@ -6,8 +6,8 @@ Remoting (codename Artery)
|
|||
|
||||
.. note::
|
||||
|
||||
This page describes the experimental remoting subsystem, codenamed *Artery* that will eventually replace the
|
||||
old remoting implementation. For the current stable remoting system please refer to :ref:`remoting-java`.
|
||||
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-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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -16,7 +16,6 @@ Scala Documentation
|
|||
scala/stream/index
|
||||
scala/http/index
|
||||
scala/howto
|
||||
experimental/index
|
||||
dev/index
|
||||
project/index
|
||||
additional/index
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -6,10 +6,10 @@ Akka Typed
|
|||
|
||||
.. warning::
|
||||
|
||||
This module is currently experimental in the sense of being the subject of
|
||||
active research. This means that API or semantics can change without warning
|
||||
or deprecation period and it is not recommended to use this module in
|
||||
production just yet—you have been warned.
|
||||
This module is currently marked as :ref:`may change <may-change>` in the sense
|
||||
of being the subject of active research. This means that API or semantics can
|
||||
change without warning or deprecation period and it is not recommended to use
|
||||
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
|
||||
multiple major releases of Akka and the plain ``akka.actor.Actor`` will not be
|
||||
deprecated or go away anytime soon.
|
||||
will take a long time. We expect that this module will stay marked
|
||||
:ref:`may change <may-change>` for multiple major releases of Akka and the
|
||||
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
|
||||
|
|
|
|||
|
|
@ -1,4 +1,5 @@
|
|||
import akka.{AkkaBuild, Formatting}
|
||||
|
||||
AkkaBuild.mayChangeSettings
|
||||
AkkaBuild.defaultSettings
|
||||
Formatting.formatSettings
|
||||
|
|
|
|||
|
|
@ -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 ⇒
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
import akka.{ AkkaBuild, Formatting }
|
||||
|
||||
AkkaBuild.defaultSettings
|
||||
AkkaBuild.experimentalSettings
|
||||
AkkaBuild.mayChangeSettings
|
||||
Formatting.formatSettings
|
||||
|
||||
disablePlugins(MimaPlugin)
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|experimental module may be dropped in major releases
|
||||
|refine and simplify based on your feedback. Additionally
|
||||
|such a module may be dropped in major releases
|
||||
|without prior deprecation.
|
||||
|""".stripMargin
|
||||
)
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue