Compatibility guide for Kotlin 1.4

Keeping the Language Modern and Comfortable Updates are among the fundamental principles in Kotlin Language Design. The former says that constructs which obstruct language evolution should be removed, and the latter says that this removal should be well-communicated beforehand to make code migration as smooth as possible.

While most of the language changes were already announced through other channels, like update changelogs or compiler warnings, this document summarizes them all, providing a complete reference for migration from Kotlin 1.3 to Kotlin 1.4.

Basic terms

In this document we introduce several kinds of compatibility:

source: source-incompatible change stops code that used to compile fine (without errors or warnings) from compiling anymore
binary: two binary artifacts are said to be binary-compatible if interchanging them doesn't lead to loading or linkage errors
behavioral: a change is said to be behavioral-incompatible if the same program demonstrates different behavior before and after applying the change

Remember that those definitions are given only for pure Kotlin. Compatibility of Kotlin code from the other languages perspective (for example, from Java) is out of the scope of this document.

Language and stdlib

Unexpected behavior with in infix operator and ConcurrentHashMap

Prohibit access to protected members inside public inline members

Contracts on calls with implicit receivers

Inconsistent behavior of floating-point number comparisons

No smart cast on the last expression in a generic lambda

Do not depend on the order of lambda arguments to coerce result to Unit

Wrong common supertype between raw and integer literal type leads to unsound code

Type safety problem because several equal type variables are instantiated with a different types

Type safety problem because of incorrect subtyping for intersection types

No type mismatch with an empty when expression inside lambda

Return type Any inferred for lambda with early return with integer literal in one of possible return values

Proper capturing of star projections with recursive types

Common supertype calculation with non-proper type and flexible one leads to incorrect results

Type safety problem because of lack of captured conversion against nullable type argument

Preserve intersection type for covariant types after unchecked cast

Type variable leaks from builder inference because of using this expression

Wrong overload resolution for contravariant types with nullable type arguments

Builder inference with non-nested recursive constraints

Eager type variable fixation leads to a contradictory constraint system

Prohibit tailrec modifier on open functions

The INSTANCE field of a companion object more visible than the companion object class itself

Outer finally block inserted before return is not excluded from the catch interval of the inner try block without finally

Use the boxed version of an inline class in return type position for covariant and generic-specialized overrides

Do not declare checked exceptions in JVM bytecode when using delegation to Kotlin interfaces

Changed behavior of signature-polymorphic calls to methods with a single vararg parameter to avoid wrapping the argument into another array

Incorrect generic signature in annotations when KClass is used as a generic parameter

Forbid spread operator in signature-polymorphic calls

Change initialization order of default values for tail-recursive optimized functions

Do not generate ConstantValue attribute for non-const vals

Generated overloads for @JvmOverloads on open methods should be final

Lambdas returning kotlin.Result now return boxed value instead of unboxed

Unify exceptions from null checks

Comparing floating-point values in array/list operations contains, indexOf, lastIndexOf: IEEE 754 or total order

Gradually change the return type of collection min and max functions to non-nullable

Deprecate appendln in favor of appendLine

Deprecate conversions of floating-point types to Short and Byte

Fail fast in Regex.findAll on an invalid startIndex

Remove deprecated kotlin.coroutines.experimental

Remove deprecated mod operator

Hide Throwable.addSuppressed member and prefer extension instead

capitalize should convert digraphs to title case

Tools

Compiler arguments with delimiter characters must be passed in double quotes on Windows

KAPT: Names of synthetic $annotations() methods for properties have changed

Last modified: 25 September 2024