From dd1b76ee217a42ed3aaca4697b6198f1aaa4cfe2 Mon Sep 17 00:00:00 2001 From: Leonid Startsev Date: Thu, 16 May 2024 16:52:31 +0200 Subject: [PATCH] Prepare Changelog and Readme for 1.7.0-RC release --- CHANGELOG.md | 85 ++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 24 +++++++-------- RELEASING.md | 2 +- 3 files changed, 98 insertions(+), 13 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 22d392c333..749e066776 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,88 @@ + +1.7.0-RC / 2024-05-16 +================== + +This is a release candidate for the next version. It is based on Kotlin 2.0.0-RC3 and is fully compatible with a stable Kotlin 2.0 release. +Due to a potential breaking change (see below), it requires a compiler plugin with a version at least of 2.0.0-RC1. + +### Important change: priority of PolymorphicSerializer for interfaces during call to serializer() function + +Non-sealed interfaces in kotlinx.serialization are always [serializable with a polymorphic serializer](/~https://github.com/Kotlin/kotlinx.serialization/blob/master/docs/polymorphism.md#serializing-interfaces), +even if they do not have `@Serializable` annotation. This also means that `serializersModule.serializer()` call will return you a serializer capable of polymorphism. +This function was written in a way that it unconditionally returns a `PolymorphicSerializer` if type argument is a non-sealed interface. +This caused problems with `SerializersModule` functionality, because actual module was not taken into consideration, and therefore it was impossible +to override serializer for interface using 'contextual serialization' feature. The problem is described in details [here](/~https://github.com/Kotlin/kotlinx.serialization/issues/2060). +To overcome these problems, we had to change the behavior of this function regarding interfaces. It now looks into `SerializersModule` first if `T` is a non-sealed interface, +and only if there is no registered contextual serializer for `T`, it returns a polymorphic serializer. + +Behavior **before 1.7.0-RC**: + +```kotlin +interface SomeInterface + +val module = SerializersModule { + contextual(SomeInterface::class, CustomSomeInterfaceSerializer) +} + +// Prints PolymorphicSerializer: +println(module.serializer()) +``` + +Behavior **in 1.7.0-RC, 1.7.0, and higher**: + +```kotlin +interface SomeInterface + +val module = SerializersModule { + contextual(SomeInterface::class, CustomSomeInterfaceSerializer) +} + +// Prints CustomSomeInterfaceSerializer: +println(module.serializer()) +``` + +We expect minimal impact from this change but be aware of it anyway. +Implementation details are available in [this PR](/~https://github.com/Kotlin/kotlinx.serialization/issues/2060). + +Due to the [serializer() function being also a compiler intrinsic](/~https://github.com/Kotlin/kotlinx.serialization/issues/1348), code +of kotlinx.serialization compiler plugin also accommodates for this change in 2.0 branch. To get a consistent result from both plugin and runtime, +kotlinx.serialization compiler plugin should be **at least of 2.0.0-RC1 version.** +**To verify so, 1.7.0-RC runtime will be rejected by older plugins.** + +### Json configuration flag to allow commentaries + +While JSON standard does not allow any kind of commentaries, they are one of the most popular extensions — for example, +commentaries are widely used in configuration files. +To support this use-case, we added a new configuration flag, `allowComments`. +This flag allows the parser to skip over C/Java-style commentaries in JSON input. +Note that commentaries cannot affect decoding or encoding in any way and are not stored anywhere. +See details in [the PR](/~https://github.com/Kotlin/kotlinx.serialization/pull/2592). + +### Promote `JsonConfiguration.explicitNulls` to a stable API + +This configuration flag has been around for a long time and got positive feedback. +Therefore, we are promoting it to a stable state. +It also received functionality enhancements when used with `JsonConfiguration.coerceInputValues` ([#2586](/~https://github.com/Kotlin/kotlinx.serialization/issues/2586)). +See related [PR](/~https://github.com/Kotlin/kotlinx.serialization/pull/2661) for details. + +### `oneof` support in ProtoBuf + +`oneof` fields in protobuf messages [represent a set of optional fields](https://protobuf.dev/programming-guides/proto2/#oneof), where the only one of them is present. +With the help of the new `@ProtoOneOf` annotation, you can naturally map them to Kotlin's sealed class hierarchy. +Check out the comprehensive guide for this feature [here](/~https://github.com/Kotlin/kotlinx.serialization/blob/194a188563c612c63a88271eb3f28f37353df514/docs/formats.md#oneof-field-experimental). + +This functionality was [contributed](/~https://github.com/Kotlin/kotlinx.serialization/pull/2546) to us by [xzk](/~https://github.com/xiaozhikang0916). + +### Other improvements and bugfixes + +* Update okio to 3.9.0 version (#2671) +* Add extension to access original descriptor from one made with SerialDescriptor.nullable (#2633) (thanks to [Chuckame](/~https://github.com/Chuckame)) +* Use @SerialName of inline polymorphic children in Json (#2601) (thanks to [Tad Fisher](/~https://github.com/tadfisher)) +* Fix serializing nulls for a property of a parameterized type with a nullable upper bound with Protobuf (#2561) (thanks to [Shreck Ye](/~https://github.com/ShreckYe)) +* Fixed type discriminator value for custom serializer that uses `encodeJsonElement` (#2628) +* Refine exception messages in case of deserializing data from JsonElement. (#2648) + + 1.6.3 / 2024-02-16 ================== diff --git a/README.md b/README.md index d69420a932..7dce89c1de 100644 --- a/README.md +++ b/README.md @@ -4,8 +4,8 @@ [![JetBrains official project](https://jb.gg/badges/official.svg)](https://confluence.jetbrains.com/display/ALL/JetBrains+on+GitHub) [![GitHub license](https://img.shields.io/badge/license-Apache%20License%202.0-blue.svg?style=flat)](http://www.apache.org/licenses/LICENSE-2.0) [![TeamCity build](https://img.shields.io/teamcity/http/teamcity.jetbrains.com/s/KotlinTools_KotlinxSerialization_Ko.svg)](https://teamcity.jetbrains.com/viewType.html?buildTypeId=KotlinTools_KotlinxSerialization_Ko&guest=1) -[![Kotlin](https://img.shields.io/badge/kotlin-1.9.22-blue.svg?logo=kotlin)](http://kotlinlang.org) -[![Maven Central](https://img.shields.io/maven-central/v/org.jetbrains.kotlinx/kotlinx-serialization-core/1.6.3)](https://central.sonatype.com/artifact/org.jetbrains.kotlinx/kotlinx-serialization-core/1.6.3) +[![Kotlin](https://img.shields.io/badge/kotlin-2.0.0-blue.svg?logo=kotlin)](http://kotlinlang.org) +[![Maven Central](https://img.shields.io/maven-central/v/org.jetbrains.kotlinx/kotlinx-serialization-core/1.7.0-RC)](https://central.sonatype.com/artifact/org.jetbrains.kotlinx/kotlinx-serialization-core/1.7.0-RC) [![KDoc link](https://img.shields.io/badge/API_reference-KDoc-blue)](https://kotlinlang.org/api/kotlinx.serialization/) [![Slack channel](https://img.shields.io/badge/chat-slack-blue.svg?logo=slack)](https://kotlinlang.slack.com/messages/serialization/) @@ -95,8 +95,8 @@ Kotlin DSL: ```kotlin plugins { - kotlin("jvm") version "1.9.22" // or kotlin("multiplatform") or any other kotlin plugin - kotlin("plugin.serialization") version "1.9.22" + kotlin("jvm") version "2.0.0-RC3" // or kotlin("multiplatform") or any other kotlin plugin + kotlin("plugin.serialization") version "2.0.0-RC3" } ``` @@ -104,8 +104,8 @@ Groovy DSL: ```gradle plugins { - id 'org.jetbrains.kotlin.multiplatform' version '1.9.22' - id 'org.jetbrains.kotlin.plugin.serialization' version '1.9.22' + id 'org.jetbrains.kotlin.multiplatform' version '2.0.0-RC3' + id 'org.jetbrains.kotlin.plugin.serialization' version '2.0.0-RC3' } ``` @@ -123,7 +123,7 @@ buildscript { repositories { mavenCentral() } dependencies { - val kotlinVersion = "1.9.22" + val kotlinVersion = "2.0.0-RC3" classpath(kotlin("gradle-plugin", version = kotlinVersion)) classpath(kotlin("serialization", version = kotlinVersion)) } @@ -134,7 +134,7 @@ Groovy DSL: ```gradle buildscript { - ext.kotlin_version = '1.9.22' + ext.kotlin_version = '2.0.0-RC3' repositories { mavenCentral() } dependencies { @@ -164,7 +164,7 @@ repositories { } dependencies { - implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.3") + implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.7.0-RC") } ``` @@ -176,7 +176,7 @@ repositories { } dependencies { - implementation "org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.3" + implementation "org.jetbrains.kotlinx:kotlinx-serialization-json:1.7.0-RC" } ``` @@ -266,8 +266,8 @@ Ensure the proper version of Kotlin and serialization version: ```xml - 1.9.22 - 1.6.3 + 2.0.0-RC3 + 1.7.0-RC ``` diff --git a/RELEASING.md b/RELEASING.md index f8b90e9b1c..561fa0c9df 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -13,7 +13,7 @@ To release new `` of `kotlinx.serialization`: * [`gradle.properties`](gradle.properties) * [`integration-test/gradle.properties`](integration-test/gradle.properties) - Update Kotlin version, if necessary. + Update Kotlin version in [`libs.versions.toml`](gradle/libs.versions.toml), if necessary. 5. Write release notes in [`CHANGELOG.md`](CHANGELOG.md): * Use old releases as example of style.