From 651cd6d0326afc6533848ebfefac63fd8ba8815d Mon Sep 17 00:00:00 2001 From: Sarah Haggarty Date: Wed, 5 Nov 2025 11:41:59 +0100 Subject: [PATCH 01/11] feat: add compatibility guide 2.3 # Conflicts: # docs/kr.tree --- .../compatibility-guide-23.md | 76 +++++++++++++++++++ 1 file changed, 76 insertions(+) create mode 100644 docs/topics/compatibility-guides/compatibility-guide-23.md diff --git a/docs/topics/compatibility-guides/compatibility-guide-23.md b/docs/topics/compatibility-guides/compatibility-guide-23.md new file mode 100644 index 00000000000..9f40bce40ad --- /dev/null +++ b/docs/topics/compatibility-guides/compatibility-guide-23.md @@ -0,0 +1,76 @@ +[//]: # (title: Compatibility guide for Kotlin 2.3) + +_[Keeping the Language Modern](kotlin-evolution-principles.md)_ and _[Comfortable Updates](kotlin-evolution-principles.md)_ 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.2 to Kotlin 2.3. + +## 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 + +### Enable invokedynamic for annotated lambdas by default + +> **Issue**: [KTLC-278](https://youtrack.jetbrains.com/issue/KTLC-278) +> +> **Component**: Core language +> +> **Incompatible change type**: behavioral +> +> **Short summary**: Lambdas with annotations now use `invokedynamic` through `LambdaMetafactory` by default, aligning their behavior with Java lambdas. +> This affects reflection-based code that relied on retrieving annotations from generated lambda classes. +> To revert to the old behavior, use the `-Xindy-allow-annotated-lambdas=false` compiler option. +> +> **Deprecation cycle**: +> +> - 2.2.0: enable `invokedynamic` for annotated lambdas by default + +## Standard library + +### Deprecate `kotlin.native.Throws` + +> **Issue**: [KT-72137](https://youtrack.jetbrains.com/issue/KT-72137) +> +> **Component**: Kotlin/Native +> +> **Incompatible change type**: source +> +> **Short summary**: `kotlin.native.Throws` is deprecated; use the common [`kotlin.Throws`](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-throws/) annotation instead. +> +> **Deprecation cycle**: +> +> - 1.9.0: report a warning when using `kotlin.native.Throws` +> - 2.2.0: raise the warning to an error + +## Kotlin/Native + +## Tools + +### Correct `setSource()` function in `KotlinCompileTool` to replace sources + +> **Issue**: [KT-59632](https://youtrack.jetbrains.com/issue/KT-59632) +> +> **Component**: Gradle +> +> **Incompatible change type**: behavioral +> +> **Short summary**: The [`setSource()`](https://kotlinlang.org/api/kotlin-gradle-plugin/kotlin-gradle-plugin-api/org.jetbrains.kotlin.gradle.tasks/-kotlin-compile-tool/set-source.html#) function in the [`KotlinCompileTool`](https://kotlinlang.org/api/kotlin-gradle-plugin/kotlin-gradle-plugin-api/org.jetbrains.kotlin.gradle.tasks/-kotlin-compile-tool/#) interface now replaces configured sources instead of adding to them. +> If you want to add sources without replacing existing ones, use the [`source()`](https://kotlinlang.org/api/kotlin-gradle-plugin/kotlin-gradle-plugin-api/org.jetbrains.kotlin.gradle.tasks/-kotlin-compile-tool/source.html#) function. +> +> **Deprecation cycle**: +> +> - 2.2.0: enable the new behavior From e6a2f13813d992450593d5c425bcdd2ff18b9f30 Mon Sep 17 00:00:00 2001 From: Sarah Haggarty Date: Wed, 5 Nov 2025 12:12:26 +0100 Subject: [PATCH 02/11] standard library tickets --- .../compatibility-guide-23.md | 72 +++++++++++++++++-- 1 file changed, 65 insertions(+), 7 deletions(-) diff --git a/docs/topics/compatibility-guides/compatibility-guide-23.md b/docs/topics/compatibility-guides/compatibility-guide-23.md index 9f40bce40ad..c3b2bf0474f 100644 --- a/docs/topics/compatibility-guides/compatibility-guide-23.md +++ b/docs/topics/compatibility-guides/compatibility-guide-23.md @@ -41,22 +41,80 @@ perspective (for example, from Java) is out of the scope of this document. ## Standard library -### Deprecate `kotlin.native.Throws` +### Deprecate `String.subSequence(start, end)` function -> **Issue**: [KT-72137](https://youtrack.jetbrains.com/issue/KT-72137) +> **Issue**: [KT-74493](https://youtrack.jetbrains.com/issue/KT-74493) > -> **Component**: Kotlin/Native +> **Component**: kotlin-stdlib +> +> **Incompatible change type**: source +> +> **Short summary**: The `String.subSequence(start, end)` function is deprecated. Use the [`String.subSequence(startIndex, endIndex)`](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/sub-sequence.html) function instead. +> +> **Deprecation cycle**: +> +> - 2.3.0: report an error when using `String.subSequence(start, end)` + +### Deprecate `kotlin.io.createTempDirectory()` and `kotlin.io.createTempFile()` functions + +> **Issue**: [KT-81078](https://youtrack.jetbrains.com/issue/KT-81078) +> +> **Component**: kotlin-stdlib +> +> **Incompatible change type**: source +> +> **Short summary**: The `kotlin.io.createTempDirectory()` and `kotlin.io.createTempFile()` functions are deprecated. +> Use the [`kotlin.io.path.createTempDirectory()`](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.io.path/create-temp-directory.html) and [`kotlin.io.path.createTempFile()`](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.io.path/create-temp-file.html) functions instead. +> +> **Deprecation cycle**: +> +> - 1.4.20: report a warning when using `kotlin.io.createTempDirectory()` and `kotlin.io.createTempFile()` functions +> - 2.3.0: raise the warning to an error + +### Deprecate `Number.toChar()` function + +> **Issue**: [KT-56822](https://youtrack.jetbrains.com/issue/KT-56822) +> +> **Component**: kotlin-stdlib +> +> **Incompatible change type**: source +> +> **Short summary**: The `Number.toChar()` function is deprecated. Use `toInt().toChar()` or the `Char` constructor instead. +> +> **Deprecation cycle**: +> +> - 1.9.0: report a warning when using the `Number.toChar()` function +> - 2.3.0: raise the warning to an error + +### Hide `InputStream.readBytes(Int)` function + +> **Issue**: [KT-79192](https://youtrack.jetbrains.com/issue/KT-79192) +> +> **Component**: kotlin-stdlib > > **Incompatible change type**: source > -> **Short summary**: `kotlin.native.Throws` is deprecated; use the common [`kotlin.Throws`](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-throws/) annotation instead. +> **Short summary**: After being deprecated for a long time, the `InputStream.readBytes(estimatedSize: Int = DEFAULT_BUFFER_SIZE): ByteArray` function is hidden. > > **Deprecation cycle**: > -> - 1.9.0: report a warning when using `kotlin.native.Throws` -> - 2.2.0: raise the warning to an error +> - 1.3.0: report a warning +> - 1.5.0: raise the warning to an error +> - 2.3.0: hide the function + +### Unify Kotlin/Native stacktrace printing with other platforms -## Kotlin/Native +> **Issue**: [KT-81431](https://youtrack.jetbrains.com/issue/KT-81431) +> +> **Component**: Kotlin/Native +> +> **Incompatible change type**: behavior +> +> **Short summary**: When formatting an exception stacktrace, no additional causes are printed once a previously seen exception cause has already been printed. +> +> **Deprecation cycle**: +> +> - 2.3.20: Unify Kotlin/Native exception stacktrace formatting with other Kotlin platforms ## Tools From 75d47a3d0fd3d265604eeae5fe673633bcd6ae17 Mon Sep 17 00:00:00 2001 From: Sarah Haggarty Date: Wed, 5 Nov 2025 16:12:30 +0100 Subject: [PATCH 03/11] language version --- .../compatibility-guide-23.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/docs/topics/compatibility-guides/compatibility-guide-23.md b/docs/topics/compatibility-guides/compatibility-guide-23.md index c3b2bf0474f..e233c6d0edc 100644 --- a/docs/topics/compatibility-guides/compatibility-guide-23.md +++ b/docs/topics/compatibility-guides/compatibility-guide-23.md @@ -23,6 +23,22 @@ perspective (for example, from Java) is out of the scope of this document. ## Language +### Remove language versions 1.8 and 1.9 + +> **Issue**: [KT-76343](https://youtrack.jetbrains.com/issue/KT-76343), [KT-76344](https://youtrack.jetbrains.com/issue/KT-76344). +> +> **Component**: Core language +> +> **Incompatible change type**: source +> +> **Short summary**: Kotlin 2.3 introduces language version 2.3 and removes support for language version 1.8. +> Support for language version 1.9 is also removed for non-JVM platforms. Language versions 1.8 and 1.9 are deprecated. +> +> **Deprecation cycle**: +> +> - 2.2.0: report a warning for language versions 1.8 and 1.9 +> - 2.3.0: raise the warning to an error for language version 1.8 on all platforms and for language version 1.9 on non-JVM platforms. + ### Enable invokedynamic for annotated lambdas by default > **Issue**: [KTLC-278](https://youtrack.jetbrains.com/issue/KTLC-278) From a5de69f4269aafe22cdf792d5486757f14d90b75 Mon Sep 17 00:00:00 2001 From: Daniel Csorba Date: Tue, 11 Nov 2025 07:16:54 +0100 Subject: [PATCH 04/11] update: adding info for KTLC-268/ KT-71822 --- .../compatibility-guide-23.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/topics/compatibility-guides/compatibility-guide-23.md b/docs/topics/compatibility-guides/compatibility-guide-23.md index e233c6d0edc..a55c1e4f8c8 100644 --- a/docs/topics/compatibility-guides/compatibility-guide-23.md +++ b/docs/topics/compatibility-guides/compatibility-guide-23.md @@ -132,6 +132,23 @@ perspective (for example, from Java) is out of the scope of this document. > > - 2.3.20: Unify Kotlin/Native exception stacktrace formatting with other Kotlin platforms +### Correct `Iterable.intersect()` and `Iterable.subtract()` behavior for referential-equality collections + +> **Issue**: [KTLC-268](https://youtrack.jetbrains.com/issue/KTLC-268) +> +> **Component**: kotlin-stdlib +> +> **Incompatible change type**: behavioral +> +> **Short summary**: The [`Iterable.intersect()`](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/intersect.html) and [`Iterable.subtract()`](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/subtract.html) functions now test membership for each +> receiver element before adding it to the result set. +> The result set compares elements using `Any::equals`, +> ensuring correct results even when the argument collection uses referential equality (for example, `IdentityHashMap.keys˙). +> +> **Deprecation cycle**: +> +> - 2.3.0: enable the new behavior + ## Tools ### Correct `setSource()` function in `KotlinCompileTool` to replace sources From 85020dd4bb69148ea4163e6908b1ab1c56ba5f8a Mon Sep 17 00:00:00 2001 From: Sarah Haggarty Date: Wed, 12 Nov 2025 15:46:40 +0100 Subject: [PATCH 05/11] language tickets --- .../compatibility-guide-23.md | 160 ++++++++++++++++-- 1 file changed, 144 insertions(+), 16 deletions(-) diff --git a/docs/topics/compatibility-guides/compatibility-guide-23.md b/docs/topics/compatibility-guides/compatibility-guide-23.md index a55c1e4f8c8..8fe8857089b 100644 --- a/docs/topics/compatibility-guides/compatibility-guide-23.md +++ b/docs/topics/compatibility-guides/compatibility-guide-23.md @@ -23,43 +23,172 @@ perspective (for example, from Java) is out of the scope of this document. ## Language -### Remove language versions 1.8 and 1.9 +### Drop support in `-language-version` for 1.8 and 1.9 > **Issue**: [KT-76343](https://youtrack.jetbrains.com/issue/KT-76343), [KT-76344](https://youtrack.jetbrains.com/issue/KT-76344). > -> **Component**: Core language +> **Component**: Compiler > > **Incompatible change type**: source > -> **Short summary**: Kotlin 2.3 introduces language version 2.3 and removes support for language version 1.8. -> Support for language version 1.9 is also removed for non-JVM platforms. Language versions 1.8 and 1.9 are deprecated. +> **Short summary**: Starting with Kotlin 2.3, the compiler no longer supports [`-language-version=1.8`](compiler-reference.md#language-version-version). +> Support for `-language-version=1.9` is also removed for non-JVM platforms. > > **Deprecation cycle**: > -> - 2.2.0: report a warning for language versions 1.8 and 1.9 +> - 2.2.0: report a warning when using `-language-version` with versions 1.8 and 1.9. > - 2.3.0: raise the warning to an error for language version 1.8 on all platforms and for language version 1.9 on non-JVM platforms. -### Enable invokedynamic for annotated lambdas by default +### Handle `UPPER_BOUND_VIOLATED` on implicit type arguments + +> **Issue**: [KTLC-287](https://youtrack.jetbrains.com/issue/KTLC-287) +> +> **Component**: Core language +> +> **Incompatible change type**: behavioral +> +> **Short summary**: Previously, the compiler never reported `UPPER_BOUND_VIOLATED` for implicit type parameters. This +> has been fixed in Kotlin 2.3.0 so that `UPPER_BOUND_VIOLATED` is reported consistently across all type parameters. +> +> **Deprecation cycle**: +> +> - 2.2.20: report deprecation warnings for bounds violations by implicit type arguments +> - 2.3.0: raise the warning to an error for `UPPER_BOUND_VIOLATED` on implicit type arguments + +### Prohibit `@JvmSerializableLambda` annotation on `inline` and `crossinline` lambdas + +> **Issue**: [KTLC-9](https://youtrack.jetbrains.com/issue/KTLC-9) +> +> **Component**: Core language +> +> **Incompatible change type**: behavioral +> +> **Short summary**: Prohibit adding the `@JvmSerializableLambda` annotation on `inline` and `crossinline` lambdas +> because it has no effect. `inline` and `crossinline` lambdas are not serializable. +> +> **Deprecation cycle**: +> +> - 2.1.20: report a warning when the `@JvmSerializableLambda` is applied to `inline` and `crossinline` lambdas +> - 2.3.0: raise the warning to an error; this change can be enabled in progressive mode + +### Prohibit delegating a Kotlin interface to a Java class when the generic signatures don't match + +> **Issue**: [KTLC-267](https://youtrack.jetbrains.com/issue/KTLC-267) +> +> **Component**: Core language +> +> **Incompatible change type**: behavioral +> +> **Short summary**: Kotlin 2.3.0 forbids delegation to a Java class that implements a generic interface method with +> a non-generic override. Previously, allowing this behavior led to type mismatches and `ClassCastException` reported at runtime. +> This change shifts the error from runtime to compile time. +> +> **Deprecation cycle**: +> +> - 2.1.20: report a warning +> - 2.3.0: raise the warning to an error + +### Deprecate unintended use of `return` in expression-bodied functions without explicit return type + +> **Issue**: [KTLC-288](https://youtrack.jetbrains.com/issue/KTLC-288) +> +> **Component**: Core language +> +> **Incompatible change type**: behavioral +> +> **Short summary**: Kotlin now deprecates using `return` inside expression bodies when the function's return type is not +> explicitly declared. +> +> **Deprecation cycle**: +> +> - 2.3.0: report a warning +> - 2.4.0: raise the warning to an error + +### Prohibit inheritance from nullable supertypes introduced via typealias + +> **Issue**: [KTLC-279](https://youtrack.jetbrains.com/issue/KTLC-279) +> +> **Component**: Core language +> +> **Incompatible change type**: behavioral +> +> **Short summary**: Kotlin now reports an error when attempting to inherit from a nullable typealias, consistent with +> how it already handles direct nullable supertypes. +> +> **Deprecation cycle**: +> +> - 2.2.0: report a warning +> - 2.3.0: raise the warning to an error + +### Unify generic signature generation for top-level lambdas and call arguments + +> **Issue**: [KTLC-277](https://youtrack.jetbrains.com/issue/KTLC-277) +> +> **Component**: Core language +> +> **Incompatible change type**: behavioral +> +> **Short summary**: Kotlin 2.3 uses the same type-checking logic for top-level lambdas as it does for lambdas passed +> as call arguments, ensuring consistent generic signature generation across both cases. +> +> **Deprecation cycle**: +> +> - 2.3.0: introduce new behavior; not applicable for progressive mode + +### Prohibit reified type parameters from being inferred as intersection types + +> **Issue**: [KTLC-13](https://youtrack.jetbrains.com/issue/KTLC-13) +> +> **Component**: Core language +> +> **Incompatible change type**: behavioral +> +> **Short summary**: Kotlin 2.3 prohibits situations where a reified type parameter is inferred to an intersection type, +> due to the risk of incorrect runtime behavior. +> +> **Deprecation cycle**: +> +> - 2.1.0: report a warning when a reified type parameter is inferred to an intersection type +> - 2.3.0: raise the warning to an error + +### Prohibit exposing less-visible types through type parameter bounds + +> **Issue**: [KTLC-275](https://youtrack.jetbrains.com/issue/KTLC-275) +> +> **Component**: Core language +> +> **Incompatible change type**: behavioral +> +> **Short summary**: Kotlin 2.3 forbids using type parameter bounds that expose types with more restrictive visibility +> than the function or declaration itself, aligning the rules for functions with those already applied to classes. +> +> **Deprecation cycle**: +> +> - 2.1.0: report a warning on the problematic type parameter bound +> - 2.3.0: raise the warning to an error + +### Deprecate misleading Char-to-number conversions and introduce explicit digit and code APIs -> **Issue**: [KTLC-278](https://youtrack.jetbrains.com/issue/KTLC-278) +> **Issue**: [KTLC-321](https://youtrack.jetbrains.com/issue/KTLC-321) > > **Component**: Core language > > **Incompatible change type**: behavioral > -> **Short summary**: Lambdas with annotations now use `invokedynamic` through `LambdaMetafactory` by default, aligning their behavior with Java lambdas. -> This affects reflection-based code that relied on retrieving annotations from generated lambda classes. -> To revert to the old behavior, use the `-Xindy-allow-annotated-lambdas=false` compiler option. +> **Short summary**: Kotlin 2.3 deprecates `Char.toX()` and `X.toChar()` conversions for numeric types and introduces new, +> explicit APIs for accessing a character's code and digit value. > > **Deprecation cycle**: > -> - 2.2.0: enable `invokedynamic` for annotated lambdas by default +> - 1.4.30: introduce new functions as Experimental +> - 1.5.0: promote the new functions to Stable; report warnings for old functions with suggestions for replacements +> - 2.3.0: raise the warnings to errors ## Standard library ### Deprecate `String.subSequence(start, end)` function -> **Issue**: [KT-74493](https://youtrack.jetbrains.com/issue/KT-74493) +> **Issue**: [KTLC-282](https://youtrack.jetbrains.com/issue/KTLC-282) > > **Component**: kotlin-stdlib > @@ -73,7 +202,7 @@ perspective (for example, from Java) is out of the scope of this document. ### Deprecate `kotlin.io.createTempDirectory()` and `kotlin.io.createTempFile()` functions -> **Issue**: [KT-81078](https://youtrack.jetbrains.com/issue/KT-81078) +> **Issue**: [KTLC-281](https://youtrack.jetbrains.com/issue/KTLC-281) > > **Component**: kotlin-stdlib > @@ -104,7 +233,7 @@ perspective (for example, from Java) is out of the scope of this document. ### Hide `InputStream.readBytes(Int)` function -> **Issue**: [KT-79192](https://youtrack.jetbrains.com/issue/KT-79192) +> **Issue**: [KTLC-280](https://youtrack.jetbrains.com/issue/KTLC-280) > > **Component**: kotlin-stdlib > @@ -141,8 +270,7 @@ perspective (for example, from Java) is out of the scope of this document. > **Incompatible change type**: behavioral > > **Short summary**: The [`Iterable.intersect()`](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/intersect.html) and [`Iterable.subtract()`](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/subtract.html) functions now test membership for each -> receiver element before adding it to the result set. -> The result set compares elements using `Any::equals`, +> receiver element before adding it to the result set. The result set compares elements using `Any::equals`, > ensuring correct results even when the argument collection uses referential equality (for example, `IdentityHashMap.keys˙). > > **Deprecation cycle**: From dc8435006b935fa0d20db2b8cd02f1b70ca94651 Mon Sep 17 00:00:00 2001 From: Sarah Haggarty Date: Thu, 13 Nov 2025 14:54:43 +0100 Subject: [PATCH 06/11] rebase on master --- docs/kr.tree | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/kr.tree b/docs/kr.tree index 2b0727930ea..182a87c21af 100644 --- a/docs/kr.tree +++ b/docs/kr.tree @@ -25,6 +25,7 @@ + From eeeec87e01a5a9d4421e3be1725db896b018cfe8 Mon Sep 17 00:00:00 2001 From: Sarah Haggarty Date: Thu, 13 Nov 2025 16:43:47 +0100 Subject: [PATCH 07/11] Filipp review --- docs/topics/compatibility-guides/compatibility-guide-23.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/topics/compatibility-guides/compatibility-guide-23.md b/docs/topics/compatibility-guides/compatibility-guide-23.md index 8fe8857089b..17d9276bfe6 100644 --- a/docs/topics/compatibility-guides/compatibility-guide-23.md +++ b/docs/topics/compatibility-guides/compatibility-guide-23.md @@ -198,7 +198,8 @@ perspective (for example, from Java) is out of the scope of this document. > > **Deprecation cycle**: > -> - 2.3.0: report an error when using `String.subSequence(start, end)` +> - 1.0: report a warning when using `String.subSequence(start, end)` +> - 2.3.0: raise the warning to an error ### Deprecate `kotlin.io.createTempDirectory()` and `kotlin.io.createTempFile()` functions From fa6eafc372bb5d21d7558fad6c7cda159f256ba6 Mon Sep 17 00:00:00 2001 From: Sarah Haggarty Date: Thu, 13 Nov 2025 17:38:33 +0100 Subject: [PATCH 08/11] Mikhail review --- .../compatibility-guide-23.md | 33 ++++++++++--------- 1 file changed, 17 insertions(+), 16 deletions(-) diff --git a/docs/topics/compatibility-guides/compatibility-guide-23.md b/docs/topics/compatibility-guides/compatibility-guide-23.md index 17d9276bfe6..27d34518049 100644 --- a/docs/topics/compatibility-guides/compatibility-guide-23.md +++ b/docs/topics/compatibility-guides/compatibility-guide-23.md @@ -39,16 +39,16 @@ perspective (for example, from Java) is out of the scope of this document. > - 2.2.0: report a warning when using `-language-version` with versions 1.8 and 1.9. > - 2.3.0: raise the warning to an error for language version 1.8 on all platforms and for language version 1.9 on non-JVM platforms. -### Handle `UPPER_BOUND_VIOLATED` on implicit type arguments +### Report upper-bound constraint violation errors for inferred types with typealiases > **Issue**: [KTLC-287](https://youtrack.jetbrains.com/issue/KTLC-287) > > **Component**: Core language > -> **Incompatible change type**: behavioral +> **Incompatible change type**: source > -> **Short summary**: Previously, the compiler never reported `UPPER_BOUND_VIOLATED` for implicit type parameters. This -> has been fixed in Kotlin 2.3.0 so that `UPPER_BOUND_VIOLATED` is reported consistently across all type parameters. +> **Short summary**: Previously, the compiler never reported errors about upper-bound violation constraints for the inferred types. This +> has been fixed in Kotlin 2.3.0 so that the error is reported consistently across all type parameters. > > **Deprecation cycle**: > @@ -61,7 +61,7 @@ perspective (for example, from Java) is out of the scope of this document. > > **Component**: Core language > -> **Incompatible change type**: behavioral +> **Incompatible change type**: source > > **Short summary**: Prohibit adding the `@JvmSerializableLambda` annotation on `inline` and `crossinline` lambdas > because it has no effect. `inline` and `crossinline` lambdas are not serializable. @@ -77,7 +77,7 @@ perspective (for example, from Java) is out of the scope of this document. > > **Component**: Core language > -> **Incompatible change type**: behavioral +> **Incompatible change type**: source > > **Short summary**: Kotlin 2.3.0 forbids delegation to a Java class that implements a generic interface method with > a non-generic override. Previously, allowing this behavior led to type mismatches and `ClassCastException` reported at runtime. @@ -94,7 +94,7 @@ perspective (for example, from Java) is out of the scope of this document. > > **Component**: Core language > -> **Incompatible change type**: behavioral +> **Incompatible change type**: source > > **Short summary**: Kotlin now deprecates using `return` inside expression bodies when the function's return type is not > explicitly declared. @@ -110,7 +110,7 @@ perspective (for example, from Java) is out of the scope of this document. > > **Component**: Core language > -> **Incompatible change type**: behavioral +> **Incompatible change type**: source > > **Short summary**: Kotlin now reports an error when attempting to inherit from a nullable typealias, consistent with > how it already handles direct nullable supertypes. @@ -124,7 +124,7 @@ perspective (for example, from Java) is out of the scope of this document. > **Issue**: [KTLC-277](https://youtrack.jetbrains.com/issue/KTLC-277) > -> **Component**: Core language +> **Component**: Reflection > > **Incompatible change type**: behavioral > @@ -141,7 +141,7 @@ perspective (for example, from Java) is out of the scope of this document. > > **Component**: Core language > -> **Incompatible change type**: behavioral +> **Incompatible change type**: source > > **Short summary**: Kotlin 2.3 prohibits situations where a reified type parameter is inferred to an intersection type, > due to the risk of incorrect runtime behavior. @@ -157,7 +157,7 @@ perspective (for example, from Java) is out of the scope of this document. > > **Component**: Core language > -> **Incompatible change type**: behavioral +> **Incompatible change type**: source > > **Short summary**: Kotlin 2.3 forbids using type parameter bounds that expose types with more restrictive visibility > than the function or declaration itself, aligning the rules for functions with those already applied to classes. @@ -167,15 +167,17 @@ perspective (for example, from Java) is out of the scope of this document. > - 2.1.0: report a warning on the problematic type parameter bound > - 2.3.0: raise the warning to an error +## Standard library + ### Deprecate misleading Char-to-number conversions and introduce explicit digit and code APIs > **Issue**: [KTLC-321](https://youtrack.jetbrains.com/issue/KTLC-321) > -> **Component**: Core language +> **Component**: kotlin-stdlib > -> **Incompatible change type**: behavioral +> **Incompatible change type**: source > -> **Short summary**: Kotlin 2.3 deprecates `Char.toX()` and `X.toChar()` conversions for numeric types and introduces new, +> **Short summary**: Kotlin 2.3 deprecates `Char.toX()` and `X.toChar()` conversions for numeric types and introduces new, > explicit APIs for accessing a character's code and digit value. > > **Deprecation cycle**: @@ -184,7 +186,6 @@ perspective (for example, from Java) is out of the scope of this document. > - 1.5.0: promote the new functions to Stable; report warnings for old functions with suggestions for replacements > - 2.3.0: raise the warnings to errors -## Standard library ### Deprecate `String.subSequence(start, end)` function @@ -254,7 +255,7 @@ perspective (for example, from Java) is out of the scope of this document. > > **Component**: Kotlin/Native > -> **Incompatible change type**: behavior +> **Incompatible change type**: behavioral > > **Short summary**: When formatting an exception stacktrace, no additional causes are printed once a previously seen exception cause has already been printed. > From 360e5fcb37d34141fbe8006249ee759cf9a21932 Mon Sep 17 00:00:00 2001 From: Sarah Haggarty Date: Mon, 17 Nov 2025 11:27:20 +0100 Subject: [PATCH 09/11] rearrange for Filipp --- .../compatibility-guide-23.md | 27 +++++++++---------- 1 file changed, 13 insertions(+), 14 deletions(-) diff --git a/docs/topics/compatibility-guides/compatibility-guide-23.md b/docs/topics/compatibility-guides/compatibility-guide-23.md index 27d34518049..b7b195c325b 100644 --- a/docs/topics/compatibility-guides/compatibility-guide-23.md +++ b/docs/topics/compatibility-guides/compatibility-guide-23.md @@ -186,51 +186,50 @@ perspective (for example, from Java) is out of the scope of this document. > - 1.5.0: promote the new functions to Stable; report warnings for old functions with suggestions for replacements > - 2.3.0: raise the warnings to errors +### Deprecate `Number.toChar()` function -### Deprecate `String.subSequence(start, end)` function - -> **Issue**: [KTLC-282](https://youtrack.jetbrains.com/issue/KTLC-282) +> **Issue**: [KT-56822](https://youtrack.jetbrains.com/issue/KT-56822) > > **Component**: kotlin-stdlib > > **Incompatible change type**: source > -> **Short summary**: The `String.subSequence(start, end)` function is deprecated. Use the [`String.subSequence(startIndex, endIndex)`](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/sub-sequence.html) function instead. +> **Short summary**: The `Number.toChar()` function is deprecated. Use `toInt().toChar()` or the `Char` constructor instead. > > **Deprecation cycle**: > -> - 1.0: report a warning when using `String.subSequence(start, end)` +> - 1.9.0: report a warning when using the `Number.toChar()` function > - 2.3.0: raise the warning to an error -### Deprecate `kotlin.io.createTempDirectory()` and `kotlin.io.createTempFile()` functions +### Deprecate `String.subSequence(start, end)` function -> **Issue**: [KTLC-281](https://youtrack.jetbrains.com/issue/KTLC-281) +> **Issue**: [KTLC-282](https://youtrack.jetbrains.com/issue/KTLC-282) > > **Component**: kotlin-stdlib > > **Incompatible change type**: source > -> **Short summary**: The `kotlin.io.createTempDirectory()` and `kotlin.io.createTempFile()` functions are deprecated. -> Use the [`kotlin.io.path.createTempDirectory()`](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.io.path/create-temp-directory.html) and [`kotlin.io.path.createTempFile()`](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.io.path/create-temp-file.html) functions instead. +> **Short summary**: The `String.subSequence(start, end)` function is deprecated. Use the [`String.subSequence(startIndex, endIndex)`](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/sub-sequence.html) function instead. > > **Deprecation cycle**: > -> - 1.4.20: report a warning when using `kotlin.io.createTempDirectory()` and `kotlin.io.createTempFile()` functions +> - 1.0: report a warning when using `String.subSequence(start, end)` > - 2.3.0: raise the warning to an error -### Deprecate `Number.toChar()` function +### Deprecate `kotlin.io.createTempDirectory()` and `kotlin.io.createTempFile()` functions -> **Issue**: [KT-56822](https://youtrack.jetbrains.com/issue/KT-56822) +> **Issue**: [KTLC-281](https://youtrack.jetbrains.com/issue/KTLC-281) > > **Component**: kotlin-stdlib > > **Incompatible change type**: source > -> **Short summary**: The `Number.toChar()` function is deprecated. Use `toInt().toChar()` or the `Char` constructor instead. +> **Short summary**: The `kotlin.io.createTempDirectory()` and `kotlin.io.createTempFile()` functions are deprecated. +> Use the [`kotlin.io.path.createTempDirectory()`](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.io.path/create-temp-directory.html) and [`kotlin.io.path.createTempFile()`](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.io.path/create-temp-file.html) functions instead. > > **Deprecation cycle**: > -> - 1.9.0: report a warning when using the `Number.toChar()` function +> - 1.4.20: report a warning when using `kotlin.io.createTempDirectory()` and `kotlin.io.createTempFile()` functions > - 2.3.0: raise the warning to an error ### Hide `InputStream.readBytes(Int)` function From d3b7954d2215689ea7b1732e5bc6272adb52a9e9 Mon Sep 17 00:00:00 2001 From: Sarah Haggarty Date: Wed, 19 Nov 2025 17:42:18 +0100 Subject: [PATCH 10/11] kotlin-dsl and kotlin("jvm") plugin conflict --- .../compatibility-guide-23.md | 33 +++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/docs/topics/compatibility-guides/compatibility-guide-23.md b/docs/topics/compatibility-guides/compatibility-guide-23.md index b7b195c325b..69dbae3bee7 100644 --- a/docs/topics/compatibility-guides/compatibility-guide-23.md +++ b/docs/topics/compatibility-guides/compatibility-guide-23.md @@ -280,6 +280,39 @@ perspective (for example, from Java) is out of the scope of this document. ## Tools +### Unsupported KGP version warning when using `kotlin-dsl` and `kotlin("jvm")` plugins + +> **Issue**: [KT-79851](https://youtrack.jetbrains.com/issue/KT-79851) +> +> **Component**: Gradle +> +> **Incompatible change type**: behavioral +> +> **Short summary**: In Kotlin 2.3, if you use both the `kotlin-dsl` **and** the `kotlin("jvm")` plugin in your Gradle +> project, you may see a Gradle warning about an unsupported Kotlin Gradle plugin (KGP) version. +> +> **Deprecation cycle**: +> +> - 2.3.0: introduce a diagnostic that detects when the `kotlin-dsl` plugin is used with an incompatible language or API version of the compiler. +> +> **Migration steps**: +> +> In general, we don't recommend using both the `kotlin-dsl` and the `kotlin("jvm")` plugins in the same Gradle project. This setup isn't supported. +> +> For convention plugins, precompiled script plugins or any other form of unpublished build logic, you have three options: +> +> 1. Don't apply the `kotlin("jvm")` plugin explicitly. Instead, let the `kotlin-dsl` plugin automatically provide a compatible KGP version. +> 2. If you want to apply the `kotlin("jvm")` plugin explicitly, use the `embeddedKotlinVersion` constant to specify the embedded Kotlin version. +> +> To upgrade the embedded Kotlin and language versions, update your Gradle version. You can find compatible Gradle versions in Gradle's [Compatibility Notes for Kotlin](https://docs.gradle.org/current/userguide/compatibility.html#kotlin). +> +> 3. Don't use the `kotlin-dsl` plugin. This may be more appropriate for binary plugins that aren't tied to a specific Gradle version. +> +> As a last resort, you can configure your project to use language version 2.1 or higher, which overrides the conflicting behavior of the `kotlin-dsl` plugin. However, we strongly recommend not doing so. +> +> If you experience difficulties during migration, reach out in the #gradle channel in our [Slack](https://surveys.jetbrains.com/s3/kotlin-slack-sign-up) for support. + + ### Correct `setSource()` function in `KotlinCompileTool` to replace sources > **Issue**: [KT-59632](https://youtrack.jetbrains.com/issue/KT-59632) From 98623e8f2e5bdd2ebb9876f7dfce66a68eb27c1c Mon Sep 17 00:00:00 2001 From: Danil Pavlov Date: Mon, 24 Nov 2025 18:33:15 +0100 Subject: [PATCH 11/11] update: available language and API versions --- docs/topics/gradle/gradle-compiler-options.md | 16 +++++++------- docs/topics/maven.md | 22 +++++++++---------- 2 files changed, 19 insertions(+), 19 deletions(-) diff --git a/docs/topics/gradle/gradle-compiler-options.md b/docs/topics/gradle/gradle-compiler-options.md index ee04897e02c..d281687b7f1 100644 --- a/docs/topics/gradle/gradle-compiler-options.md +++ b/docs/topics/gradle/gradle-compiler-options.md @@ -591,14 +591,14 @@ Here is a complete list of options for the Gradle compiler: ### Attributes common to JVM and JavaScript -| Name | Description | Possible values |Default value | -|------|-------------|----------------------------------------------------------------|--------------| -| `allWarningsAsErrors` | Report an error if there are any warnings | | false | -| `suppressWarnings` | Don't generate warnings | | false | -| `verbose` | Enable verbose logging output. Works only when the [Gradle debug log level enabled](https://docs.gradle.org/current/userguide/logging.html) | | false | -| `freeCompilerArgs` | A list of additional compiler arguments. You can use experimental `-X` arguments here too. See an [example](#example-of-additional-arguments-usage-via-freecompilerargs) | | [] | -| `apiVersion` | Restrict the use of declarations to those from the specified version of bundled libraries | "1.8", "1.9", "2.0", "2.1", "2.2" (EXPERIMENTAL) | | -| `languageVersion` | Provide source compatibility with the specified version of Kotlin | "1.8", "1.9", "2.0", "2.1", "2.2" (EXPERIMENTAL) | | +| Name | Description | Possible values | Default value | +|-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------|---------------| +| `allWarningsAsErrors` | Report an error if there are any warnings | | false | +| `suppressWarnings` | Don't generate warnings | | false | +| `verbose` | Enable verbose logging output. Works only when the [Gradle debug log level enabled](https://docs.gradle.org/current/userguide/logging.html) | | false | +| `freeCompilerArgs` | A list of additional compiler arguments. You can use experimental `-X` arguments here too. See an [example](#example-of-additional-arguments-usage-via-freecompilerargs) | | [] | +| `apiVersion` | Restrict the use of declarations to those from the specified version of bundled libraries | "1.9", "2.0", "2.1", "2.2", "2.3", "2.4" (EXPERIMENTAL) | | +| `languageVersion` | Provide source compatibility with the specified version of Kotlin | "1.9", "2.0", "2.1", "2.2", "2.3", "2.4" (EXPERIMENTAL) | | > We are going to deprecate the attribute `freeCompilerArgs` in future releases. If you miss some option in the Kotlin Gradle DSL, > please, [file an issue](https://youtrack.jetbrains.com/newissue?project=kt). diff --git a/docs/topics/maven.md b/docs/topics/maven.md index 494b1ef049f..b8ef4f39fd0 100644 --- a/docs/topics/maven.md +++ b/docs/topics/maven.md @@ -342,17 +342,17 @@ The following attributes are supported: ### Attributes specific to JVM -| Name | Property name | Description | Possible values | Default value | -|-------------------|---------------------------------|------------------------------------------------------------------------------------------------------|--------------------------------------------------|-----------------------------| -| `nowarn` | | Generate no warnings | true, false | false | -| `languageVersion` | kotlin.compiler.languageVersion | Provide source compatibility with the specified version of Kotlin | "1.8", "1.9", "2.0", "2.1", "2.2" (EXPERIMENTAL) | | -| `apiVersion` | kotlin.compiler.apiVersion | Allow using declarations only from the specified version of bundled libraries | "1.8", "1.9", "2.0", "2.1", "2.2" (EXPERIMENTAL) | | -| `sourceDirs` | | The directories containing the source files to compile | | The project source roots | -| `compilerPlugins` | | Enabled compiler plugins | | [] | -| `pluginOptions` | | Options for compiler plugins | | [] | -| `args` | | Additional compiler arguments | | [] | -| `jvmTarget` | `kotlin.compiler.jvmTarget` | Target version of the generated JVM bytecode | "1.8", "9", "10", ..., "24" | "%defaultJvmTargetVersion%" | -| `jdkHome` | `kotlin.compiler.jdkHome` | Include a custom JDK from the specified location into the classpath instead of the default JAVA_HOME | | | +| Name | Property name | Description | Possible values | Default value | +|-------------------|---------------------------------|------------------------------------------------------------------------------------------------------|---------------------------------------------------------|-----------------------------| +| `nowarn` | | Generate no warnings | true, false | false | +| `languageVersion` | kotlin.compiler.languageVersion | Provide source compatibility with the specified version of Kotlin | "1.9", "2.0", "2.1", "2.2", "2.3", "2.4" (EXPERIMENTAL) | | +| `apiVersion` | kotlin.compiler.apiVersion | Allow using declarations only from the specified version of bundled libraries | "1.9", "2.0", "2.1", "2.2", "2.3", "2.4" (EXPERIMENTAL) | | +| `sourceDirs` | | The directories containing the source files to compile | | The project source roots | +| `compilerPlugins` | | Enabled compiler plugins | | [] | +| `pluginOptions` | | Options for compiler plugins | | [] | +| `args` | | Additional compiler arguments | | [] | +| `jvmTarget` | `kotlin.compiler.jvmTarget` | Target version of the generated JVM bytecode | "1.8", "9", "10", ..., "24" | "%defaultJvmTargetVersion%" | +| `jdkHome` | `kotlin.compiler.jdkHome` | Include a custom JDK from the specified location into the classpath instead of the default JAVA_HOME | | | ## Use BOM