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