Update Kotlinx Coroutines tested version

build-logic/src/main/kotlin/dokkabuild/tasks/GitCheckoutTask.kt

@@ -13,11 +13,14 @@ import org.eclipse.jgit.util.FS
 import org.gradle.api.DefaultTask
 import org.gradle.api.file.DirectoryProperty
 import org.gradle.api.file.FileSystemOperations
-import org.gradle.api.provider.Property
+import org.gradle.api.logging.Logging
+import org.gradle.api.provider.*
 import org.gradle.api.tasks.CacheableTask
 import org.gradle.api.tasks.Input
 import org.gradle.api.tasks.OutputDirectory
 import org.gradle.api.tasks.TaskAction
+import org.gradle.kotlin.dsl.assign
+import org.gradle.kotlin.dsl.of
 import java.io.File
 import javax.inject.Inject
 
@@ -26,7 +29,8 @@ import javax.inject.Inject
  */
 @CacheableTask
 abstract class GitCheckoutTask @Inject constructor(
-    private val fs: FileSystemOperations
+    private val fs: FileSystemOperations,
+    private val providers: ProviderFactory,
 ) : DefaultTask() {
 
     @get:OutputDirectory
@@ -40,6 +44,13 @@ abstract class GitCheckoutTask @Inject constructor(
     @get:Input
     abstract val commitId: Property<String>
 
+    init {
+        outputs.upToDateWhen { task ->
+            require(task is GitCheckoutTask)
+            task.gitRepoIsUpToDate().get()
+        }
+    }
+
     private val localRepoDir: File
         get() = temporaryDir.resolve("repo")
 
@@ -121,4 +132,55 @@ abstract class GitCheckoutTask @Inject constructor(
                 .call()
         }
     }
+
+    private fun gitRepoIsUpToDate(): Provider<Boolean> =
+        providers.of(GitRepoIsUpToDate::class) {
+            parameters.repoDir = localRepoDir
+        }
+
+    /**
+     * Determine if [repoDir][GitRepoIsUpToDate.Params.repoDir] is a valid Git repo,
+     * and it does not require cleaning.
+     */
+    internal abstract class GitRepoIsUpToDate : ValueSource<Boolean, GitRepoIsUpToDate.Params> {
+        interface Params : ValueSourceParameters {
+            val repoDir: DirectoryProperty
+        }
+
+        private val repoDir: File get() = parameters.repoDir.get().asFile
+
+        private val logger = Logging.getLogger(GitRepoIsUpToDate::class.java)
+        private fun log(msg: String): Unit = logger.info("[GitRepoIsUpToDate] $msg (repoDir=$repoDir)")
+
+
+        override fun obtain(): Boolean {
+            val gitRepoInitialized = RepositoryCache.FileKey.isGitRepository(repoDir, FS.DETECTED)
+
+            if (!gitRepoInitialized) {
+                logger.info("repo is either not cloned or is not recognizable as a git repo")
+                return false
+            }
+
+            Git.open(repoDir).use { git ->
+                val status = git.status().call()
+                return when {
+                    status.hasUncommittedChanges() -> {
+                        log("repo has ${status.uncommittedChanges.size} uncommited changes")
+                        false
+                    }
+
+                    status.hasUncommittedChanges() -> {
+                        log("repo has ${status.untracked.size} untracked changes")
+                        false
+                    }
+
+                    else -> {
+                        log("repo is up-to-date")
+                        true
+                    }
+                }
+            }
+
+        }
+    }
 }

dokka-integration-tests/README.md

@@ -36,18 +36,41 @@ Here's how to update an external project:
         destination = templateProjectsDir.dir("serialization/kotlinx-serialization")
     }
     ```
-   Note that the Gradle task will clone the repo into a `build/tmp` directory
-   before copying it to a subdirectory inside `projects/`
+3. Run the Gradle task
 
-3. Manually write the diff (or apply the existing one and tweak) to have the project buildable against locally published Dokka of version `for-integration-tests-SNAPSHOT`
+   ```shell
+   ./gradlew :dokka-integration-tests:gradle:checkoutKotlinxSerialization
+   ```
+
+4. The `GitCheckoutTask` task will first clone the repo into a `build/tmp` directory.
+   Open this directory in an IDE, and edit the project to be testable.
 
-   A git patch can be exported with:
    ```shell
-   git diff > $pathToProjectInDokka/project.diff
+   # open with IntelliJ IDEA
+   idea ./gradle/build/tmp/checkoutKotlinxSerialization/repo
    ```
 
-4. Check that the corresponding `GradleIntegrationTest` passes locally and push
+   - Remove `mavenLocal()` repositories.
+   - Add `/* %{DOKKA_IT_MAVEN_REPO}% */` to the top of `repositories {}` blocks.
+   - Update Dokka version.
+     ```diff
+     - classpath "org.jetbrains.dokka:dokka-gradle-plugin:$dokka_version"
+     + classpath "org.jetbrains.dokka:dokka-gradle-plugin:${providers.gradleProperty("dokka_it_dokka_version").get()}"
+     ```
 
+   ⚠️ `GitCheckoutTask` will delete any changes, so make sure not to run it again while you're editing.
+5. Once you're happy, export a git patch.
+   ```shell
+   cd ./gradle/build/tmp/checkoutKotlinxSerialization/repo;
+   git diff > updated.diff
+   ```
+   Update the patch in the [projects](./gradle/projects/) directory,
+   e.g. [`dokka-integration-tests/gradle/projects/serialization/serialization.diff`](./gradle/projects/serialization/serialization.diff).
+6. Run the corresponding test task.
+   ```shell
+   ./gradlew :dokka-integration-tests:gradle:testExternalProjectKotlinxSerialization
+   ```
+7. Once the test works, commit and push.
 
 ### Run integration tests with K2 (symbols)
 

dokka-integration-tests/gradle/build.gradle.kts

@@ -164,7 +164,7 @@ fun registerTestProjectSuite(
 
 val checkoutKotlinxCoroutines by tasks.registering(GitCheckoutTask::class) {
     uri = "https://github.com/Kotlin/kotlinx.coroutines.git"
-    commitId = "b78bbf518bd8e90e9ed2133ebdacc36441210cd6"
+    commitId = "1bffe67a32d9d0285320f5b23fa94bc2b5f2b92e"
     destination = templateProjectsDir.dir("coroutines/kotlinx-coroutines")
 }