diff --git a/akka-docs/rst/additional/index.rst b/akka-docs/rst/additional/index.rst index be35078c23..03e8a81966 100644 --- a/akka-docs/rst/additional/index.rst +++ b/akka-docs/rst/additional/index.rst @@ -4,6 +4,7 @@ Additional Information .. toctree:: :maxdepth: 2 + ../common/binary-compatibility-rules faq books language-bindings diff --git a/akka-docs/rst/common/binary-compatibility-rules.rst b/akka-docs/rst/common/binary-compatibility-rules.rst new file mode 100644 index 0000000000..bd327869b6 --- /dev/null +++ b/akka-docs/rst/common/binary-compatibility-rules.rst @@ -0,0 +1,125 @@ +.. _BinCompatRules: + +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 :ref:`24versioningChange` for details. + +Binary compatibility is **NOT** maintained between: + +- **major** versions +- any versions of **experimental** modules – read :ref:`meaning-of-experimental` 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"):: + + # [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: + + - ``*-testkit`` modules - since these are to be used only in tests, which usually are re-compiled and run on demand + - ``*-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 ` modules - which by definition are subject to rapid iteration and change. Read more about them in :ref:`meaning-of-experimental` + +.. _24versioningChange: + +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. + +.. note:: + 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 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.