Backward compatibility guidelines for library authors

Binary compatibility means that a new version of a library can replace a previously compiled version of the library. Any software that was compiled against the previous version of the library should continue to work correctly.

tip
Learn more about binary compatibility in the Binary compatibility validator's README or from the Evolving Java-based APIs document.

Source compatibility means that a new version of a library can replace a previous one without modifying any of the source code that uses the library. However, the outputs from compiling this client code may no longer be compatible with the outputs from compiling the library, so the client code must be rebuilt against the new version of the library to guarantee compatibility.

Behavioral compatibility means that a new version of the library does not modify the existing functionality, except to fix bugs. The same features are involved and they have the same semantics.

Use the Binary compatibility validator

The apiCheck task is invoked at build time by the standard Gradle check task. When compatibility is broken, the build fails. At that point, you should run the apiDump task manually and compare the differences between the old and new versions. If you are satisfied with the changes, you can update the existing .api file, which resides within your VCS.

Specify return types explicitly

Consider the following example, where the library author creates a JsonDeserializer and, for convenience, uses an extension function to associate it with the Int type:

class JsonDeserializer<T>(private val fromJson: (String) -> T) {
    fun deserialize(input: String): T {
        ...
    }
}

fun Int.defaultDeserializer() = JsonDeserializer { ... }

Let's say the author replaces this implementation with a JsonOrXmlDeserializer:

class JsonOrXmlDeserializer<T>(
    private val fromJson: (String) -> T,
    private val fromXML: (String) -> T
) {
    fun deserialize(input: String): T {
        ...
    }
}

fun Int.defaultDeserializer() = JsonOrXmlDeserializer({ ... }, { ... })

Avoid adding arguments to existing API functions

For example, imagine you have the following function in lib.kt:

fun fib() = … // Returns zero

And the following function in client.kt:

fun main() {
    println(fib()) // Prints zero
}

Compiling these two files on the JVM would produce the outputs LibKt.class and ClientKt.class.

Let's say you reimplement and compile the fib function to represent the Fibonacci sequence, such that fib(3) returns 2, fib(4) returns 3, and so on. You add a parameter but give it a default value of zero to preserve the existing behavior:

fun fib(input: Int = 0) = … // Returns Fibonacci member

You now need to recompile the file lib.kt. You might expect that the client.kt file does not need to be recompiled, and the associated class file can be invoked as follows:

$ kotlin ClientKt.class

But if you try this, a NoSuchMethodError occurs:

Exception in thread "main" java.lang.NoSuchMethodError: 'int LibKt.fib()'
       at LibKt.main(fib.kt:2)
       at LibKt.main(fib.kt)
       …

When writing Kotlin code for the JVM, you can use the @JvmOverloads annotation on functions with default arguments. This generates overloads of the function, one for each parameter with a default argument that may be omitted from the end of the parameter list. With these individual generated functions, adding a new parameter to the end of the parameter list preserves binary compatibility, as it doesn't change any existing functions in the output, just adds a new one.

For example, the above function might be annotated like this:

@JvmOverloads
fun fib(input: Int = 0) = …

This would generate two methods in the output bytecode, one with no parameter and one with an Int parameter:

public final static fib()I
public final static fib(I)I

For all Kotlin targets, you may choose to manually create several overloads of your function instead of a single function that accepts default arguments to preserve binary compatibility. In the example above, this means creating a separate fib function for the case where you wish to take an Int parameter:

fun fib() = …
fun fib(input: Int) = …

Avoid widening or narrowing return types

When evolving an API, it is common to want to widen or narrow the return type of a function. For example, in an upcoming version of your API, you might want to switch a return type from List to Collection or from Collection to List.

You might want to narrow the type to List to meet user requests for indexing support. Conversely, you might want to widen the type to Collection because you realize the data you are working with has no natural order.

It is easy to see why widening a return type breaks compatibility. For example, converting from List to Collection breaks all the code that uses indexing.

You might think that narrowing a return type, for example from Collection to List would preserve compatibility. Unfortunately, while source compatibility is preserved, binary compatibility is broken.

Let's say you have a demo function in the file Library.kt:

public fun demo(): Number = 3

And a client for the function in Client.kt:

fun main() {
    println(demo()) // Prints 3
}

Let's imagine a scenario where you change the return type of demo and only recompile Library.kt:

fun demo(): Int = 3

Exception in thread "main" java.lang.NoSuchMethodError: 'java.lang.Number Library.demo()'
        at ClientKt.main(call.kt:2)
        at ClientKt.main(call.kt)
        …

This happens because of the following instruction in the bytecode generated from the main method:

0: invokestatic  #12 // Method Library.demo:()Ljava/lang/Number;

The JVM is trying to invoke a static method called demo which returns a Number. However, as this method no longer exists, you have broken binary compatibility.

Avoid using data classes in your API

data class User(
    val name: String,
    val email: String
)

Later, you might want to add a property called active:

data class User(
    val name: String,
    val email: String,
    val active: Boolean = true
)

This would break binary compatibility in two ways. Firstly, the generated constructor will have a different signature. Additionally, the signature of the generated copy method changes.

public final User copy(java.lang.String, java.lang.String)

After adding the active property, the signature becomes:

public final User copy(java.lang.String, java.lang.String, boolean)

It's possible to work around these issues by manually writing a secondary constructor and overriding the copy method. However, the effort involved negates the convenience of using a data class.

Another issue with data classes is that changing the order of constructor arguments affects the generated componentX methods, which are used for destructuring. Even if it does not break binary compatibility, changing the order will definitely break behavioral compatibility.

Backward compatibility guidelines for library authors﻿

Compatibility types﻿

Use the Binary compatibility validator﻿

Specify return types explicitly﻿

Avoid adding arguments to existing API functions﻿

Use overloads to preserve compatibility﻿

Avoid widening or narrowing return types﻿

Avoid using data classes in your API﻿

Considerations for using the PublishedApi annotation﻿

Evolve APIs pragmatically﻿

Use the RequiresOptIn mechanism﻿

What's next﻿

Backward compatibility guidelines for library authors

Compatibility types

Use the Binary compatibility validator

Specify return types explicitly

Avoid adding arguments to existing API functions

Use overloads to preserve compatibility

Avoid widening or narrowing return types

Avoid using data classes in your API

Considerations for using the PublishedApi annotation

Evolve APIs pragmatically

Use the RequiresOptIn mechanism

What's next