android_studio.md: generate Android Studio releases list (#676)

android_studio.md: generate Android Studio releases list

.github/scripts/android_studio_releases.main.kts

@@ -0,0 +1,78 @@
+#!/usr/bin/env kotlin
+
+/**
+ * This script is used to update the Android Studio releases page.
+ * At first, it fetches the list of Android Studio updates from the official `updates.xml` file.
+ * Parsed list is used to generate the Markdown table.
+ * The actual IntelliJ IDEA release version is obtained with the help of the JetBrains Data Services API.
+ */
+@file:DependsOn("org.simpleframework:simple-xml:2.7.1")
+@file:DependsOn("org.json:json:20211205")
+
+import org.json.JSONObject
+import org.simpleframework.xml.Attribute
+import org.simpleframework.xml.ElementList
+import org.simpleframework.xml.Path
+import org.simpleframework.xml.Root
+import org.simpleframework.xml.core.Persister
+import java.io.File
+import java.net.URL
+
+val DATA_SERVICES_RELEASES_URL = "https://data.services.jetbrains.com/products/releases"
+val ANDROID_STUDIO_RELEASES_URL = "https://dl.google.com/android/studio/patches/updates.xml"
+val RELEASES_FILE_PATH = "topics/_generated/android_studio_releases.md"
+
+fun resolveMarketingRelease(build: String) = URL("$DATA_SERVICES_RELEASES_URL?code=IC&build=$build").openStream().use {
+  it.readBytes().toString(Charsets.UTF_8).let { content ->
+    (JSONObject(content).getJSONArray("IIC").first() as JSONObject).getString("version")
+  }
+}
+
+URL(ANDROID_STUDIO_RELEASES_URL).openStream().use { inputStream ->
+  inputStream.reader().run {
+    Persister().read(ProductsReleases::class.java, readText())
+  }.run {
+    """
+    | Android Studio | Channel | Build Number | IntelliJ IDEA Build Number | IntelliJ IDEA Release |
+    |----------------|---------|--------------|----------------------------|-----------------------|
+
+    """.trimIndent() + channels.distinctBy { it.number }.joinToString("\n") {
+      val name = it.version.replace('|', '-')
+      val channel = it.status
+      val number = it.number.split('-').last()
+      val ijBuild = it.apiVersion.split('-').last()
+      val ijRelease = ijBuild.let(::resolveMarketingRelease)
+
+      "| $name | $channel | $number | $ijBuild | $ijRelease |"
+    }
+  }.let {
+    "<chunk id=\"releases_table\">\n\n$it\n\n</chunk>"
+  }.let {
+    File(System.getenv("GITHUB_WORKSPACE")).resolve(RELEASES_FILE_PATH).writeText(it)
+  }
+}
+
+@Root(name = "products", strict = false)
+data class ProductsReleases(
+        @field:ElementList(name = "channel", inline = true)
+        @field:Path("product")
+        var channels: List<Channel> = mutableListOf()
+)
+
+@Root(strict = false)
+data class Channel(
+        @field:Attribute
+        var status: String = "",
+
+        @field:Path("build")
+        @field:Attribute
+        var apiVersion: String = "",
+
+        @field:Path("build")
+        @field:Attribute
+        var number: String = "",
+
+        @field:Path("build")
+        @field:Attribute
+        var version: String = "",
+)

.github/workflows/generate-android-studio-releases.yml

@@ -0,0 +1,18 @@
+name: Generate Android Studio releases
+
+on:
+  schedule:
+    - cron: "1 1 * * *"
+
+jobs:
+  example-action:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Generate
+        run: .github/workflows/generate-android-studio-releases.sh
+      - name: Commit changes
+        uses: Endbug/add-and-commit@v8
+        with:
+          message: 'Generate Android Studio releases'
+          add: 'android_studio_releases.md'

topics/_generated/android_studio_releases.md

@@ -0,0 +1,9 @@
+<chunk id="releases_table">
+
+| Android Studio | Channel | Build Number | IntelliJ IDEA Build Number | IntelliJ IDEA Release |
+|----------------|---------|--------------|----------------------------|-----------------------|
+| Dolphin - 2021.3.1 Canary 3 | eap | 213.6777.52.2113.8172706 | 213.6777.52 | 2021.3.2 |
+| Chipmunk - 2021.2.1 Beta 2 | beta | 212.5712.43.2112.8125332 | 212.5712.43 | 2021.2.4 |
+| Bumblebee - 2021.1.1 Patch 2 | release | 211.7628.21.2111.8193401 | 211.7628.21 | 2021.1.3 |
+
+</chunk>

topics/products/android_studio.md

@@ -20,13 +20,25 @@ Some minor modifications to the skeleton project are needed, as discussed below.
 For API compatibility, it is essential to match the version of the IntelliJ Platform APIs used for plugin development with the target version of Android Studio.
 The version number of Android Studio contains the version of the underlying IntelliJ Platform APIs that were used to build it.
 
+The actual Android Studio version doesn't entirely reflect the (YEAR.MAJOR.MINOR) version of the IntelliJ Platform.
+The Android Studio version presented below is `2021.1.1 Patch 1`, but the `2021.1` part marked with the green rectangle refers to the IntelliJ IDEA release.
+
 To find the version of the IntelliJ Platform used to build Android Studio, use the Android Studio _About_ dialog screen.
 An example is shown below.
-In this case, the (BRANCH.BUILD.FIX) version of the IntelliJ Platform is `191.8026.42`, which corresponds to the IntelliJ IDEA version 2019.1.4.
+In this case, the (BRANCH.BUILD.FIX) version of the IntelliJ Platform is `211.7628.21` – marked with the blue rectangle – is corresponding to the IntelliJ IDEA version `2021.1.3`.
+
+In your Gradle build script, you should set both versions – build number and the release number – to the `intellij.version` property.
+To figure out the exact release number based on the build number, visit the [IntelliJ Repository Releases](https://www.jetbrains.com/intellij-repository/releases/) listing and check the `com.jetbrains.intellij.idea` section.
+
 The [build.gradle configuration steps](#configuring-the-plugin-buildgradle-file) section below explains how to set the IntelliJ Platform version to match the target version of Android Studio.
 
 ![Example Android Studio About Dialog](android_studio_build.png){width="600"}
 
+### Android Studio Releases Listing
+Below you may find a list of Android Studio releases mapped to the relevant IntelliJ IDEA versions:
+
+<include src="android_studio_releases.md" include-id="releases_table"></include>
+
 ### Configuring the Plugin build.gradle File
 The use-case of developing for a non-IntelliJ IDEA IDE is reviewed in the [Plugins Targeting Alternate IntelliJ Platform-Based IDEs](gradle_guide.md#plugins-targeting-alternate-intellij-platform-based-ides) section of the [Configuring Gradle for IntelliJ Platform Plugins](gradle_guide.md) page.
 The particular example in that section discusses configuring a plugin project for PhpStorm, so the details for an Android Studio plugin project are reviewed here.
@@ -36,7 +48,7 @@ Here are the steps to configure the <path>build.gradle</path> file for developin
   Continuing with the example [above](#matching-versions-of-the-intellij-platform-with-the-android-studio-version), set the `intellij.version` value to `191.8026.42`.
   Alternatively, specify `intellij.localPath` to refer to a local installation of Android Studio.
 * Android Studio plugin projects that use APIs from the `android` plugin must declare a dependency on that plugin.
- Declare the dependency in <path>build.gradle</path> using the Gradle plugin `intellij.plugins` attribute, which in this case lists the [directory name](https://github.com/JetBrains/gradle-intellij-plugin#intellij-platform-properties) of the plugin.
+  Declare the dependency in <path>build.gradle</path> using the Gradle plugin `intellij.plugins` attribute, which in this case lists the [directory name](https://github.com/JetBrains/gradle-intellij-plugin#intellij-platform-properties) of the plugin.
 * The best practice is to use the target version of Android Studio as the IDE Development Instance.
   Set the Development Instance to the (user-specific) absolute path to the target Android Studio application.