|
| 1 | + |
| 2 | +1.7.0-RC / 2024-05-16 |
| 3 | +================== |
| 4 | + |
| 5 | +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. |
| 6 | +Due to a potential breaking change (see below), it requires a compiler plugin with a version at least of 2.0.0-RC1. |
| 7 | + |
| 8 | +### Important change: priority of PolymorphicSerializer for interfaces during call to serializer<T>() function |
| 9 | + |
| 10 | +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), |
| 11 | +even if they do not have `@Serializable` annotation. This also means that `serializersModule.serializer<SomeInterface>()` call will return you a serializer capable of polymorphism. |
| 12 | +This function was written in a way that it unconditionally returns a `PolymorphicSerializer` if type argument is a non-sealed interface. |
| 13 | +This caused problems with `SerializersModule` functionality, because actual module was not taken into consideration, and therefore it was impossible |
| 14 | +to override serializer for interface using 'contextual serialization' feature. The problem is described in details [here](https://github.com/Kotlin/kotlinx.serialization/issues/2060). |
| 15 | +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, |
| 16 | +and only if there is no registered contextual serializer for `T`, it returns a polymorphic serializer. |
| 17 | + |
| 18 | +Behavior **before 1.7.0-RC**: |
| 19 | + |
| 20 | +```kotlin |
| 21 | +interface SomeInterface |
| 22 | + |
| 23 | +val module = SerializersModule { |
| 24 | + contextual(SomeInterface::class, CustomSomeInterfaceSerializer) |
| 25 | +} |
| 26 | + |
| 27 | +// Prints PolymorphicSerializer<SomeInterface>: |
| 28 | +println(module.serializer<SomeInterface>()) |
| 29 | +``` |
| 30 | + |
| 31 | +Behavior **in 1.7.0-RC, 1.7.0, and higher**: |
| 32 | + |
| 33 | +```kotlin |
| 34 | +interface SomeInterface |
| 35 | + |
| 36 | +val module = SerializersModule { |
| 37 | + contextual(SomeInterface::class, CustomSomeInterfaceSerializer) |
| 38 | +} |
| 39 | + |
| 40 | +// Prints CustomSomeInterfaceSerializer: |
| 41 | +println(module.serializer<SomeInterface>()) |
| 42 | +``` |
| 43 | + |
| 44 | +We expect minimal impact from this change but be aware of it anyway. |
| 45 | +Implementation details are available in [this PR](https://github.com/Kotlin/kotlinx.serialization/issues/2060). |
| 46 | + |
| 47 | +Due to the [serializer() function being also a compiler intrinsic](https://github.com/Kotlin/kotlinx.serialization/issues/1348), code |
| 48 | +of kotlinx.serialization compiler plugin also accommodates for this change in 2.0 branch. To get a consistent result from both plugin and runtime, |
| 49 | +kotlinx.serialization compiler plugin should be **at least of 2.0.0-RC1 version.** |
| 50 | +**To verify so, 1.7.0-RC runtime will be rejected by older plugins.** |
| 51 | + |
| 52 | +### Json configuration flag to allow commentaries |
| 53 | + |
| 54 | +While JSON standard does not allow any kind of commentaries, they are one of the most popular extensions — for example, |
| 55 | +commentaries are widely used in configuration files. |
| 56 | +To support this use-case, we added a new configuration flag, `allowComments`. |
| 57 | +This flag allows the parser to skip over C/Java-style commentaries in JSON input. |
| 58 | +Note that commentaries cannot affect decoding or encoding in any way and are not stored anywhere. |
| 59 | +See details in [the PR](https://github.com/Kotlin/kotlinx.serialization/pull/2592). |
| 60 | + |
| 61 | +### Promote `JsonConfiguration.explicitNulls` to a stable API |
| 62 | + |
| 63 | +This configuration flag has been around for a long time and got positive feedback. |
| 64 | +Therefore, we are promoting it to a stable state. |
| 65 | +It also received functionality enhancements when used with `JsonConfiguration.coerceInputValues` ([#2586](https://github.com/Kotlin/kotlinx.serialization/issues/2586)). |
| 66 | +See related [PR](https://github.com/Kotlin/kotlinx.serialization/pull/2661) for details. |
| 67 | + |
| 68 | +### `oneof` support in ProtoBuf |
| 69 | + |
| 70 | +`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. |
| 71 | +With the help of the new `@ProtoOneOf` annotation, you can naturally map them to Kotlin's sealed class hierarchy. |
| 72 | +Check out the comprehensive guide for this feature [here](https://github.com/Kotlin/kotlinx.serialization/blob/194a188563c612c63a88271eb3f28f37353df514/docs/formats.md#oneof-field-experimental). |
| 73 | + |
| 74 | +This functionality was [contributed](https://github.com/Kotlin/kotlinx.serialization/pull/2546) to us by [xzk](https://github.com/xiaozhikang0916). |
| 75 | + |
| 76 | +### Other improvements and bugfixes |
| 77 | + |
| 78 | +* Update okio to 3.9.0 version (#2671) |
| 79 | +* Add extension to access original descriptor from one made with SerialDescriptor.nullable (#2633) (thanks to [Chuckame](https://github.com/Chuckame)) |
| 80 | +* Use @SerialName of inline polymorphic children in Json (#2601) (thanks to [Tad Fisher](https://github.com/tadfisher)) |
| 81 | +* 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)) |
| 82 | +* Fixed type discriminator value for custom serializer that uses `encodeJsonElement` (#2628) |
| 83 | +* Refine exception messages in case of deserializing data from JsonElement. (#2648) |
| 84 | + |
| 85 | + |
1 | 86 | 1.6.3 / 2024-02-16 |
2 | 87 | ================== |
3 | 88 |
|
|
0 commit comments