| # 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. |
| |
