Konrad Malawski
parent
2c47f1883d
commit
74b8d749b6
2 changed files with 126 additions and 0 deletions
|
|
@ -4,6 +4,7 @@ Additional Information
|
|||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
../common/binary-compatibility-rules
|
||||
faq
|
||||
books
|
||||
language-bindings
|
||||
|
|
|
|||
125
akka-docs/rst/common/binary-compatibility-rules.rst
Normal file
125
akka-docs/rst/common/binary-compatibility-rules.rst
Normal file
|
|
@ -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 <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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue