Compatibility guide for Kotlin 1.7

tip

Issue: KT-46860

Component: Core language

Incompatible change type: source

Short summary: Kotlin 1.7 will consider the type of safe call result always nullable, even when the receiver of the safe call is non-nullable

Deprecation cycle:

• <1.3: report a warning on an unnecessary safe call on non-nullable receivers

• 1.6.20: warn additionally that the result of an unnecessary safe call will change its type in the next version

• 1.7.0: change the type of safe call result to nullable,

  
  

  -XXLanguage:-SafeCallsAreAlwaysNullable can be used to temporarily revert to the pre-1.7 behavior

tip

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 an error if a super call, in fact, accesses an abstract member from a superclass

• 1.7.0: report an error 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 all cases

tip

Issue: KT-28078

Component: Core language

Incompatible change type: source

Short summary: Kotlin will prevent declaring public properties having non-public types in a private primary constructor. Accessing such properties from another package could lead to an IllegalAccessError

Deprecation cycle:

• 1.3.20: report a warning on a public property that has a non-public type and is declared in a non-public constructor

• 1.6.20: raise this warning to an error in the progressive mode

• 1.7.0: raise this warning to an error

tip

Issue: KT-41124

Component: Core language

Incompatible change type: source

Short summary: Kotlin 1.7 will prohibit access to uninitialized enum entries from the enum static initializer block when these entries are qualified with the enum name

Deprecation cycle:

• 1.7.0: report an error when uninitialized enum entries are accessed from the enum static initializer block

tip

Issue: KT-39883

Component: Core language

Incompatible change type: source

Short summary: Kotlin will no longer make exhaustiveness and control flow assumptions based on constant boolean expressions other than literal true and false

Deprecation cycle:

• 1.5.30: report a warning when exhaustiveness of when or control flow reachability is determined based on a complex constant boolean expression in when branch or loop condition

• 1.7.0: raise this warning to an error

tip

Issue: KT-47709

Component: Core language

Incompatible change type: source

Short summary: Kotlin 1.7 will report an error about the when statement with an enum, sealed, or Boolean subject being non-exhaustive

Deprecation cycle:

• 1.6.0: introduce a warning when the when statement with an enum, sealed, or Boolean subject is non-exhaustive (error in the progressive mode)

• 1.7.0: raise this warning to an error

tip

Issue: KT-48385

Component: Core language

Incompatible change type: source

Short summary: Kotlin 1.6 deprecated several confusing grammar constructs in when condition expressions

Deprecation cycle:

• 1.6.20: introduce a deprecation warning on the affected expressions

• 1.8.0: raise this warning to an error

• >= 1.8: repurpose some deprecated constructs for new language features

tip

Issue: KT-48623

Component: Kotlin/JVM

Incompatible change type: source

Short summary: Kotlin 1.7 will change how it loads and interprets type nullability annotations in Java code

Deprecation cycle:

• 1.4.30: introduce warnings for cases where more precise type nullability could lead to an error

• 1.7.0: infer more precise nullability of Java types, -XXLanguage:-TypeEnhancementImprovementsInStrictMode can be used to temporarily revert to the pre-1.7 behavior

tip

Issue: KT-48645

Component: Kotlin/JVM

Incompatible change type: behavioral

Short summary: Kotlin will avoid converting numeric values automatically to a primitive numeric type where only a downcast to that type was needed semantically

Deprecation cycle:

• < 1.5.30: the old behavior in all affected cases

• 1.5.30: fix the downcast behavior in generated property delegate accessors, -Xuse-old-backend can be used to temporarily revert to the pre-1.5.30 fix behavior

• >= 1.7.20: fix the downcast behavior in other affected cases

tip

Issue: KT-46329

Component: Kotlin/JVM

Incompatible change type: source

Short summary: Kotlin 1.6.20 warns about the usage of enable and compatibility modes of the -Xjvm-default compiler option

Deprecation cycle:

• 1.6.20: introduce a warning on the enable and compatibility modes of the -Xjvm-default compiler option

• >= 1.8.0: raise this warning to an error

tip

Issue: KT-22562

Component: Core language

Incompatible change type: source

Short summary: Kotlin 1.6 no longer allows calling user functions named suspend that have the single argument of a functional type passed as a trailing lambda

Deprecation cycle:

• 1.3.0: introduce a warning on such function calls

• 1.6.0: raise this warning to an error

• 1.7.0: introduce changes to the language grammar so that suspend before { is parsed as a keyword

tip

Issue: KT-52629

Component: Core language

Incompatible change type: source

Short summary: Kotlin 1.7 will no longer allow smart casts on properties of a superclass if that class is located in another module

Deprecation cycle:

• 1.6.0: report a warning on a smart cast on a property declared in the superclass located in another module

• 1.7.0: raise this warning to an error,

  
  

  -XXLanguage:-ProhibitSmartcastsOnPropertyFromAlienBaseClass can be used to temporarily revert to the pre-1.7 behavior

tip

Issue: KT-52668

Component: Core language

Incompatible change type: source

Short summary: Kotlin 1.4−1.6 neglected some type constraints during type inference due to an incorrect optimization. It could allow writing unsound code, causing ClassCastException at runtime. Kotlin 1.7 takes these constraints into account, thus prohibiting the unsound code

Deprecation cycle:

• 1.5.20: report a warning on expressions where a type mismatch would happen if all the type inference constraints were taken into account

• 1.7.0: take all the constraints into account, thus raising this warning to an error,

  
  

  -XXLanguage:-ProperTypeInferenceConstraintsProcessing can be used to temporarily revert to the pre-1.7 behavior

tip

Issue: KT-38854

Component: kotlin-stdlib

Incompatible change type: source

Short summary: the return type of collection min and max functions will be changed to non-nullable in Kotlin 1.7

Deprecation cycle:

• 1.4.0: introduce ...OrNull functions as synonyms and deprecate the affected API (see details in the issue)

• 1.5.0: raise the deprecation level of the affected API to an error

• 1.6.0: hide the deprecated functions from the public API

• 1.7.0: reintroduce the affected API but with non-nullable return type

tip

Issue: KT-28753

Component: kotlin-stdlib

Incompatible change type: source

Short summary: Kotlin deprecates floating-point array functions contains, indexOf, lastIndexOf that compare values using the IEEE-754 order instead of the total order

Deprecation cycle:

• 1.4.0: deprecate the affected functions with a warning

• 1.6.0: raise the deprecation level to an error

• 1.7.0: hide the deprecated functions from the public API

tip

Issue: KT-39330

Component: kotlin-stdlib (JS)

Incompatible change type: source

Short summary: declarations from the kotlin.dom and kotlin.browser packages are moved to the corresponding kotlinx.* packages to prepare for extracting them from stdlib

Deprecation cycle:

• 1.4.0: introduce the replacement API in kotlinx.dom and kotlinx.browser packages

• 1.4.0: deprecate the API in kotlin.dom and kotlin.browser packages and propose the new API above as a replacement

• 1.6.0: raise the deprecation level to an error

• >= 1.8: remove the deprecated functions from stdlib

• >= 1.8: move the API in kotlinx.* packages to a separate library

tip

Issue: KT-48587

Component: kotlin-stdlib (JS)

Incompatible change type: source

Short summary: a number of JS-only functions in stdlib are deprecated for removal. They include: String.concat(String), String.match(regex: String), String.matches(regex: String), and the sort functions on arrays taking a comparison function, for example, Array<out T>.sort(comparison: (a: T, b: T) -> Int)

Deprecation cycle:

• 1.6.0: deprecate the affected functions with a warning

• 1.8.0: raise the deprecation level to an error

• 1.9.0: remove the deprecated functions from the public API

tip

Issue: KT-48831

Component: Gradle

Incompatible change type: source

Short summary: remove the KotlinGradleSubplugin class. Use the KotlinCompilerPluginSupportPlugin class instead

Deprecation cycle:

• 1.6.0: raise the deprecation level to an error

• 1.7.0: remove the deprecated class

tip

Issue: KT-48847

Component: Gradle

Incompatible change type: source

Short summary: remove the deprecated and hidden useIR compiler option

Deprecation cycle:

• 1.5.0: raise the deprecation level to a warning

• 1.6.0: hide the option

• 1.7.0: remove the deprecated option

tip

Issue: KT-48826

Component: Gradle

Incompatible change type: source

Short summary: deprecate the kapt.use.worker.api property that allowed to run kapt via Gradle Workers API (default: true)

Deprecation cycle:

• 1.6.20: raise the deprecation level to a warning

• >= 1.8.0: remove this property

tip

Issue: KT-50494

Component: Gradle

Incompatible change type: source

Short summary: remove the kotlin.experimental.coroutines Gradle DSL option and the kotlin.coroutines property

Deprecation cycle:

• 1.6.20: raise the deprecation level to a warning

• 1.7.0: remove the DSL option, its enclosing experimental block, and the property

tip

Issue: KT-47763

Component: Gradle

Incompatible change type: source

Short summary: remove the hidden useExperimentalAnnotation() Gradle function used to opt in to using an API in a module. optIn() function can be used instead

Deprecation cycle:

• 1.6.0: hide the deprecation option

• 1.7.0: remove the deprecated option

tip

Issue: KT-51830

Component: Gradle

Incompatible change type: source

Short summary: deprecate the kotlin.compiler.execution.strategy system property used to choose a compiler execution strategy. Use the Gradle property kotlin.compiler.execution.strategy or the compile task property compilerExecutionStrategy instead

Deprecation cycle:

• 1.7.0: raise the deprecation level to a warning

• > 1.7.0: remove the property

tip

Issue: KT-46541

Component: Gradle

Incompatible change type: source

Short summary: remove the kotlinOptions.jdkHome compiler option used to include a custom JDK from the specified location into the classpath instead of the default JAVA_HOME. Use Java toolchains instead

Deprecation cycle:

• 1.5.30: raise the deprecation level to a warning

• > 1.7.0: remove the option

tip

Issue: KT-49011

Component: Gradle

Incompatible change type: source

Short summary: remove the noStdlib compiler option. The Gradle plugin uses the kotlin.stdlib.default.dependency=true property to control whether the Kotlin standard library is present

Deprecation cycle:

• 1.5.0: raise the deprecation level to a warning

• 1.7.0: remove the option

tip

Issue: KT-48276

Component: Gradle

Incompatible change type: source

Short summary: remove the kotlin2js and kotlin-dce-plugin plugins. Instead of kotlin2js, use the new org.jetbrains.kotlin.js plugin. Dead code elimination (DCE) works when the Kotlin/JS Gradle plugin is properly configured

tip

Deprecation cycle:

• 1.4.0: raise the deprecation level to a warning

• 1.7.0: remove the plugins

tip

Issue: KT-32805

Component: Gradle

Incompatible change type: source

Short summary: Kotlin compile tasks no longer inherit the Gradle AbstractCompile task and that's why the sourceCompatibility and targetCompatibility inputs are no longer available in Kotlin users' scripts. The SourceTask.stableSources input is no longer available. The sourceFilesExtensions input was removed. The deprecated Gradle destinationDir: File output was replaced with the destinationDirectory: DirectoryProperty output. The classpath property of the KotlinCompile task is deprecated

Deprecation cycle:

• 1.7.0: inputs are not available, the output is replaced, the classpath property is deprecated