Kotlin / Kotlin/dataframe

Start using `@IntroducedAt()`

Open
#1,884 0 comments 0 reactions 0 assignees View on GitHub
API enhancement infrastructure
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.