Kotlin Help

Compatibility guide for Kotlin 2.1

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 2.0 to Kotlin 2.1.

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

Change the typeOf() function behavior on Kotlin/Native

Prohibit exposing types through type parameters' bounds

Prohibit inheriting an abstract var property and a val property with the same name

Report error when accessing uninitialized enum entries

Changes in K2 smart cast propagation

Correct the handling of member-extension property overrides in Java subclasses

Correct visibility alignment for getters and setters of var properties overriding a protected val

Raise severity of JSpecify nullability mismatch diagnostics to errors

Change overload resolution to prioritize extension functions over invoke calls in ambiguous cases

Prohibit returning nullable values from lambdas in SAM constructors of JDK function interfaces

Correct handling of private members conflicting with public members in Kotlin/Native

Forbid access to private operator functions in public inline functions

Prohibit passing invalid arguments to invariant parameters annotated with @UnsafeVariance

Report nullability errors for error-level nullable arguments of warning-level Java types

Report implicit usages of inaccessible types

Standard library

Deprecate locale-sensitive case conversion functions for Char and String

Remove kotlin-stdlib-common JAR artifact

Deprecate appendln() in favor of appendLine()

Change Map.Entry behavior to fail-fast on structural modification

Tools

Deprecate KotlinCompilationOutput#resourcesDirProvider

Deprecate registerKotlinJvmCompileTask(taskName, moduleName) function

Deprecate registerKaptGenerateStubsTask(taskName) function

Deprecate KotlinTopLevelExtension and KotlinTopLevelExtensionConfig interfaces

Remove kotlin-compiler-embeddable from build runtime dependencies

Hide compiler symbols from the Kotlin Gradle Plugin API

Add support for multiple stability configuration files

Remove deprecated platform plugin IDs

Last modified: 26 November 2024
FAQCompatibility guide for Kotlin 2.0