Updated docs for 0.4.0; bumped version (#222)

Co-authored-by: Viktoriya Nikolova <[email protected]>
Kotlin · Nov 5, 2024 · 727511b · 727511b
1 parent e70e1ca
commit 727511b
Show file tree

Hide file tree

Showing 15 changed files with 159 additions and 161 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -20,7 +20,7 @@ env:
   ALGOLIA_INDEX_NAME: 'prod_kotlin_rpc'
   ALGOLIA_KEY: '${{ secrets.ALGOLIA_KEY }}'
   CONFIG_JSON_PRODUCT: 'kotlinx-rpc'
-  CONFIG_JSON_VERSION: '0.3.0'
+  CONFIG_JSON_VERSION: '0.4.0'
 
 jobs:
   build:

diff --git a/README.md b/README.md
@@ -7,7 +7,7 @@
 
 [![Kotlin Experimental](https://kotl.in/badges/experimental.svg)](https://kotlinlang.org/docs/components-stability.html)
 [![Official JetBrains project](http://jb.gg/badges/official.svg)](https://confluence.jetbrains.com/display/ALL/JetBrains+on+GitHub)
-[![Kotlin](https://img.shields.io/badge/kotlin-1.7.0--2.0.10-blue.svg?logo=kotlin)](http://kotlinlang.org)
+[![Kotlin](https://img.shields.io/badge/kotlin-2.0.0--2.0.21-blue.svg?logo=kotlin)](http://kotlinlang.org)
 [![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]&#40;https://img.shields.io/teamcity/build/s/Build_kRPC_All.svg?server=http%3A%2F%2Fkrpc.teamcity.com&#41;]&#40;https://teamcity.jetbrains.com/viewType.html?buildTypeId=Build_kRPC_All&guest=1&#41;)
@@ -84,33 +84,18 @@ Check out our [getting started guide](https://kotlin.github.io/kotlinx-rpc) for
 
 ### Plugin dependencies
 
-`kotlinx.rpc` has the following plugin dependencies:
-- The `org.jetbrains.kotlinx.rpc.plugin` will set up BOM and code generation for targets in the project.
-- The `org.jetbrains.kotlinx.rpc.platform` will only set up BOM. It is useful when you want to split your app into modules, 
-and some of them will contain service declarations, thus using code generation, while others will only consume them.
+`kotlinx.rpc` provides Gradle plugin `org.jetbrains.kotlinx.rpc.plugin` 
+that will set up code generation in a project.
 
-Example of plugins setup in a project's `build.gradle.kts`:
+Example of a setup in a project's `build.gradle.kts`:
 ```kotlin
 plugins {
-    kotlin("jvm") version "2.0.10"
-    kotlin("plugin.serialization") version "2.0.10"
-    id("org.jetbrains.kotlinx.rpc.plugin") version "0.3.0"
+    kotlin("multiplatform") version "2.0.21"
+    kotlin("plugin.serialization") version "2.0.21"
+    id("org.jetbrains.kotlinx.rpc.plugin") version "0.4.0"
 }
 ```
 
-For Kotlin versions prior to 2.0, 
-KSP plugin is required 
-(Corresponding configurations will be set up automatically by `org.jetbrains.kotlinx.rpc.plugin` plugin):
-
-```kotlin
-// build.gradle.kts
-plugins {
-    kotlin("jvm") version "1.9.25"
-    kotlin("plugin.serialization") version "1.9.25"
-    id("com.google.devtools.ksp") version "1.9.25-1.0.20"
-    id("org.jetbrains.kotlinx.rpc.plugin") version "0.3.0"
-}
-```
 ### Runtime dependencies
 To use `kotlinx.rpc` runtime dependencies, add Maven Central to the list of your repositories: 
 ```kotlin
@@ -121,16 +106,16 @@ repositories {
 And now you can add dependencies to your project:
 ```kotlin
 dependencies {
-    // client API
-    implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-client")
-    // server API
-    implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-server") 
-    // serialization module. also, protobuf and cbor are available
-    implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-serialization-json") 
+    // Client API
+    implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-client:0.4.0")
+    // Server API
+    implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-server:0.4.0") 
+    // Serialization module. Also, protobuf and cbor are provided
+    implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-serialization-json:0.4.0") 
 
-    // transport implementation for Ktor
-    implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-ktor-client")
-    implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-ktor-server")
+    // Transport implementation for Ktor
+    implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-ktor-client:0.4.0")
+    implementation("org.jetbrains.kotlinx:kotlinx-rpc-krpc-ktor-server:0.4.0")
 
     // Ktor API
     implementation("io.ktor:ktor-client-cio-jvm:$ktor_version")
@@ -143,7 +128,7 @@ You can see example projects in the [samples](samples) folder.
 `kotlinx.rpc` is designed to be transport agnostic.
 That means that the library aims to provide the best RPC experience regardless of how the resulting messages are transferred. 
 That allows for easy integration into existing solutions, such as Ktor, without the need to rewrite code.
-Just plug-in `kotlinx.rpc`, provide it with means to transfer encoded data (or use out-of-the-box integrations) and it will run.
+Add `kotlinx.rpc`, provide it with means to transfer encoded data (or use out-of-the-box integrations) and it will run.
 With enough time it might even work with [avian carriers](https://en.wikipedia.org/wiki/IP_over_Avian_Carriers).
 
 `kotlinx.rpc` provides its own transfer protocol called kRPC, which takes responsibility for tracking serializing and handling other complex request operations.
@@ -154,26 +139,12 @@ Besides that, one can even provide their own protocol or integration with one to
 Though possible, it is much more complicated way to use the library and generally not needed. 
 `kotlinx.rpc` aims to provide most common protocols integrations as well as the in-house one called kRPC.  
 Integrations in progress:
-- Integration with [gRPC](https://grpc.io/)  (in prototype)
+- Integration with [gRPC](https://grpc.io/) (in prototype)
 
 ## Kotlin compatibility
 We support all stable Kotlin versions starting from 2.0.0:
 - 2.0.0, 2.0.10, 2.0.20, 2.0.21
 
-To simplify project configuration, our Gradle plugin sets a proper library version automatically using BOM, 
-based on the project's Kotlin version:
-```kotlin
-plugins {
-    kotlin("jvm") version "2.0.10"
-    id("org.jetbrains.kotlinx.rpc.plugin") version "0.3.0"
-}
-
-dependencies {
-    // version 0.3.0 is set by the Gradle plugin
-    implementation("org.jetbrains.kotlinx:kotlinx-rpc-core") 
-}
-```
-
 For a full compatibility checklist, 
 see [Versions](https://kotlin.github.io/kotlinx-rpc/versions.html).
 

diff --git a/docs/pages/kotlinx-rpc/help-versions.json b/docs/pages/kotlinx-rpc/help-versions.json
@@ -1,3 +1,3 @@
 [
-  {"version":"0.3.0","url":"/kotlinx-rpc/0.3.0/","isCurrent":true}
+  {"version":"0.4.0","url":"/kotlinx-rpc/0.4.0/","isCurrent":true}
 ]
diff --git 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-4-0.topic"/>
         <toc-element topic="0-3-0.topic"/>
         <toc-element topic="0-2-4.topic"/>
         <toc-element topic="0-2-1.topic"/>

diff --git a/docs/pages/kotlinx-rpc/topics/0-4-0.topic b/docs/pages/kotlinx-rpc/topics/0-4-0.topic
@@ -0,0 +1,90 @@
+<?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.4.0" id="0-4-0">
+    <p>
+        Version <code>0.4.0</code> introduces breaking changes.
+    </p>
+    <chapter title="@Rpc Annotation and RemoteService Interface" id="rpc_annotation_and_remote_service_interface">
+        <p>
+            This version brings changes to service definitions. Starting with this version, service definitions require
+            the <code>@Rpc</code> annotation.
+        </p>
+        <p>
+            Prior to <code>0.4.0</code>, a service was defined as follows:
+        </p>
+        <code-block lang="kotlin">
+            interface MyService : RPC
+        </code-block>
+        <p>
+            Starting from <code>0.4.0</code>, the new service definition should be:
+        </p>
+        <code-block lang="kotlin">
+            @Rpc
+            interface MyService
+        </code-block>
+        <p>
+            This definition is sufficient for the project to build. However, it will not fully support IDE features,
+            such as code highlighting.
+            All interfaces annotated with <code>@Rpc</code> are inherently of type <code>RemoteService</code>, which is
+            added by the compiler plugin, but IDEs won't be able to resolve it.
+        </p>
+        <p>
+            To ensure proper IDE support, add explicit typing:
+        </p>
+        <code-block lang="kotlin">
+            @Rpc
+            interface MyService : RemoteService
+        </code-block>
+        <note>
+            <p>
+                The reasoning behind this update is that the Kotlin Compiler Plugin API has changed.
+                Versions <code>2.0.0</code> and <code>2.0.10</code> allowed our plugin to resolve marker interfaces (like <code>RPC</code>)
+                before the code generation phase. Starting from version <code>2.0.20</code>, this behaviour changed,
+                making annotations the only reliable way to detect RPC services.
+            </p>
+            <p>
+                To track changes in this regard, we raised an <a href="https://youtrack.jetbrains.com/issue/KT-72654">issue</a>
+                with the compiler team.
+                Note that this approach is subject to change, and the final API design may be updated before the stable
+                release.
+            </p>
+        </note>
+    </chapter>
+    <chapter title="Removal of Kotlin versions prior to 2.0" id="removal_of_kotlin_versions_prior_to_2_0">
+        <p>
+            We stopped publishing compiler plugin artifacts for Kotlin versions prior to <code>2.0.0</code>.
+            The reason being its high maintenance cost with little to no usage.
+            We encourage the migration to Kotlin 2.0, where all stable versions are now supported.
+            <br/>
+        </p>
+        <p>
+            Currently supported Kotlin versions: <code>2.0.0</code>, <code>2.0.10</code>, <code>2.0.20</code>, <code>2.0.21</code>
+        </p>
+    </chapter>
+    <chapter title="Removal of org.jetbrains.kotlinx.rpc.platform Gradle plugin"
+             id="removal_of_org_jetbrains_kotlinx_rpc_platform_gradle_plugin">
+        <p>
+            The Gradle plugin with id <code>org.jetbrains.kotlinx.rpc.platform</code> is not being published anymore.
+            The reason is that it's sole role was to set BOM in the project, which is now considered unnecessary.
+            <a href="https://docs.gradle.org/current/userguide/platforms.html#sub:conventional-dependencies-toml">Gradle version catalogs</a>
+            can be used instead.
+        </p>
+    </chapter>
+    <chapter title="Removal of BOM from the Gradle plugin" id="removal_of_bom_from_the_gradle_plugin">
+        <p>
+            The Gradle plugin with id <code>org.jetbrains.kotlinx.rpc.plugin</code>
+            does not set BOM for the project anymore.
+        </p>
+        <p>
+            To configure BOM manually, add the following dependency:
+        </p>
+        <code-block lang="kotlin">
+            dependencies {
+                implementation(platform("org.jetbrains.kotlinx:kotlinx-rpc-bom:%kotlinx-rpc-version%"))
+            }
+        </code-block>
+    </chapter>
+</topic>
diff --git a/docs/pages/kotlinx-rpc/topics/features.topic b/docs/pages/kotlinx-rpc/topics/features.topic
@@ -36,7 +36,8 @@
                 that will provide your flows with their lifetime:</p>
 
             <code-block lang="kotlin">
-                interface MyService {
+                @Rpc
+                interface MyService : RemoteService {
                     suspend fun sendFlow(flow: Flow&lt;Int&gt;)
                 }
 
@@ -81,6 +82,17 @@
                 }
             </code-block>
             <p>Note that this API is experimental and may be removed in future releases.</p>
+            <p>
+                Another way of managing streams is to do it manually.
+                For this, you can use the <code>StreamScope</code> constructor function together with
+                <code>withStreamScope</code>:
+            </p>
+            <code-block lang="kotlin">
+                val streamScope = StreamScope(myJob)
+                withStreamScope(streamScope) {
+                    // use streams here
+                }
+            </code-block>
         </chapter>
     <chapter title="Service fields" id="service-fields">
             <p>Our protocol provides you with an ability to declare service fields:</p>

diff --git a/docs/pages/kotlinx-rpc/topics/get-started.topic b/docs/pages/kotlinx-rpc/topics/get-started.topic
@@ -110,33 +110,23 @@
         </chapter>
 
         <chapter title="Add plugin dependencies" id="add-gradle-plugin">
-            <p><code>kotlinx.rpc</code> provides <a href="plugins.topic">two Gradle plugins</a>:</p>
-            <list>
-                <li>
-                    <a href="plugins.topic" anchor="rpc-platform">
-                        <code>org.jetbrains.kotlinx.rpc.platform</code>
-                    </a>
-                </li>
-                <li>
-                    <a href="plugins.topic" anchor="rpc-plugin">
-                        <code>org.jetbrains.kotlinx.rpc.plugin</code>
-                    </a>
-                </li>
-            </list>
             <p>
-                To add a plugin to your project, you need to define the following in your <path>build.gradle.kts</path>:
+                To add a <a href="plugins.topic">Gradle plugin</a> to your project, you need to define the following in your <path>build.gradle.kts</path>:
             </p>
 
             <code-block lang="kotlin">
                 plugins {
                     id(&quot;org.jetbrains.kotlinx.rpc.plugin&quot;) version &quot;%kotlinx-rpc-version%&quot;
                 }
             </code-block>
-            <p>To learn more about versioning, see <a href="versions.topic"/>.</p>
+
+            <p>
+                This will configure code generation for your project.
+            </p>
         </chapter>
 
         <chapter title="Add serialization dependency" id="add-serialization-dependency">
-            <p><code>kotlinx.rpc</code> requires you to add
+            <p><code>kotlinx.rpc</code> requires you to add the
                 <a href="https://github.com/Kotlin/kotlinx.serialization">kotlinx.serialization</a>
                 Gradle plugin to your project.</p>