Binary Compatibility Rules
Akka maintains and verifies backwards binary compatibility across versions of modules.
In the rest of this document whenever binary compatibility is mentioned "backwards binary compatibility" is meant (as opposed to forward compatibility).
This means that the new JARs are a drop-in replacement for the old one (but not the other way around) as long as your build does not enable the inliner (Scala-only restriction).
Binary compatibility rules explained
Binary compatibility is maintained between:
- minor and patch versions - please note that the meaning of "minor" has shifted to be more restrictive with Akka
2.4.0, read Change in versioning scheme, stronger compatibility since 2.4 for details.
Binary compatibility is NOT maintained between:
- major versions
- any versions of experimental modules – read The meaning of "experimental" for details
- a few notable exclusions explained below
Specific examples (please read Change in versioning scheme, stronger compatibility since 2.4 to understand the difference in "before 2.4 era" and "after 2.4 era"):
# [epoch.major.minor] era
OK: 2.2.0 --> 2.2.1 --> ... --> 2.2.x
NO: 2.2.y --x 2.3.y
OK: 2.3.0 --> 2.3.1 --> ... --> 2.3.x
OK: 2.3.x --> 2.4.x (special case, migration to new versioning scheme)
# [major.minor.path] era
OK: 2.4.0 --> 2.5.x
OK: 2.5.0 --> 2.6.x
NO: 2.x.y --x 3.x.y
OK: 3.0.0 --> 3.0.1 --> ... --> 3.0.n
OK: 3.0.n --> 3.1.0 --> ... --> 3.1.n
OK: 3.1.n --> 3.2.0 ...
...
Cases where binary compatibility is not retained
Some modules are excluded from the binary compatibility guarantees, such as:
*-testkitmodules - since these are to be used only in tests, which usually are re-compiled and run on demand
*-tckmodules - since they may want to add new tests (or force configuring something), in order to discover possiblefailures 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 experimental modules - which by definition are subject to rapid iteration and change. Read more about them in The meaning of "experimental"
Change in versioning scheme, stronger compatibility since 2.4
Since the release of Akka 2.4.0 a new versioning scheme is in effect.
Historically, Akka has been following the Java or Scala style of versioning where as the first number would mean "epoch",
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.
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
(and many issues have been fixed ever since).
Mixed versioning is not allowed
Modules that are released together under the Akka project are intended to be upgraded together.
For example, it is not legal to mix Akka Actor 2.4.2 with Akka Cluster 2.4.5 even though
"Akka 2.4.2" and "Akka 2.4.5" are binary compatible.
This is because modules may assume internals changes across module boundaries, for example some feature in Clustering may have required an internals change in Actor, however it is not public API, 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.
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 INTERNAL API
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.
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.
Side-note on JVM representation details of the Scala private[akka] pattern that Akka is using extensively in
it's internals: Such methods or classes, which act as "accessible only from the given package" in Scala, are compiled
down to public (!) in raw Java bytecode, and the access restriction, that Scala understands is carried along
as metadata stored in the classfile. Thus, such methods are safely guarded from being accessed from Scala,
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.
Binary Compatibility Checking Toolchain
Akka uses the Lightbend maintained Migration Manager,
called MiMa for short, for enforcing binary compatibility is kept where it was promised.
All Pull Requests must pass MiMa validation (which happens automatically), and if failures are detected, manual exception overrides may be put in place if the change happened to be in an Internal API for example.
Contents
