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