If you are 1. *Not* using libraries that themselve...

# kotlinx-datetime

[Dmitry Khalanskiy [JB]]

If you are
1. Not using libraries that themselves depend on kotlinx-datetime 0.6.2 or earlier, and are also
2. Planning on upgrading to kotlinx-datetime 0.7.0, but haven't yet,
then you are advised to wait until 0.7.1 comes out in the next few days.

0.7.0 is missing some migration assistance, namely the deprecated-with-warning type aliases kotlinx.datetime.Instant = kotlin.time.Instant and kotlinx.datetime.Clock = kotlin.time.Clock (https://github.com/Kotlin/kotlinx-datetime/pull/540/commits/f829958a1bcbe7b24a11a91519cf57aaf3daa74b). Without them, your client code will not compile until you replace the usages manually, whereas with them, you will be able to proceed at your own pace (if you are not using libraries that themselves depend on kotlinx.datetime.Instant) or even perform automatic replacement with the help of an IDE.

This is a glaring omission that I made when publishing the release, and I am sorry about that. The type aliases in 0.7.0 were planned from the beginning, but due to my oversight, were missing from the release.

[Jacob Ras]

I did the migration already but I'm glad to hear a nicer update path was intended and will be available 🙂 Thanks for the update

[Emre]

I became aware of the 0.7 release when CI broke. I tried fixing it with the @ExperimentalTime tag, but bumped against this serialization problem:
> Serializer has not been found for type 'Instant?'. To use context serializer as fallback, explicitly annotate type or property with @Contextual
The kotlinx Instant was compatible with @Serializable, through kotlinx.datetime.serializers.InstantSerializer. My understanding is that 0.7.1 is going to fix this.

[Dmitry Khalanskiy [JB]]

This issue can be fixed by using kotlinx.serialization 1.9.0 with Kotlin 2.2.0. The IDE will incorrectly highlight some code as red, but the code should still compile: https://github.com/Kotlin/kotlinx.serialization/issues/3026#issuecomment-3018712811

[rocketraman]

Can you clarify how this relates to the compatibility release of kotlinx-datetime documented at https://github.com/Kotlin/kotlinx-datetime?tab=readme-ov-file#deprecation-of-instant? With the type aliases in 0.7.1, it appears that the compatibility release will no longer be necessary?

[Dmitry Khalanskiy [JB]]

@rocketraman, unfortunately, no, the compatibility release is still necessary.
Type aliases will make the compiler treat writing kotlinx.datetime.Instant and kotlin.time.Instant as basically the same thing. kotlinx.datetime.Instant will not have its own representation in the compiled file.
This means that libraries compiled with the existence of kotlinx.datetime.Instant in mind will not work with the plain 0.7.1 and will instead throw ClassNotFoundException when an attempt to access kotlinx.datetime.Instant is made. After all, the class truly does not exist as a separate entity.
The compatibility artifact has kotlinx.datetime.Instant as a proper class, which has many usability downsides, but preserves compatibility with libraries not yet recompiled with kotlinx-datetime 0.7.x.

[rocketraman]

Thanks for the clarification

[rocketraman]

Can you also document or provide a recommended path for library authors that wish to maintain backward compatibility with Kotlin < 2.1, but also compile against 0.7.x to avoid users on 2.1+ having to use the compatibility lib?

[Dmitry Khalanskiy [JB]]

If some users only have kotlin.time.Instant but not kotlinx.datetime.Instant, whereas others only have kotlinx.datetime.Instant but not kotlin.time.Instant, then you have to do some runtime check like try { println(kotlinx.datetime.Instant.fromEpochSeconds(0)) } catch (e: ClassNotFoundException) { println(kotlin.time.Instant.fromEpochSeconds(0)) } for every usage. You will also need to have a compile-only dependency on Kotlin 2.1.20 and a compile-only dependency on the compatibility artifact of kotlinx-datetime.

[rocketraman]

Right, or if possible, separate modules for each version

[Dmitry Khalanskiy [JB]]

My earlier comment regarding this may be useful: https://kotlinlang.slack.com/archives/C01923PC6A0/p1750799482451409?thread_ts=1750776789.877609&amp;cid=C01923PC6A0