A Deeper Dive into Compatibility Concepts

The core idea behind all these "compatibilities" is answering the question: "If I update a library, what might break for people who are already using it?"

Let's imagine you are the author of a popular library, AwesomeLibrary, and a developer, "Alex," is using it in their app.

1. Binary Compatibility (The "Plug-and-Play" Contract)

• What it is: This is the most strict and important type of compatibility. It means that an app (a binary file, like an .apk or .jar) that was compiled with an OLD version of your library will still run correctly with a NEW version of your library, without needing to be recompiled. The user can just drop in the new library file, and the app won't crash on startup.

• Analogy: A Physical Power Adapter Imagine Alex's app has a plug designed for your library's three-pronged socket.

  • A Compatible Change: You update your library by making the internal wiring more efficient. The socket still has three prongs in the same shape and position. Alex can unplug the old version and plug in the new one. It just works.
  • An Incompatible Change: You decide to "improve" your library by removing one of the prongs from the socket. When Alex's app tries to plug into the new version, the plug doesn't fit. The program can't even start and crashes immediately. This is a binary incompatibility.

• Technical Example: You delete a public method fun doSomething(). Alex's app was compiled expecting that method to exist. When the app runs and tries to call doSomething(), the runtime system (the JVM) can't find it and throws a NoSuchMethodError. The app crashes.

• Why it's the Strictest: It's about the physical "shape" of the compiled code. Any change to the shape (deleting methods, changing method signatures in certain ways) breaks this contract. Metalava aims for 100% enforcement here because breaking binary compatibility is a severe issue.