-
Notifications
You must be signed in to change notification settings - Fork 4.3k
Compatibility guide for Kotlin 2.3.0 #5171
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Draft
sarahhaggarty
wants to merge
11
commits into
master
Choose a base branch
from
2-3-0-compat-guide
base: master
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Draft
Changes from 7 commits
Commits
Show all changes
11 commits
Select commit
Hold shift + click to select a range
651cd6d
feat: add compatibility guide 2.3
sarahhaggarty e6a2f13
standard library tickets
sarahhaggarty 75d47a3
language version
sarahhaggarty a5de69f
update: adding info for KTLC-268/ KT-71822
daniCsorbaJB 85020dd
language tickets
sarahhaggarty dc84350
rebase on master
sarahhaggarty eeeec87
Filipp review
sarahhaggarty fa6eafc
Mikhail review
sarahhaggarty 360e5fc
rearrange for Filipp
sarahhaggarty d3b7954
kotlin-dsl and kotlin("jvm") plugin conflict
sarahhaggarty 98623e8
update: available language and API versions
danil-pavlov File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
296 changes: 296 additions & 0 deletions
296
docs/topics/compatibility-guides/compatibility-guide-23.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,296 @@ | ||
| [//]: # (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 | ||
|
|
||
| ### 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**: Compiler | ||
| > | ||
| > **Incompatible change type**: source | ||
| > | ||
| > **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 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 | ||
|
|
||
| > **Issue**: [KTLC-287](https://youtrack.jetbrains.com/issue/KTLC-287) | ||
| > | ||
| > **Component**: Core language | ||
| > | ||
| > **Incompatible change type**: behavioral | ||
sarahhaggarty marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
| > | ||
| > **Short summary**: Previously, the compiler never reported `UPPER_BOUND_VIOLATED` for implicit type parameters. This | ||
sarahhaggarty marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
| > has been fixed in Kotlin 2.3.0 so that `UPPER_BOUND_VIOLATED` is reported consistently across all type parameters. | ||
sarahhaggarty marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
| > | ||
| > **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 | ||
sarahhaggarty marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
| > | ||
| > **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 | ||
sarahhaggarty marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
| > | ||
| > **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 | ||
sarahhaggarty marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
| > | ||
| > **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 | ||
sarahhaggarty marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
| > | ||
| > **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 | ||
sarahhaggarty marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
| > | ||
| > **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 | ||
sarahhaggarty marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
| > | ||
| > **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 | ||
sarahhaggarty marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
| > | ||
| > **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 | ||
sarahhaggarty marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| > **Issue**: [KTLC-321](https://youtrack.jetbrains.com/issue/KTLC-321) | ||
| > | ||
| > **Component**: Core language | ||
sarahhaggarty marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
| > | ||
| > **Incompatible change type**: behavioral | ||
sarahhaggarty marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
| > | ||
| > **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**: | ||
| > | ||
| > - 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**: [KTLC-282](https://youtrack.jetbrains.com/issue/KTLC-282) | ||
| > | ||
| > **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**: | ||
| > | ||
sarahhaggarty marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| > - 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 | ||
|
|
||
| > **Issue**: [KTLC-281](https://youtrack.jetbrains.com/issue/KTLC-281) | ||
| > | ||
| > **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**: [KTLC-280](https://youtrack.jetbrains.com/issue/KTLC-280) | ||
| > | ||
| > **Component**: kotlin-stdlib | ||
| > | ||
| > **Incompatible change type**: source | ||
| > | ||
| > **Short summary**: After being deprecated for a long time, the `InputStream.readBytes(estimatedSize: Int = DEFAULT_BUFFER_SIZE): ByteArray` function is hidden. | ||
| > | ||
| > **Deprecation cycle**: | ||
| > | ||
| > - 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 | ||
|
|
||
| > **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 | ||
|
|
||
| ### Correct `Iterable<T>.intersect()` and `Iterable<T>.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<T>.intersect()`](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/intersect.html) and [`Iterable<T>.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 | ||
|
|
||
| > **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 | ||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.