feat: update the Kotlin release information and evolution principles (#…

…4173)

* update: update kotlin-evolution.md

* update: update releases.md

* update: update wording

* update: review fixes, anchor fixes

* fix: fix one more anchor

docs/topics/components-stability-pre-1.4.md

@@ -1,12 +1,12 @@
 [//]: # (title: Stability of Kotlin components \(pre 1.4\))
 
-There can be different modes of stability depending of how quickly a component is evolving:
+There can be different modes of stability depending on how quickly a component is evolving:
 <a name="moving-fast"></a>
-*   **Moving fast (MF)**: no compatibility should be expected between even [incremental releases](kotlin-evolution.md#feature-releases-and-incremental-releases), any functionality can be added, removed or changed without warning.
+*   **Moving fast (MF)**: no compatibility should be expected between even [incremental releases](kotlin-evolution.md#language-and-tooling-releases), any functionality can be added, removed or changed without warning.
 
 *   **Additions in Incremental Releases (AIR)**: things can be added in an incremental release, removals and changes of behavior should be avoided and announced in a previous incremental release if necessary.
 
-*   **Stable Incremental Releases (SIR)**: incremental releases are fully compatible, only optimizations and bug fixes happen. Any changes can be made in a [feature release](kotlin-evolution.md#feature-releases-and-incremental-releases).
+*   **Stable Incremental Releases (SIR)**: incremental releases are fully compatible, only optimizations and bug fixes happen. Any changes can be made in a [language release](kotlin-evolution.md#language-and-tooling-releases).
 
 <a name="fully-stable"></a>
 *   **Fully Stable (FS)**: incremental releases are fully compatible, only optimizations and bug fixes happen. Feature releases are backwards compatible.

docs/topics/releases.md

@@ -1,57 +1,92 @@
 [//]: # (title:  Kotlin releases)
 
-We ship different types of releases:
+Since Kotlin 2.0.0, we ship the following types of releases:
 
-* _Feature releases_ (1._x_) that bring major changes in the language.
-* _Incremental releases_ (1._x_._y_) that are shipped between feature releases and include updates in the tooling,
-  performance improvements, and bug fixes.
-* _Bug fix releases_ (1._x_._yz_) that include bug fixes for incremental releases.
+* _Language releases_ (2._x_._0_) that bring major changes in the language and include tooling updates. Released once in 6 months.
+* _Tooling releases_ (2._x_._20_) that are shipped between language releases and include updates in the tooling,
+    performance improvements, and bug fixes.
+    Released in 3 months after corresponding _language release_.
+* _Bug fix releases_ (2._x_._yz_) that include bug fixes for _tooling releases_. There is no exact release schedule for these releases.
 
-For example, for the feature release 1.3 we had several incremental releases including 1.3.10, 1.3.20, and 1.3.70.
-For 1.3.70, we had 2 bug fix releases – 1.3.71 and 1.3.72.
+<!-- TODO: uncomment with 2.1.0 release
+> For example, for the feature release 1.8.0, we had only one tooling release 1.8.20,
+> and several bugfix releases including 1.8.21, 1.8.22.
+>
+{type="tip"}
+-->
 
-For each incremental and feature release, we also ship several preview (_EAP_) versions for you to try
+For each language and tooling release, we also ship several preview (_EAP_) versions for you to try
 new features before they are released. See [Early Access Preview](eap.md) for details.
 
-Learn more about [types of Kotlin releases and their compatibility](kotlin-evolution.md#feature-releases-and-incremental-releases).
-
 ## Update to a new release
 
-> Starting from IntelliJ IDEA 2023.3 and Android Studio Iguana (2023.2.1) Canary 15, the Kotlin plugin is automatically
-> updated. All you need to do is update the Kotlin version in your projects.
->
-{type="note"}
+To upgrade your project to a new release, you need to update your build script file.
+For example, to update to Kotlin %kotlinVersion%, change the version of the Kotlin Gradle plugin in your
+`build.gradle(.kts)` file:
+
+<tabs group="build-script">
+<tab title="Kotlin" group-key="kotlin">
 
-IntelliJ IDEA and Android Studio suggest updating to a new release once it is out. When you accept the suggestion,
-it automatically updates the Kotlin plugin to the new version. You can check the Kotlin version in **Tools** | **Kotlin**
-| **Configure Kotlin Plugin Updates**.
+```kotlin
+plugins {
+    // Replace `<...>` with the plugin name appropriate for your target environment
+    kotlin("<...>") version "%kotlinVersion%"
+    // For example, if your target environment is JVM:
+    // kotlin("jvm") version "%kotlinVersion%"
+    // If you target is Kotlin Multiplatform
+    // kotlin("multiplatform") version "%kotlinVersion%"
+}
+```
+
+</tab>
+<tab title="Groovy" group-key="groovy">
+
+```groovy
+plugins {
+    // Replace `<...>` with the plugin name appropriate for your target environment
+    id 'org.jetbrains.kotlin.<...>' version '%kotlinVersion%'
+    // For example, if your target environment is JVM: 
+    // id 'org.jetbrains.kotlin.jvm' version '%kotlinVersion%'
+    // If you target is Kotlin Multiplatform
+    // id 'org.jetbrains.kotlin.multiplatform' version '%kotlinVersion%'
+}
+```
+
+</tab>
+</tabs>
 
 If you have projects created with earlier Kotlin versions, change the Kotlin version in your projects and update kotlinx
 libraries if necessary.
 
-If you are migrating to the new feature release, Kotlin plugin's migration tools will help you with the migration.
+If you are migrating to the new language release, Kotlin plugin's migration tools will help you with the migration.
 
 ## IDE support
 
-The IDE support for the latest version of the language is available for the following versions of IntelliJ IDEA and Android Studio:
-* IntelliJ IDEA:
-    * Latest stable
-    * Previous stable
-    * [Early access](https://www.jetbrains.com/resources/eap/) versions
-* Android Studio:
-    * [Latest released](https://developer.android.com/studio) version
-    * [Early access](https://developer.android.com/studio/preview) versions
+Even with the release of the K2 compiler, IntelliJ IDEA and Android Studio still use the K1 compiler by default 
+for code analysis, code completion, highlighting, and other IDE-related features.
 
-> Learn more about the latest Kotlin-related updates in IntelliJ IDEA in the **Kotlin** section of the
-> [What's new in IntelliJ IDEA page](https://www.jetbrains.com/idea/whatsnew/).
-> 
-{type="tip"}
+Starting from 2024.1, IntelliJ IDEA can use the new K2 compiler to analyze your code with its K2 Kotlin mode.
+To enable it, go to **Settings** | **Languages & Frameworks** | **Kotlin** and select the **Enable the K2-based Kotlin plugin** option.
+
+> The K2 Kotlin mode is in Alpha. The performance and stability of code highlighting and code completion have been significantly improved,
+> but not all IDE features are supported yet.
+>
+{type="warning"}
+
+After enabling K2 mode, you may notice differences in IDE analysis due to changes in compiler behavior.
+Learn how the K2 compiler differs from K1 in the [migration guide](k2-compiler-migration-guide.md).
+
+## Kotlin release compatibility
+
+Learn more about [types of Kotlin releases and their compatibility](kotlin-evolution.md#language-and-tooling-releases)
 
 ## Release details
 
-The following table lists details of the latest Kotlin releases.
+The following table lists details of the latest Kotlin releases:
 
-You can also use [preview versions of Kotlin](eap.md#build-details).
+> You can also use [preview versions of Kotlin](eap.md#build-details).
+> 
+{type="tip"}
 
 <table>
     <tr>
@@ -118,7 +153,10 @@ You can also use [preview versions of Kotlin](eap.md#build-details).
             <p><a href="https://github.com/JetBrains/kotlin/releases/tag/v1.9.0" target="_blank">Release on GitHub</a></p>
         </td>
         <td>
-            <p>A feature release with Kotlin K2 compiler updates, new enum class values function, new operator for open-ended ranges, preview of Gradle configuration cache in Kotlin Multiplatform, changes to Android target support in Kotlin Multiplatform, preview of custom memory allocator in Kotlin/Native.</p>
+            <p>A feature release with Kotlin K2 compiler updates, new enum class values function,
+                new operator for open-ended ranges, preview of Gradle configuration cache in Kotlin Multiplatform, 
+                changes to Android target support in Kotlin Multiplatform, preview of custom memory allocator in Kotlin/Native.
+            </p>
             <p>Learn more in:</p>
             <list>
                 <li><a href="whatsnew19.md" target="_blank">What's new in Kotlin 1.9.0</a></li>
@@ -153,7 +191,9 @@ You can also use [preview versions of Kotlin](eap.md#build-details).
             <p><a href="https://github.com/JetBrains/kotlin/releases/tag/v1.8.20" target="_blank">Release on GitHub</a></p>
         </td>
         <td>
-            <p>A feature release with Kotlin K2 compiler updates, AutoCloseable interface and Base64 encoding in stdlib, new JVM incremental compilation enabled by default, new Kotlin/Wasm compiler backend.</p>
+            <p>A feature release with Kotlin K2 compiler updates, AutoCloseable interface and Base64 encoding in stdlib,
+                new JVM incremental compilation enabled by default, new Kotlin/Wasm compiler backend.
+            </p>
             <p>Learn more in:</p>
             <list>
                 <li><a href="whatsnew1820.md" target="_blank">What's new in Kotlin 1.8.20</a></li>
@@ -203,7 +243,9 @@ You can also use [preview versions of Kotlin](eap.md#build-details).
             <p><a href="https://github.com/JetBrains/kotlin/releases/tag/v1.7.20" target="_blank">Release on GitHub</a></p>
         </td>
         <td>
-          <p>An incremental release with new language features, the support for several compiler plugins in the Kotlin K2 compiler, the new Kotlin/Native memory manager enabled by default, and the support for Gradle 7.1.</p>
+            <p>An incremental release with new language features, the support for several compiler plugins in the Kotlin K2 compiler,
+                the new Kotlin/Native memory manager enabled by default, and the support for Gradle 7.1.
+            </p>
             <p>Learn more in:</p>
             <list>
                 <li><a href="whatsnew1720.md" target="_blank">What's new in Kotlin 1.7.20</a></li>

docs/topics/whatsnew14.md

@@ -1517,7 +1517,7 @@ to help you decide which suggestions to accept and which to ignore.
 
 ![Migration inspections](migration-inspection-wn.png)
 
-Kotlin 1.4.0 is a [feature release](kotlin-evolution.md#feature-releases-and-incremental-releases) and therefore can 
+Kotlin 1.4.0 is a [feature release](kotlin-evolution.md#language-and-tooling-releases) and therefore can 
 bring incompatible changes to the language. Find the detailed list of such changes in the **[Compatibility Guide for Kotlin 1.4](compatibility-guide-14.md)**.
 
 <!-- ### Migrating multiplatform projects

docs/topics/whatsnew15.md

@@ -791,5 +791,5 @@ To start a new project with Kotlin 1.5.0, update the Kotlin plugin and run the P
 
 The new command-line compiler is available for downloading on the [GitHub release page](https://github.com/JetBrains/kotlin/releases/tag/v1.5.0).
 
-Kotlin 1.5.0 is a [feature release](kotlin-evolution.md#feature-releases-and-incremental-releases) and therefore can
+Kotlin 1.5.0 is a [feature release](kotlin-evolution.md#language-and-tooling-releases) and therefore can
 bring incompatible changes to the language. Find the detailed list of such changes in the [Compatibility Guide for Kotlin 1.5](compatibility-guide-15.md).

docs/topics/whatsnew16.md

@@ -695,5 +695,5 @@ To start a new project with Kotlin 1.6.0, update the Kotlin plugin and run the P
 
 The new command-line compiler is available for download on the [GitHub release page](https://github.com/JetBrains/kotlin/releases/tag/v1.6.0).
 
-Kotlin 1.6.0 is a [feature release](kotlin-evolution.md#feature-releases-and-incremental-releases) and can, therefore, bring changes that are incompatible with your code written for earlier versions of the language.
+Kotlin 1.6.0 is a [feature release](kotlin-evolution.md#language-and-tooling-releases) and can, therefore, bring changes that are incompatible with your code written for earlier versions of the language.
 Find the detailed list of such changes in the [Compatibility Guide for Kotlin 1.6](compatibility-guide-16.md).

docs/topics/whatsnew17.md

@@ -1075,5 +1075,5 @@ project. [Learn how to update to Kotlin 1.7.0](releases.md#update-to-a-new-relea
 
 ### Compatibility guide for Kotlin 1.7.0
 
-Kotlin 1.7.0 is a [feature release](kotlin-evolution.md#feature-releases-and-incremental-releases) and can, therefore, bring changes that are incompatible with your code written for earlier versions of the language.
+Kotlin 1.7.0 is a [feature release](kotlin-evolution.md#language-and-tooling-releases) and can, therefore, bring changes that are incompatible with your code written for earlier versions of the language.
 Find the detailed list of such changes in the [Compatibility guide for Kotlin 1.7.0](compatibility-guide-17.md).

docs/topics/whatsnew18.md

@@ -818,6 +818,6 @@ the upcoming Android Studios updates. The new command-line compiler is available
 
 ## Compatibility guide for Kotlin 1.8.0
 
-Kotlin 1.8.0 is a [feature release](kotlin-evolution.md#feature-releases-and-incremental-releases) and can, therefore,
+Kotlin 1.8.0 is a [feature release](kotlin-evolution.md#language-and-tooling-releases) and can, therefore,
 bring changes that are incompatible with your code written for earlier versions of the language. Find the detailed list
 of these changes in the [Compatibility guide for Kotlin 1.8.0](compatibility-guide-18.md).

docs/topics/whatsnew19.md

@@ -1230,6 +1230,6 @@ If the repository is not specified, Gradle uses the sunset JCenter repository, w
 
 ## Compatibility guide for Kotlin 1.9.0
 
-Kotlin 1.9.0 is a [feature release](kotlin-evolution.md#feature-releases-and-incremental-releases) and can, therefore, 
+Kotlin 1.9.0 is a [feature release](kotlin-evolution.md#language-and-tooling-releases) and can, therefore, 
 bring changes that are incompatible with your code written for earlier versions of the language. Find the detailed list 
 of these changes in the [Compatibility guide for Kotlin 1.9.0](compatibility-guide-19.md).