Compatibility guide for Kotlin 2.1.0 #4540
There are no files selected for viewing
This file contains 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
This file contains 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,186 @@ | ||||||
| [//]: # (title: Compatibility guide for Kotlin 2.1) | ||||||
|
|
||||||
| _[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 | ||||||
|
There was a problem hiding this comment. I see this part is fixed from previous guide versions, but, to make it more conversational and closer to users, could we change "The former and the latter", for: "The first principle states that constructs which obstruct language evolution should be removed, while the second principle emphasizes that such removal should be well-communicated..." or something like this? |
||||||
| 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 | ||||||
|
There was a problem hiding this comment. Should we bold the terms? For consistency with this type of list in our docs. |
||||||
| 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 | ||||||
|
|
||||||
| <!-- | ||||||
| ### Title | ||||||
|
|
||||||
| > **Issue**: [KT-NNNNN](https://youtrack.jetbrains.com/issue/KT-NNNNN) | ||||||
| > | ||||||
| > **Component**: Core language | ||||||
| > | ||||||
| > **Incompatible change type**: source | ||||||
| > | ||||||
| > **Short summary**: | ||||||
| > | ||||||
| > **Deprecation cycle**: | ||||||
| > | ||||||
| > - 2.1.0: report a warning | ||||||
daniCsorbaJB marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
| > - 2.2.0: raise the warning to an error | ||||||
| --> | ||||||
|
|
||||||
| ### Change data class copy() function visibility to match private constructor | ||||||
daniCsorbaJB marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
|
|
||||||
| > **Issue**: [KT-11914](https://youtrack.jetbrains.com/issue/KT-11914) | ||||||
| > | ||||||
| > **Component**: Core language | ||||||
daniCsorbaJB marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
| > | ||||||
| > **Incompatible change type**: source | ||||||
| > | ||||||
| > **Deprecation cycle**: | ||||||
| > | ||||||
| > - 2.0.20: report a warning for visibility mismatches; apply `@ConsistentCopyVisibility` or use the `-Xconsistent-data-class-copy-visibility` flag to adopt the new behavior early, or use the `@ExposedCopyVisibility` annotation to retain the old behavior | ||||||
| > - 2.2.0: raise the warning to an error for incompatible `copy()` usages | ||||||
| > - 2.3.0: the `copy()` function defaults to the visibility of the primary constructor | ||||||
|
|
||||||
|
|
||||||
| ## Tools | ||||||
|
|
||||||
| ### Deprecate KotlinCompilationOutput#resourcesDirProvider | ||||||
|
|
||||||
| > **Issue**: [KT-69255](https://youtrack.jetbrains.com/issue/KT-69255) | ||||||
| > | ||||||
| > **Component**: Gradle | ||||||
| > | ||||||
| > **Incompatible change type**: source | ||||||
| > | ||||||
| > **Short summary**: The `KotlinCompilationOutput#resourcesDirProvider` field is deprecated. | ||||||
daniCsorbaJB marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
| > Use `KotlinSourceSet.resources` to add additional resource directories instead. | ||||||
| > | ||||||
| > **Deprecation cycle**: | ||||||
| > | ||||||
| > - 2.1.0: `KotlinCompilationOutput#resourcesDirProvider` is deprecated | ||||||
|
|
||||||
| ### Deprecate registerKotlinJvmCompileTask(taskName, moduleName) function | ||||||
|
|
||||||
| > **Issue**: [KT-69927](https://youtrack.jetbrains.com/issue/KT-69927) | ||||||
| > | ||||||
| > **Component**: Gradle | ||||||
| > | ||||||
| > **Incompatible change type**: source | ||||||
| > | ||||||
| > **Short summary**: The `registerKotlinJvmCompileTask(taskName, moduleName)` function is deprecated | ||||||
| > in favor of the new `registerKotlinJvmCompileTask(taskName, compilerOptions, explicitApiMode)` function, which now accepts `KotlinJvmCompilerOptions`. | ||||||
| > This allows you to set compiler options directly when creating a new JVM compilation task. | ||||||
Tapchicoma marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
| > | ||||||
| > **Deprecation cycle**: | ||||||
| > | ||||||
| > - 2.1.0: the `registerKotlinJvmCompileTask(taskName, moduleName)` function is deprecated | ||||||
|
|
||||||
| ### Deprecate registerKaptGenerateStubsTask(taskName) function | ||||||
|
|
||||||
| > **Issue**: [KT-70383](https://youtrack.jetbrains.com/issue/KT-70383) | ||||||
| > | ||||||
| > **Component**: Gradle | ||||||
| > | ||||||
| > **Incompatible change type**: source | ||||||
| > | ||||||
| > **Short summary**: The `registerKaptGenerateStubsTask(taskName)` function is deprecated. | ||||||
| > Use the new `registerKaptGenerateStubsTask(compileTask, kaptExtension, explicitApiMode)` function instead. | ||||||
| > This new version allows `KotlinJvmCompile` tasks to be directly connected to `KaptGenerateStubsTask`, making it possible to apply `KotlinJvmCompilerOptions` directly within the task. | ||||||
Tapchicoma marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
| > | ||||||
| > **Deprecation cycle**: | ||||||
| > | ||||||
| > - 2.1.0: the `registerKaptGenerateStubsTask(taskName)` function is deprecated | ||||||
|
|
||||||
| ### Deprecate KotlinTopLevelExtension and KotlinTopLevelExtensionConfig interfaces | ||||||
|
|
||||||
| > **Issue**: [KT-71602](https://youtrack.jetbrains.com/issue/KT-71602) | ||||||
| > | ||||||
| > **Component**: Gradle | ||||||
| > | ||||||
| > **Incompatible change type**: behavioral | ||||||
| > | ||||||
| > **Short summary**: `KotlinTopLevelExtension` and `KotlinTopLevelExtensionConfig` interfaces are deprecated in favor of a new `KotlinTopLevelExtension` interface. | ||||||
| > This interface merges `KotlinTopLevelExtensionConfig`, `KotlinTopLevelExtension`, and `KotlinProjectExtension` | ||||||
| > to provide a clearer API hierarchy, and official access to JVM toolchain and compiler properties. | ||||||
daniCsorbaJB marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
| > | ||||||
| > **Deprecation cycle**: | ||||||
| > | ||||||
| > - 2.1.0: the `KotlinTopLevelExtension` and `KotlinTopLevelExtensionConfig` interfaces are deprecated | ||||||
|
|
||||||
| ### Remove kotlin-compiler-embeddable from build runtime dependencies | ||||||
|
|
||||||
| > **Issue**: [KT-61706](https://youtrack.jetbrains.com/issue/KT-61706) | ||||||
| > | ||||||
| > **Component**: Gradle | ||||||
| > | ||||||
| > **Incompatible change type**: source | ||||||
| > | ||||||
| > **Short summary**: The `kotlin-compiler-embeddable` dependency is removed from the runtime in Kotlin Gradle Plugin (KGP). | ||||||
| > Required modules are now included directly in KGP artifacts, with a version limit of 2.0 to support compatibility with Gradle versions below 8.2. | ||||||
Tapchicoma marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
| > | ||||||
| > **Deprecation cycle**: | ||||||
| > | ||||||
| > - 2.1.0: report a warning on using `kotlin-compiler-embeddable` | ||||||
| > - 2.2.0: raise the warning to an error | ||||||
|
|
||||||
| ### Hide compiler symbols from the Kotlin Gradle Plugin API | ||||||
|
|
||||||
| > **Issue**: [KT-70251](https://youtrack.jetbrains.com/issue/KT-70251) | ||||||
| > | ||||||
| > **Component**: Gradle | ||||||
| > | ||||||
| > **Incompatible change type**: source | ||||||
| > | ||||||
| > **Short summary**: Compiler module symbols bundled within the Kotlin Gradle Plugin (KGP), such as `KotlinCompilerVersion`, | ||||||
| > are hidden from the public API to prevent unintended access in build scripts. | ||||||
| > | ||||||
| > **Deprecation cycle**: | ||||||
| > | ||||||
| > - 2.1.0: report a warning on accessing these symbols | ||||||
| > - 2.2.0: raise the warning to an error | ||||||
|
|
||||||
| ### Support for multiple stability configuration files | ||||||
daniCsorbaJB marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
|
|
||||||
| > **Issue**: [KT-68345](https://youtrack.jetbrains.com/issue/KT-68345) | ||||||
| > | ||||||
| > **Component**: Gradle | ||||||
| > | ||||||
| > **Incompatible change type**: source | ||||||
| > | ||||||
| > **Short summary**: The `stabilityConfigurationFile` property in the Compose compiler options is deprecated | ||||||
Tapchicoma marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
| > in favor of a new `stabilityConfigurationFiles` property, which allows specifying multiple configuration files. | ||||||
| > | ||||||
| > **Deprecation cycle**: | ||||||
| > | ||||||
| > - 2.1.0: `stabilityConfigurationFile` property is deprecated | ||||||
|
|
||||||
| ### Remove deprecated platform plugin IDs | ||||||
|
|
||||||
| > **Issue**: [KT-65565](https://youtrack.jetbrains.com/issue/KT-65565) | ||||||
| > | ||||||
| > **Component**: Gradle | ||||||
| > | ||||||
| > **Incompatible change type**: source | ||||||
| > | ||||||
| > **Short summary**: support for these platform plugin IDs have been removed: | ||||||
|
There was a problem hiding this comment.
Suggested change
|
||||||
| > * `kotlin-platform-common` | ||||||
| > * `org.jetbrains.kotlin.platform.common` | ||||||
| > | ||||||
| > **Deprecation cycle**: | ||||||
| > | ||||||
| > - 1.3: the platform plugin IDs are deprecated | ||||||
| > - 2.1.0: the platform plugin IDs are no longer supported | ||||||
Oops, something went wrong.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
A related question: would it be possible to link the compatibility guide from the What's new page? (as we did in 1.9 and before)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Hi Ilya - I asked the team - we'll link to it! 👍