125 lines
6.6 KiB
ReStructuredText
125 lines
6.6 KiB
ReStructuredText
.. _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 <meaning-of-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 <https://github.com/typesafehub/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.
|