1# Compatibility 2 3As stated in the README, one of Metalava's core functions is that it 4can diff two versions of an API to determine compatibility. But what 5does that word "compatibility" mean? This document details the definitions 6Metalava maintainers have adopted then uses those definitions to outline 7the specific compatibility that Metalava strives to uphold. 8 9The inspiration for this comes from the [Evolving Java Based APIs series](https://wiki.eclipse.org/Evolving_Java-based_APIs) 10in the Eclipse Wiki. 11 12## Binary Compatibility 13 14Binary compatibility is when **existing binaries correctly link with an updated library at load time**. 15 16An example of a binary incompatibility is deleting a public method. 17 18Metalava strives to prevent 100% of binary incompatible changes when performing 19compatibility checks. In the context of semantic versioning, incompatibilities are only allowed at 20major version bumps or by special exemption during certain later stages of release. 21 22## Source Compatibility 23 24Source compatibility is when **existing source compiles against an updated library without compile time errors**. 25 26Examples of source incompatibilities are adding an enum value in Kotlin (due to exhaustive when checks) or 27changing the name of a parameter. 28 29Metalava warns or blocks on many forms of source incompatibility; however, 100% enforcement is not a goal. 30about source compatibility than binary compatibility. Some forms of source incompatibility are simple to fix 31and very difficult to avoid; therefore source compatibility is not considered a hard requirement for API Compatibility. 32 33## Runtime Compatibility 34 35Runtime compatibility is when **existing valid interactions with an updated library do not trigger unexpected exceptions at runtime**. 36 37An example of runtime incompatibility is changing a method from nullable to non-null. 38 39Runtime incompatibility is impossible to enforce with tooling, but is nice to have. Therefore Metalava strives 40to prevent runtime incompatibility with it's checks, but cannot provide any assurances about it. 41 42## API Contract Compatibility 43 44 45API Contract Compatibility is when **existing client code is not invalidated by the new API**. 46 47API compatibility is most strongly enforceable with Binary compatibility. Unfortunately, 48it is extremely difficult to fully automate the detection of all Api Contract incompatibilities. For example, 49if a method documents that it returns a non-empty list, then the comment changes to state that it allows 50the return of an empty list, that breaks the API contract. 51 52Metalava strives to maintain API Contract Compatibility as fully as possible. 53 54