Merge branch 'master' into vmishenev/update-analysis-api-to-2.0.20-de…

…v-3206
Kotlin · May 14, 2024 · 6a2f7e2 · 6a2f7e2
2 parents bfab90a + 2a1f2b8
commit 6a2f7e2
Show file tree

Hide file tree

Showing 28 changed files with 115 additions and 94 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -105,6 +105,17 @@ However, if you need to run all integration tests locally, you can use the `inte
 If you need to run a specific test locally, you can run it from your IDE or by calling the corresponding Gradle
 task (for example, `:dokka-integration-tests:gradle:testExternalProjectKotlinxCoroutines`).
 
+It's possible to run integration tests with a custom Dokka version published to
+[MavenCentral](https://central.sonatype.com),
+[dev](https://maven.pkg.jetbrains.space/kotlin/p/dokka/dev),
+[test](https://maven.pkg.jetbrains.space/kotlin/p/dokka/test) or
+`mavenLocal` 
+via `org.jetbrains.dokka.integration_test.dokkaVersionOverride` Gradle property:
+
+```bash
+./gradlew :dokka-integration-tests:gradle:testExternalProjectKotlinxCoroutines -Porg.jetbrains.dokka.integration_test.dokkaVersionOverride=2.0.0-dev-329
+```
+
 ## Infrastructure
 
 ### Java version

diff --git a/build-logic/src/main/kotlin/dokkabuild/DokkaBuildProperties.kt b/build-logic/src/main/kotlin/dokkabuild/DokkaBuildProperties.kt
@@ -81,6 +81,10 @@ abstract class DokkaBuildProperties @Inject constructor(
         dokkaProperty("integration_test.useK2", String::toBoolean)
             .orElse(false)
 
+    /** Allows running integration tests with a custom Dokka version */
+    val integrationTestDokkaVersionOverride: Provider<String> =
+        dokkaProperty("integration_test.dokkaVersionOverride") { it }
+
     val androidSdkDir: Provider<File> =
         providers
             // first try finding a local.properties file in any parent directory

diff --git a/dokka-integration-tests/gradle/build.gradle.kts b/dokka-integration-tests/gradle/build.gradle.kts
@@ -94,13 +94,15 @@ tasks.withType<Test>().configureEach {
     }
 
     // environment() isn't Provider API compatible yet https://github.com/gradle/gradle/issues/11534
-    dokkaBuild.integrationTestExhaustive.orNull?.let { exhaustive ->
-        environment("isExhaustive", exhaustive)
-    }
-    dokkaBuild.androidSdkDir.orNull?.let { androidSdkDir ->
-        environment("ANDROID_HOME", androidSdkDir.invariantSeparatorsPath)
+    fun environmentProvider(name: String, provider: Provider<out Any>) {
+        inputs.property(name, provider).optional(true)
+        provider.orNull?.let { environment(name, it) }
     }
 
+    environmentProvider("DOKKA_VERSION_OVERRIDE", dokkaBuild.integrationTestDokkaVersionOverride)
+    environmentProvider("isExhaustive", dokkaBuild.integrationTestExhaustive)
+    environmentProvider("ANDROID_HOME", dokkaBuild.androidSdkDir.map { it.invariantSeparatorsPath })
+
     testLogging {
         exceptionFormat = FULL
         events(SKIPPED, FAILED)

diff --git a/dokka-integration-tests/gradle/projects/coroutines/coroutines.diff b/dokka-integration-tests/gradle/projects/coroutines/coroutines.diff
@@ -6,7 +6,7 @@ index e7d405e12..db5dcec66 100644
      }
 
      repositories {
-+        /* %{PROJECT_LOCAL_MAVEN_DIR}% */
++        /* %{DOKKA_IT_MAVEN_REPO}% */
          mavenCentral()
          maven { url "https://plugins.gradle.org/m2/" }
          CommunityProjectsBuild.addDevRepositoryIfEnabled(delegate, project)
@@ -54,7 +54,7 @@ index e7d405e12..db5dcec66 100644
  // Configure repositories
  allprojects {
      repositories {
-+        /* %{PROJECT_LOCAL_MAVEN_DIR}% */
++        /* %{DOKKA_IT_MAVEN_REPO}% */
          /*
           * google should be first in the repository list because some of the play services
           * transitive dependencies was removed from jcenter, thus breaking gradle dependency resolution
@@ -80,7 +80,7 @@ index ae54ad0f6..00963f5b2 100644
  val kotlinDevUrl = project.rootProject.properties["kotlin_repo_url"] as? String
 
  repositories {
-+    /* %{PROJECT_LOCAL_MAVEN_DIR}% */
++    /* %{DOKKA_IT_MAVEN_REPO}% */
      mavenCentral()
      if (cacheRedirectorEnabled) {
          maven("https://cache-redirector.jetbrains.com/plugins.gradle.org/m2")
@@ -120,7 +120,7 @@ index c2e859f65..9cc749a1f 100644
  pluginManagement {
      val build_snapshot_train: String? by settings
      repositories {
-+        /* %{PROJECT_LOCAL_MAVEN_DIR}% */
++        /* %{DOKKA_IT_MAVEN_REPO}% */
          val cacheRedirectorEnabled = System.getenv("CACHE_REDIRECTOR")?.toBoolean() == true
          if (cacheRedirectorEnabled) {
              println("Redirecting repositories for buildSrc buildscript")
@@ -177,7 +177,7 @@ index 151c087fd..e4433c24f 100644
 
      repositories {
 -        maven { url "https://maven.pkg.jetbrains.space/kotlin/p/dokka/dev/" }
-+        /* %{PROJECT_LOCAL_MAVEN_DIR}% */
++        /* %{DOKKA_IT_MAVEN_REPO}% */
 +        //maven { url "https://maven.pkg.jetbrains.space/kotlin/p/dokka/dev/" }
          gradlePluginPortal()
      }

diff --git a/dokka-integration-tests/gradle/projects/it-android-0/gradle.properties b/dokka-integration-tests/gradle/projects/it-android-0/gradle.properties
@@ -2,6 +2,6 @@
 # Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
 #
 
-dokka_it_kotlin_version=2.0.0-RC1
+dokka_it_kotlin_version=2.0.0-RC3
 dokka_it_android_gradle_plugin_version=4.2.2
 android.useAndroidX=true
diff --git a/dokka-integration-tests/gradle/projects/it-basic-groovy/gradle.properties b/dokka-integration-tests/gradle/projects/it-basic-groovy/gradle.properties
@@ -2,4 +2,4 @@
 # Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
 #
 
-dokka_it_kotlin_version=2.0.0-RC1
+dokka_it_kotlin_version=2.0.0-RC3
diff --git a/dokka-integration-tests/gradle/projects/it-basic/gradle.properties b/dokka-integration-tests/gradle/projects/it-basic/gradle.properties
@@ -2,4 +2,4 @@
 # Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
 #
 
-dokka_it_kotlin_version=2.0.0-RC1
+dokka_it_kotlin_version=2.0.0-RC3
diff --git a/dokka-integration-tests/gradle/projects/it-collector-0/gradle.properties b/dokka-integration-tests/gradle/projects/it-collector-0/gradle.properties
@@ -2,4 +2,4 @@
 # Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
 #
 
-dokka_it_kotlin_version=2.0.0-RC1
+dokka_it_kotlin_version=2.0.0-RC3
diff --git a/dokka-integration-tests/gradle/projects/it-configuration/gradle.properties b/dokka-integration-tests/gradle/projects/it-configuration/gradle.properties
@@ -2,6 +2,6 @@
 # Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
 #
 
-dokka_it_kotlin_version=2.0.0-RC1
+dokka_it_kotlin_version=2.0.0-RC3
 fail_on_warning=false
 report_undocumented=false
diff --git a/dokka-integration-tests/gradle/projects/it-js-ir-0/gradle.properties b/dokka-integration-tests/gradle/projects/it-js-ir-0/gradle.properties
@@ -2,5 +2,5 @@
 # Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
 #
 
-dokka_it_kotlin_version=2.0.0-RC1
+dokka_it_kotlin_version=2.0.0-RC3
 react_version=18.2.0-pre.467
diff --git a/dokka-integration-tests/gradle/projects/it-multimodule-0/gradle.properties b/dokka-integration-tests/gradle/projects/it-multimodule-0/gradle.properties
@@ -2,4 +2,4 @@
 # Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
 #
 
-dokka_it_kotlin_version=2.0.0-RC1
+dokka_it_kotlin_version=2.0.0-RC3
diff --git a/dokka-integration-tests/gradle/projects/it-multimodule-1/gradle.properties b/dokka-integration-tests/gradle/projects/it-multimodule-1/gradle.properties
@@ -2,4 +2,4 @@
 # Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
 #
 
-dokka_it_kotlin_version=2.0.0-RC1
+dokka_it_kotlin_version=2.0.0-RC3
diff --git a/dokka-integration-tests/gradle/projects/it-multimodule-inter-module-links/gradle.properties b/dokka-integration-tests/gradle/projects/it-multimodule-inter-module-links/gradle.properties
@@ -2,4 +2,4 @@
 # Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
 #
 
-dokka_it_kotlin_version=1.9.20
+dokka_it_kotlin_version=2.0.0-RC3
diff --git a/dokka-integration-tests/gradle/projects/it-multimodule-versioning-0/gradle.properties b/dokka-integration-tests/gradle/projects/it-multimodule-versioning-0/gradle.properties
@@ -2,5 +2,5 @@
 # Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
 #
 
-dokka_it_kotlin_version=2.0.0-RC1
+dokka_it_kotlin_version=2.0.0-RC3
 
diff --git a/dokka-integration-tests/gradle/projects/it-multiplatform-0/gradle.properties b/dokka-integration-tests/gradle/projects/it-multiplatform-0/gradle.properties
@@ -2,4 +2,4 @@
 # Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
 #
 
-dokka_it_kotlin_version=2.0.0-RC1
+dokka_it_kotlin_version=2.0.0-RC3
diff --git a/...-integration-tests/gradle/projects/it-sequential-tasks-execution-stress/gradle.properties b/...-integration-tests/gradle/projects/it-sequential-tasks-execution-stress/gradle.properties
@@ -2,5 +2,5 @@
 # Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
 #
 
-dokka_it_kotlin_version=2.0.0-RC1
+dokka_it_kotlin_version=2.0.0-RC3
 task_number=100
diff --git a/dokka-integration-tests/gradle/projects/it-wasm-js-wasi-basic/gradle.properties b/dokka-integration-tests/gradle/projects/it-wasm-js-wasi-basic/gradle.properties
@@ -2,4 +2,4 @@
 # Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
 #
 
-dokka_it_kotlin_version=2.0.0-RC1
+dokka_it_kotlin_version=2.0.0-RC3
diff --git a/dokka-integration-tests/gradle/projects/serialization/serialization.diff b/dokka-integration-tests/gradle/projects/serialization/serialization.diff
@@ -7,7 +7,7 @@ index 73b566ae..e2af43bd 100644
 
      repositories {
 -        maven { url 'https://maven.pkg.jetbrains.space/kotlin/p/dokka/dev' }
-+        /* %{PROJECT_LOCAL_MAVEN_DIR}% */
++        /* %{DOKKA_IT_MAVEN_REPO}% */
 +        //maven { url 'https://maven.pkg.jetbrains.space/kotlin/p/dokka/dev' }
          // kotlin-dev with space redirector
          maven { url "https://cache-redirector.jetbrains.com/maven.pkg.jetbrains.space/kotlin/p/kotlin/dev" }
@@ -61,7 +61,7 @@ index 73b566ae..e2af43bd 100644
          // Snapshot-specific
          repositories {
 -            mavenLocal()
-+            /* %{PROJECT_LOCAL_MAVEN_DIR}% */
++            /* %{DOKKA_IT_MAVEN_REPO}% */
 +            //mavenLocal()
              maven { url "https://oss.sonatype.org/content/repositories/snapshots" }
          }
@@ -70,7 +70,7 @@ index 73b566ae..e2af43bd 100644
      }
 
      repositories {
-+        /* %{PROJECT_LOCAL_MAVEN_DIR}% */
++        /* %{DOKKA_IT_MAVEN_REPO}% */
          mavenCentral()
 -        maven { url 'https://maven.pkg.jetbrains.space/kotlin/p/dokka/dev' }
 +        //maven { url 'https://maven.pkg.jetbrains.space/kotlin/p/dokka/dev' }
@@ -92,7 +92,7 @@ index c999bcd2..98afdae7 100644
  }
 
  repositories {
-+    /* %{PROJECT_LOCAL_MAVEN_DIR}% */
++    /* %{DOKKA_IT_MAVEN_REPO}% */
      mavenCentral()
 -    mavenLocal()
 +    //mavenLocal()
@@ -143,7 +143,7 @@ index dda68347..119c321a 100644
 
      repositories {
 -        mavenLocal()
-+        /* %{PROJECT_LOCAL_MAVEN_DIR}% */
++        /* %{DOKKA_IT_MAVEN_REPO}% */
 +        //mavenLocal()
          mavenCentral()
          maven { url "https://cache-redirector.jetbrains.com/maven.pkg.jetbrains.space/kotlin/p/kotlin/dev" }
@@ -153,7 +153,7 @@ index dda68347..119c321a 100644
 
  repositories {
 -    mavenLocal()
-+    /* %{PROJECT_LOCAL_MAVEN_DIR}% */
++    /* %{DOKKA_IT_MAVEN_REPO}% */
 +    //mavenLocal()
      mavenCentral()
      maven { url "https://cache-redirector.jetbrains.com/maven.pkg.jetbrains.space/kotlin/p/kotlin/dev" }
@@ -166,7 +166,7 @@ index f8cb2d87..beebf995 100644
      }
 
      repositories {
-+        /* %{PROJECT_LOCAL_MAVEN_DIR}% */
++        /* %{DOKKA_IT_MAVEN_REPO}% */
          mavenCentral()
          maven { url 'https://plugins.gradle.org/m2/' }
          maven { url "https://cache-redirector.jetbrains.com/maven.pkg.jetbrains.space/kotlin/p/kotlin/dev" }

diff --git a/dokka-integration-tests/gradle/projects/template.settings.gradle.kts b/dokka-integration-tests/gradle/projects/template.settings.gradle.kts
@@ -36,7 +36,7 @@ pluginManagement {
         }
     }
     repositories {
-        /* %{PROJECT_LOCAL_MAVEN_DIR}% */
+        /* %{DOKKA_IT_MAVEN_REPO}% */
         mavenCentral()
         gradlePluginPortal()
         google()
@@ -47,7 +47,7 @@ pluginManagement {
 dependencyResolutionManagement {
     repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)
     repositories {
-        /* %{PROJECT_LOCAL_MAVEN_DIR}% */
+        /* %{DOKKA_IT_MAVEN_REPO}% */
         mavenCentral()
         google()
         maven("https://maven.pkg.jetbrains.space/public/p/kotlinx-html/maven") {

diff --git a/dokka-integration-tests/gradle/projects/ui-showcase/README.md b/dokka-integration-tests/gradle/projects/ui-showcase/README.md
@@ -5,9 +5,22 @@ This is a Dokka test project for UI e2e tests.
 The goal is to have as much variety of UI elements in one project as possible, so that during refactorings
 we can compare the outputs between different versions of Dokka and make sure we didn't break any corner cases.
 
-### Run from root of the project
+### Run from the root of the project
 
 ```bash
 export DOKKA_TEST_OUTPUT_PATH="build/ui-showcase-result"
 ./gradlew :dokka-integration-tests:gradle:testUiShowcaseProject
 ```
+
+### Run with the published Dokka version
+
+Dokka should be published in one of the following repositories:
+[MavenCentral](https://central.sonatype.com),
+[dev](https://maven.pkg.jetbrains.space/kotlin/p/dokka/dev),
+[test](https://maven.pkg.jetbrains.space/kotlin/p/dokka/test) or
+`mavenLocal`
+
+```bash
+export DOKKA_TEST_OUTPUT_PATH="build/ui-showcase-result"
+./gradlew :dokka-integration-tests:gradle:testUiShowcaseProject -Porg.jetbrains.dokka.integration_test.dokkaVersionOverride=2.0.0-dev-329
+```
diff --git a/...sts/gradle/src/main/kotlin/org/jetbrains/dokka/it/gradle/AbstractGradleIntegrationTest.kt b/...sts/gradle/src/main/kotlin/org/jetbrains/dokka/it/gradle/AbstractGradleIntegrationTest.kt
@@ -67,7 +67,7 @@ abstract class AbstractGradleIntegrationTest : AbstractIntegrationTest() {
             .withDebug(TestEnvironment.isEnabledDebug)
             .withArguments(
                 listOfNotNull(
-                    "-Pdokka_it_dokka_version=${System.getenv("DOKKA_VERSION")}",
+                    "-Pdokka_it_dokka_version=${dokkaVersion}",
                     "-Pdokka_it_kotlin_version=${buildVersions.kotlinVersion}",
                     buildVersions.androidGradlePluginVersion?.let { androidVersion ->
                         "-Pdokka_it_android_gradle_plugin_version=$androidVersion"
@@ -103,6 +103,9 @@ abstract class AbstractGradleIntegrationTest : AbstractIntegrationTest() {
     }
 
     companion object {
+        private val dokkaVersionOverride: String? = System.getenv("DOKKA_VERSION_OVERRIDE")
+        private val dokkaVersion: String = dokkaVersionOverride ?: System.getenv("DOKKA_VERSION")
+
         /**
          * Location of the template project that will be copied into [AbstractIntegrationTest.projectDir].
          *
@@ -120,12 +123,24 @@ abstract class AbstractGradleIntegrationTest : AbstractIntegrationTest() {
         val templateSettingsGradleKts: Path by systemProperty(Paths::get)
 
         /** file-based Maven repositories with Dokka dependencies */
-        private val devMavenRepositories: String by systemProperty { repos ->
-            val repoPaths = repos.split(",").map { Paths.get(it) }
+        private val devMavenRepositories: List<Path> by systemProperty { repos ->
+            repos.split(",").map { Paths.get(it) }
+        }
 
-            val reposSpecs = repoPaths
-                .withIndex()
-                .joinToString(",\n") { (i, repoPath) ->
+        private val mavenRepositories: String by lazy {
+            val reposSpecs = if (dokkaVersionOverride != null) {
+                println("Dokka version overridden with $dokkaVersionOverride")
+                // if `DOKKA_VERSION_OVERRIDE` environment variable is provided,
+                //  we allow running tests on a custom Dokka version from specific repositories
+                """
+                maven("https://maven.pkg.jetbrains.space/kotlin/p/dokka/test"),
+                maven("https://maven.pkg.jetbrains.space/kotlin/p/dokka/dev"),
+                mavenCentral(),
+                mavenLocal()
+                """.trimIndent()
+            } else {
+                // otherwise - use locally published versions via `devMavenPublish`
+                devMavenRepositories.withIndex().joinToString(",\n") { (i, repoPath) ->
                     // Exclusive repository containing local Dokka artifacts.
                     // Must be compatible with both Groovy and Kotlin DSL.
                     /* language=kts */
@@ -136,6 +151,7 @@ abstract class AbstractGradleIntegrationTest : AbstractIntegrationTest() {
                     |}
                     """.trimMargin()
                 }
+            }
 
             /* language=kts */
             """
@@ -153,17 +169,17 @@ abstract class AbstractGradleIntegrationTest : AbstractIntegrationTest() {
 
         fun File.updateProjectLocalMavenDir() {
 
-            val dokkaDevMavenRepoMarker = "/* %{PROJECT_LOCAL_MAVEN_DIR}% */"
+            val dokkaMavenRepoMarker = "/* %{DOKKA_IT_MAVEN_REPO}% */"
 
             // Exclusive repository containing local Dokka artifacts.
             // Must be compatible with both Groovy and Kotlin DSL.
 
             walk().filter { it.isFile }.forEach { file ->
                 val fileText = file.readText()
 
-                if (dokkaDevMavenRepoMarker in fileText) {
+                if (dokkaMavenRepoMarker in fileText) {
                     file.writeText(
-                        fileText.replace(dokkaDevMavenRepoMarker, devMavenRepositories)
+                        fileText.replace(dokkaMavenRepoMarker, mavenRepositories)
                     )
                 }
             }

diff --git a/...-integration-tests/gradle/src/main/kotlin/org/jetbrains/dokka/it/gradle/TestedVersions.kt b/...-integration-tests/gradle/src/main/kotlin/org/jetbrains/dokka/it/gradle/TestedVersions.kt
@@ -14,7 +14,7 @@ open class AllSupportedTestedVersionsArgumentsProvider : TestedVersionsArguments
 
 object TestedVersions {
 
-    val LATEST = BuildVersions("8.7", "2.0.0-RC1")
+    val LATEST = BuildVersions("8.7", "2.0.0-RC3")
 
     /**
      * All supported Gradle/Kotlin versions, including [LATEST]
@@ -41,7 +41,7 @@ object TestedVersions {
     val ANDROID =
         BuildVersions.permutations(
             gradleVersions = listOf("8.4"),
-            kotlinVersions = listOf("2.0.0-RC1"),
+            kotlinVersions = listOf("2.0.0-RC3"),
             androidGradlePluginVersions = listOf("8.3.0")
         ) + BuildVersions.permutations(
             gradleVersions = listOf("7.4.2", *ifExhaustive("7.0")),
@@ -66,7 +66,7 @@ object TestedVersions {
         "1.9.0" to "18.2.0-pre.597",
         "1.9.10" to "18.2.0-pre.597",
         "1.9.23" to "18.2.0-pre.682",
-        "2.0.0-RC1" to "18.2.0-pre.726",
+        "2.0.0-RC3" to "18.2.0-pre.726",
     )
 }
 

diff --git a/dokka-integration-tests/maven/projects/it-maven/pom.xml b/dokka-integration-tests/maven/projects/it-maven/pom.xml
@@ -11,7 +11,7 @@
     <version>1.0-SNAPSHOT</version>
 
     <properties>
-        <kotlin.version>2.0.0-RC1</kotlin.version>
+        <kotlin.version>2.0.0-RC3</kotlin.version>
     </properties>
     <build>
         <plugins>