Compatibility guide for Kotlin 1.8

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.7 to Kotlin 1.8.

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

Prohibit the delegation of super calls to an abstract superclass member

Issues: KT-45508, KT-49017, KT-38078

Component: Core language

Incompatible change type: source

Short summary: Kotlin will report a compile error when an explicit or implicit super call is delegated to an abstract member of the superclass, even if there's a default implementation in a super interface

Deprecation cycle:

1.5.20: introduce a warning when non-abstract classes that do not override all abstract members are used
1.7.0: report a warning if a super call, in fact, accesses an abstract member from a superclass
1.7.0: report an error in all affected cases if the -Xjvm-default=all or -Xjvm-default=all-compatibility compatibility modes are enabled; report an error in the progressive mode
1.8.0: report an error in cases of declaring a concrete class with a non-overridden abstract method from the superclass, and super calls of Any methods are overridden as abstract in the superclass
1.9.0: report an error in all affected cases, including explicit super calls to an abstract method from the super class

Deprecate confusing grammar in when-with-subject

Prevent implicit coercions between different numeric types

Make private constructors of sealed classes really private

Issue: KT-44866

Component: Core language

Incompatible change type: source

Short summary: after relaxing restrictions on where the inheritors of sealed classes could be declared in the project structure, the default visibility of sealed class constructors became protected. However, until 1.8, Kotlin still allowed calling explicitly declared private constructors of sealed classes outside those classes' scopes

Deprecation cycle:

1.6.20: report a warning (or an error in the progressive mode) when a private constructor of a sealed class is called outside that class
1.8.0: use default visibility rules for private constructors (a call to a private constructor can be resolved only if this call is inside the corresponding class), the old behavior can be brought back temporarily by specifying the -XXLanguage:-UseConsistentRulesForPrivateConstructorsOfSealedClasses compiler argument

Prohibit using operator == on incompatible numeric types in builder inference context

Prohibit if without else and non-exhaustive when in right hand side of elvis operator

Prohibit upper bound violation in a generic type alias usage (one type parameter used in several type arguments of the aliased type)

Prohibit upper bound violation in a generic type alias usage (a type parameter used in a generic type argument of a type argument of the aliased type)

Prohibit using a type parameter declared for an extension property inside delegate

Forbid @Synchronized annotation on suspend functions

Prohibit using spread operator for passing arguments to non-vararg parameters

Prohibit null-safety violation in lambdas passed to functions overloaded by lambda return type

Keep nullability when approximating local types in public signatures

Issue: KT-53982

Component: Core language

Incompatible change type: source, binary

Short summary: when a local or anonymous type is returned from an expression-body function without an explicitly specified return type, Kotlin compiler infers (or approximates) the return type using the known supertype of that type. During this, the compiler can infer a non-nullable type where the null value could in fact be returned

Deprecation cycle:

1.8.0: approximate flexible types by flexible supertypes
1.8.0: report a warning when a declaration is inferred to have a non-nullable type that should be nullable, prompting users to specify the type explicitly
1.9.0: approximate nullable types by nullable supertypes, -XXLanguage:-KeepNullabilityWhenApproximatingLocalType can be used to temporarily revert to the pre-1.9 behavior

Do not propagate deprecation through overrides

Prohibit implicit inferring a type variable into an upper bound in the builder inference context

Prohibit using collection literals in annotation classes anywhere except their parameters declaration

Prohibit forward referencing of parameters with default values in default value expressions

Prohibit extension calls on inline functional parameters

Prohibit calls to infix functions named suspend with an anonymous function argument

Prohibit using captured type parameters in inner classes against their variance

Prohibit recursive call of a function without explicit return type in compound assignment operators

Prohibit unsound calls with expected @NotNull T and given Kotlin generic parameter with nullable bound

Prohibit access to members of a companion of an enum class from entry initializers of this enum

Deprecate and remove Enum.declaringClass synthetic property

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

Standard library

Warn about potential overload resolution change when Range/Progression starts implementing Collection

Issue: KT-49276

Component: Core language / kotlin-stdlib

Incompatible change type: source

Short summary: it is planned to implement the Collection interface in the standard progressions and concrete ranges inherited from them in Kotlin 1.9. This could make a different overload selected in the overload resolution if there are two overloads of some method, one accepting an element and another accepting a collection. Kotlin will make this situation visible by reporting a warning or an error when such overloaded method is called with a range or progression argument

Deprecation cycle:

1.6.20: report a warning when an overloaded method is called with the standard progression or its range inheritor as an argument if implementing the Collection interface by this progression/range leads to another overload being selected in this call in future
1.8.0: raise this warning to an error
1.9.0: stop reporting the error, implement Collection interface in progressions thus changing the overload resolution result in the affected cases

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

Deprecate some JS-only API

Tools

Raise deprecation level of classpath property of KotlinCompile task

Remove kapt.use.worker.api Gradle property

Remove kotlin.compiler.execution.strategy system property

Changes in compiler options

Issues: KT-27301, KT-48532

Component: Gradle

Incompatible change type: source, binary

Short summary: this change might affect Gradle plugins authors. In kotlin-gradle-plugin, there are additional generic parameters to some internal types (you should add generic types or *). KotlinNativeLink task does not inherit the AbstractKotlinNativeCompile task anymore. KotlinJsCompilerOptions.outputFile and the related KotlinJsOptions.outputFile options are deprecated. Use the Kotlin2JsCompile.outputFileProperty task input instead. The kotlinOptions task input and the kotlinOptions{...} task DSL are in a support mode and will be deprecated in upcoming releases. compilerOptions and kotlinOptions can not be changed on a task execution phase (see one exception in What's new in Kotlin 1.8). freeCompilerArgs returns an immutable List<String> – kotlinOptions.freeCompilerArgs.remove("something") will fail. The useOldBackend property that allowed to use the old JVM backend is removed

Deprecation cycle:

1.8.0: KotlinNativeLink task does not inherit the AbstractKotlinNativeCompile. KotlinJsCompilerOptions.outputFile and the related KotlinJsOptions.outputFile options are deprecated. The useOldBackend property that allowed to use the old JVM backend is removed.

Deprecate kotlin.internal.single.build.metrics.file property

Last modified: 30 December 2022