Compatibility guide for Kotlin 1.6

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.5 to Kotlin 1.6.

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

Make when statements with enum, sealed, and Boolean subjects exhaustive by default

Deprecate confusing grammar in when-with-subject

Prohibit access to class members in the super constructor call of its companion and nested objects

Type nullability enhancement improvements

Prevent implicit coercions between different numeric types

Prohibit declarations of repeatable annotation classes whose container annotation violates JLS

Prohibit declaring a nested class named Container in a repeatable annotation class

Prohibit @JvmField on a property in the primary constructor that overrides an interface property

Deprecate the enable and the compatibility modes of the compiler option -Xjvm-default

Prohibit super calls from public-abi inline functions

Prohibit protected constructor calls from public inline functions

Prohibit exposing private nested types from private-in-file types

Annotation target is not analyzed in several cases for annotations on a type

Prohibit calls to functions named suspend with a trailing lambda

Standard library

Remove brittle contains optimization in minus/removeAll/retainAll

Change value generation algorithm in Random.nextLong

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

Deprecate floating-point array functions: contains, indexOf, lastIndexOf

Migrate declarations from kotlin.dom and kotlin.browser packages to kotlinx.*

Make Regex.replace function not inline in Kotlin/JS

Different behavior of the Regex.replace function in JVM and JS when replacement string contains group reference

Use the Unicode case folding in JS Regex

Deprecate some JS-only API

Hide implementation- and interop-specific functions from the public API of classes in Kotlin/JS

Tools

Deprecate KotlinGradleSubplugin class

Remove kotlin.useFallbackCompilerSearch build option

Remove several compiler options

Deprecate useIR compiler option

Deprecate kapt.use.worker.api Gradle property

Remove kotlin.parallel.tasks.in.project Gradle property

Deprecate kotlin.experimental.coroutines Gradle DSL option and kotlin.coroutines Gradle property

Last modified: 28 December 2022