From 50c4e5d0a6feda40dd41e6211b027557090735bd Mon Sep 17 00:00:00 2001
From: Alexander Sysoev <Alexander.Sysoev@jetbrains.com>
Date: Mon, 19 Aug 2024 14:39:33 +0200
Subject: [PATCH] Migration guide to 0.2.3 (KRPC-112)

---
 docs/pages/kotlinx-rpc/rpc.tree           |  1 +
 docs/pages/kotlinx-rpc/topics/0-2-3.topic | 55 +++++++++++++++++++++++
 2 files changed, 56 insertions(+)
 create mode 100644 docs/pages/kotlinx-rpc/topics/0-2-3.topic

diff --git a/docs/pages/kotlinx-rpc/rpc.tree b/docs/pages/kotlinx-rpc/rpc.tree
index 78de9b6b..30864a08 100644
--- a/docs/pages/kotlinx-rpc/rpc.tree
+++ b/docs/pages/kotlinx-rpc/rpc.tree
@@ -26,6 +26,7 @@
     </toc-element>
     <toc-element topic="versions.topic"/>
     <toc-element toc-title="Migration guides">
+        <toc-element topic="0-2-3.topic"/>
         <toc-element topic="0-2-1.topic"/>
     </toc-element>
 </instance-profile>
\ No newline at end of file
diff --git a/docs/pages/kotlinx-rpc/topics/0-2-3.topic b/docs/pages/kotlinx-rpc/topics/0-2-3.topic
new file mode 100644
index 00000000..32712ce1
--- /dev/null
+++ b/docs/pages/kotlinx-rpc/topics/0-2-3.topic
@@ -0,0 +1,55 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE topic
+        SYSTEM "https://resources.jetbrains.com/writerside/1.0/xhtml-entities.dtd">
+<topic xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+       xsi:noNamespaceSchemaLocation="https://resources.jetbrains.com/writerside/1.0/topic.v2.xsd"
+       title="Migration to 0.2.3" id="0-2-3">
+
+    <p>
+        Version <code>0.2.3</code> does introduce any breaking changes.
+        However, it includes some updates that may require additional modifications in user projects.
+    </p>
+    <chapter title="Removal of KSP plugin for Kotlin 2.0" id="removal-of-ksp-plugin-for-kotlin-2-0">
+        If your project uses Kotlin 2.0,
+        you are no longer required to add KSP Gradle plugin to your build files:
+        <code-block lang="kotlin">
+            plugins {
+                kotlin("jvm") version "2.0.10"
+                kotlin("plugin.serialization") version "2.0.10"
+                id("org.jetbrains.kotlinx.rpc.plugin") version "0.2.3"
+
+                // KSP can be removed
+                // id("com.google.devtools.ksp") version "2.0.10-1.0.24"
+            }
+        </code-block>
+        This change brings one more benefit:
+        without KSP, projects that use <code>kotlinx.rpc</code>
+        can now use <a href="https://docs.gradle.org/current/userguide/configuration_cache.html">Gradle configuration
+        caches</a>.
+    </chapter>
+    <chapter title="Moving of client APIs" id="moving-of-client-apis">
+        Some client APIs were moved from <code>kotlinx-rpc-krpc-client</code> artifact (and package)
+        into <code>kotlinx-rpc-core</code> module (and package). These APIs are not kRPC specific hence the move.
+        <p>List of API changes:</p>
+        <table>
+            <tr>
+                <td><code>0.2.2</code></td>
+                <td><code>0.2.3</code></td>
+            </tr>
+            <tr>
+                <td><code>kotlinx.rpc.client.withService</code></td>
+                <td><code>kotlinx.rpc.withService</code></td>
+            </tr>
+            <tr>
+                <td><code>kotlinx.rpc.client.awaitFieldInitialization</code></td>
+                <td><code>kotlinx.rpc.awaitFieldInitialization</code></td>
+            </tr>
+            <tr>
+                <td><code>kotlinx.rpc.client.UninitializedRPCFieldException</code></td>
+                <td><code>kotlinx.rpc.UninitializedRPCFieldException</code></td>
+            </tr>
+        </table>
+        Old declaration and marked with <code>@Deprecated(WARNING)</code>
+        and will be removed in 2 minor releases.
+    </chapter>
+</topic>
\ No newline at end of file