:mega: `kotlinx-datetime` 0.7.0 is here! - `Insta...

# kotlinx-datetime

[Dmitry Khalanskiy [JB]]

📣 kotlinx-datetime 0.7.0 is here!
• Instant and Clock were moved to the standard library and are no longer part of kotlinx-datetime. Please follow https://github.com/Kotlin/kotlinx-datetime?tab=readme-ov-file#deprecation-of-instant if you encounter problems because of that.
• LocalDateRange, a range of date values, was added.
• YearMonth and YearMonthRange were added.
• Serializers that can be parameterized with a DateTimeFormat were added.
• Most entities in the library are java.io.Serializable now.
• Other changes. The full changelog is available here: https://github.com/Kotlin/kotlinx-datetime/releases/tag/v0.7.0

[florent]

looks like @Serializable(with = InstantIso8601Serializer::class) is missing on kotlin 2.2.0 instant version?

[florent]

nevermind, it is waiting for https://github.com/Kotlin/kotlinx.serialization/pull/2945/files to be merged

[Jeff Lockhart]

Reading Deprecation of Instant, it's not clear what the guidance would be for library authors that have kotlinx-datetime as a dependency and use kotlinx.datetime.Instant in their API. Will migrating to kotlin.time.Instant be a binary compatible change? Will it require users to be using at least Kotlin 2.1.20? Can you elaborate on a proper migration path for libraries?

[Dmitry Khalanskiy [JB]]

Will migrating to kotlin.time.Instant be a binary compatible change?

It will not.

Will it require users to be using at least Kotlin 2.1.20?

Yes, users have to be using at least Kotlin 2.1.20 to access kotlin.time.Instant.

the guidance would be for library authors that have kotlinx-datetime as a dependency and use kotlinx.datetime.Instant in their API

This depends on your goals.

If you want to obey the social contracts established between libraries in the JVM world, you are already free to simply replace kotlinx.datetime.Instant with kotlin.time.Instant, breaking binary compatibility in the process. After all, kotlinx-datetime is itself fully experimental, not even at the beta stage, any usages of it are subject to breakage, so even we had the right to just remove kotlinx.datetime.Instant. We went the extra mile to mitigate the potential problems this could cause, but doing this right is tricky, we don't expect other library authors to do the same.

If your library is used by many other libraries in turn and you are also willing to put in quite a bit of extra effort to simplify life for them, you'll need to replicate what we have done: have two separate versions of your library, one using kotlin.time.Instant, the other one still depending on kotlinx.datetime.Instant (possibly from the compatibility artifact).

If you are interested in going down the far more difficult road, please let me know, and I'll formulate a guidance. It would be based on the procedure we described in the KEEP for removing `Instant`: https://github.com/dkhalanskyjb/KEEP/blob/982d2f611c8721477f861c4940647184c313c577/proposals/stdlib/instant.md#description-of-the-process The KEEP itself may be enough to get started.

[Jeff Lockhart]

Thanks for those details. I think in my case I will wait to upgrade kotlinx-datetime to 0.7.0 and migrate to kotlin.time.Instant in the next version release, along with other API additions and changes in the library, introducing the requirement to use Kotlin 2.1.20+.

[Joel Denke]

Is it possible serialize Kotlin Instant with kotlinx serialization in latest Kotlin 2.2.0? Or do I need add custom serializer?

[Dmitry Khalanskiy [JB]]

https://github.com/Kotlin/kotlinx.serialization/pull/2945 is the pull request adding kotlin.time.Instant support to kotlinx.serialization. A kotlinx.serialization release that includes these changes is not yet published.

[Joel Denke]

Wow yeah massive chain of things need to align like Kotlin, ksp, kotlinx stuff and now also AGP bricked. A well waiting a couple of months until bumping I think.
Or is this release close in time?

[Dmitry Khalanskiy [JB]]

@sandwwraith, do we have plans to release kotlinx.serialization with the kotlin.time.Instant PR sometime soon?

[sandwwraith]

I did not, because I was not aware of the plans of dropping your serializers entirely, and I did not now that releases should have been aligned. Given that the issue is important, I'll try to publish next version soon.

[Dmitry Khalanskiy [JB]]

The serializers for kotlinx.datetime.Instant are still present in the compatibility artifact, but we didn't introduce the kotlin.time.Instant serializers to kotlinx-datetime (mostly because we couldn't mark kotlin.time.Instant as Serializable from inside kotlinx-datetime, only kotlinx.serialization can do that).

[Nikky]

so for now to stop my project from exploding i have to use smth like..

object InstantSerializer : FormattedInstantSerializer(
    "ISO", DateTimeComponents.Formats.ISO_DATE_TIME_OFFSET
)

to keep serialization the same as before ?

[Dmitry Khalanskiy [JB]]

@Nikky, this would work, yes. There's also the option of waiting for the kotlinx.serialization update before upgrading to the new kotlinx-datetime if you are using the Instant serializers.

[Thierry Kh]

Anyone using Compottie who noticed animations don't show with 0.7.0 ?

[Dmitry Khalanskiy [JB]]

Serializers are now available for kotlin.time.Instant in kotlinx.serialization 1.9.0. Some users report having issues with them, but we suspect it's purely IDE-related and does not affect compilation: https://github.com/Kotlin/kotlinx.serialization/issues/3026#issuecomment-3018712811