Prepare Changelog and Readme for 1.7.0-RC releaseupstream/v1.7.0-RCupstream-master

3 files changed, 98 insertions, 13 deletions

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 22d392c3..749e0667 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<T>() 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<SomeInterface>()` 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<SomeInterface>:
+println(module.serializer<SomeInterface>())
+```
+
+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<SomeInterface>())
+```
+
+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 d69420a9..7dce89c1 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
 <properties>
-    <kotlin.version>1.9.22</kotlin.version>
-    <serialization.version>1.6.3</serialization.version>
+    <kotlin.version>2.0.0-RC3</kotlin.version>
+    <serialization.version>1.7.0-RC</serialization.version>
 </properties>
 ```
 
diff --git a/RELEASING.md b/RELEASING.md
index f8b90e9b..561fa0c9 100644
--- a/RELEASING.md
+++ b/RELEASING.md
@@ -13,7 +13,7 @@ To release new `<version>` 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.