Start using `@IntroducedAt()`
- Dominant language
- Kotlin
- Stars
- 1.1k
- Forks
- 83
- Avg merge
- 4d 12h
- Merged PRs (30d)
- 30
Description
Background:
https://youtrack.jetbrains.com/issue/KT-80852
https://github.com/Kotlin/KEEP/blob/main/proposals/KEEP-0431-version-overloading.md
In the library we have many deprecations like:
```kt
@Deprecated(
message = "This function exists for binary compatibility",
level = DeprecationLevel.HIDDEN,
)
```
Since Kotlin 2.4.0, we can use (Experimental) Version Overloading to generate these hidden overloads for us in a cleaner and more maintainable way.
We've accumulated quite a few places where this would be useful.
For instance, in #1869, we introduced a new parameter to the `DataFrame.readJson(inputStream, ...)` function like this:
```kt
public fun DataFrame.Companion.readJson(
stream: InputStream,
header: List = emptyList(),
keyValuePaths: List = emptyList(),
typeClashTactic: TypeClashTactic = ARRAY_AND_VALUE_COLUMNS,
unifyNumbers: Boolean = true,
format: Json = Json.Default,
): AnyFrame = ...
@Deprecated(
message = "This function exists for binary compatibility",
level = DeprecationLevel.HIDDEN,
)
public fun DataFrame.Companion.readJson(
stream: InputStream,
header: List = emptyList(),
keyValuePaths: List = emptyList(),
typeClashTactic: TypeClashTactic = ARRAY_AND_VALUE_COLUMNS,
unifyNumbers: Boolean = true,
): AnyFrame =
DataFrame.readJson(
stream = stream,
header = header,
keyValuePaths = keyValuePaths,
typeClashTactic = typeClashTactic,
unifyNumbers = unifyNumbers,
format = Json.Default,
)
```
Though, with the new annotation, we can simply write this and achieve exactly the same result:
```kt
@OptIn(ExperimentalVersionOverloading::class)
public fun DataFrame.Companion.readJson(
stream: InputStream,
header: List = emptyList(),
keyValuePaths: List = emptyList(),
typeClashTactic: TypeClashTactic = ARRAY_AND_VALUE_COLUMNS,
unifyNumbers: Boolean = true,
@IntroducedAt("1.0.0-Beta6") format: Json = Json.Default,
): AnyFrame = ...
```
Since it generates the overloads in bytecode, users will have to change nothing to use it. And since we already wrote the overloads as Deprecated HIDDEN, changing to this annotation won't break bytecode compatibilty.
Contributor guide
Research direction
Start by reviewing the linked KEEP proposal and the library's existing Deprecated(..., level = DeprecationLevel.HIDDEN) patterns, including the readJson example described here. Identify applicable compatibility overloads and verify that replacing them preserves binary compatibility and existing user behavior.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- kotlin
- Domain
- api
- Issue type
- Refactor
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 52/100