54 lines
2.6 KiB
Markdown
54 lines
2.6 KiB
Markdown
|
# Compatibility
|
||
|
|
|
||
|
|
As stated in the README, one of Metalava's core functions is that it
|
||
|
|
can diff two versions of an API to determine compatibility. But what
|
||
|
|
does that word "compatibility" mean? This document details the definitions
|
||
|
|
Metalava maintainers have adopted then uses those definitions to outline
|
||
|
|
the specific compatibility that Metalava strives to uphold.
|
||
|
|
|
||
|
|
The inspiration for this comes from the [Evolving Java Based APIs series](https://wiki.eclipse.org/Evolving_Java-based_APIs)
|
||
|
|
in the Eclipse Wiki.
|
||
|
|
|
||
|
|
## Binary Compatibility
|
||
|
|
|
||
|
|
Binary compatibility is when **existing binaries correctly link with an updated library at load time**.
|
||
|
|
|
||
|
|
An example of a binary incompatibility is deleting a public method.
|
||
|
|
|
||
|
|
Metalava strives to prevent 100% of binary incompatible changes when performing
|
||
|
|
compatibility checks. In the context of semantic versioning, incompatibilities are only allowed at
|
||
|
|
major version bumps or by special exemption during certain later stages of release.
|
||
|
|
|
||
|
|
## Source Compatibility
|
||
|
|
|
||
|
|
Source compatibility is when **existing source compiles against an updated library without compile time errors**.
|
||
|
|
|
||
|
|
Examples of source incompatibilities are adding an enum value in Kotlin (due to exhaustive when checks) or
|
||
|
|
changing the name of a parameter.
|
||
|
|
|
||
|
|
Metalava warns or blocks on many forms of source incompatibility; however, 100% enforcement is not a goal.
|
||
|
|
about source compatibility than binary compatibility. Some forms of source incompatibility are simple to fix
|
||
|
|
and very difficult to avoid; therefore source compatibility is not considered a hard requirement for API Compatibility.
|
||
|
|
|
||
|
|
## Runtime Compatibility
|
||
|
|
|
||
|
|
Runtime compatibility is when **existing valid interactions with an updated library do not trigger unexpected exceptions at runtime**.
|
||
|
|
|
||
|
|
An example of runtime incompatibility is changing a method from nullable to non-null.
|
||
|
|
|
||
|
|
Runtime incompatibility is impossible to enforce with tooling, but is nice to have. Therefore Metalava strives
|
||
|
|
to prevent runtime incompatibility with it's checks, but cannot provide any assurances about it.
|
||
|
|
|
||
|
|
## API Contract Compatibility
|
||
|
|
|
||
|
|
|
||
|
|
API Contract Compatibility is when **existing client code is not invalidated by the new API**.
|
||
|
|
|
||
|
|
API compatibility is most strongly enforceable with Binary compatibility. Unfortunately,
|
||
|
|
it is extremely difficult to fully automate the detection of all Api Contract incompatibilities. For example,
|
||
|
|
if a method documents that it returns a non-empty list, then the comment changes to state that it allows
|
||
|
|
the return of an empty list, that breaks the API contract.
|
||
|
|
|
||
|
|
Metalava strives to maintain API Contract Compatibility as fully as possible.
|
||
|
|
|