From 361f074e2beda84bd653a7f1e460d59b902f487a Mon Sep 17 00:00:00 2001 From: Adam <152864218+adam-enko@users.noreply.github.com> Date: Tue, 24 Sep 2024 16:54:55 +0200 Subject: [PATCH] Fix DGPv2 migration helpers (#3822) * Fix DGPv2 migration helpers - Set the DGPv1 tasks to 'other' instead of "" (fix KT-71678) - Configure all DGPv1 tasks, not just `DokkaTask`s. --- .../main/kotlin/internal/v2MigrationUtils.kt | 13 ++- .../kotlin/internal/MigrationHelpersTest.kt | 107 ++++++++++++++++++ .../testFixtures/kotlin/GradleProjectUtils.kt | 6 +- 3 files changed, 119 insertions(+), 7 deletions(-) create mode 100644 dokka-runners/dokka-gradle-plugin/src/test/kotlin/internal/MigrationHelpersTest.kt diff --git a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/internal/v2MigrationUtils.kt b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/internal/v2MigrationUtils.kt index 474ac9e4a8..3e9e601c2d 100644 --- a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/internal/v2MigrationUtils.kt +++ b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/internal/v2MigrationUtils.kt @@ -9,10 +9,7 @@ import org.gradle.api.artifacts.ConfigurationContainer import org.gradle.internal.deprecation.DeprecatableConfiguration import org.gradle.kotlin.dsl.register import org.gradle.kotlin.dsl.withType -import org.jetbrains.dokka.gradle.DokkaCollectorTask -import org.jetbrains.dokka.gradle.DokkaMultiModuleTask -import org.jetbrains.dokka.gradle.DokkaTask -import org.jetbrains.dokka.gradle.DokkaTaskPartial +import org.jetbrains.dokka.gradle.* import org.jetbrains.dokka.gradle.dependencies.DependencyContainerNames /** @@ -36,8 +33,12 @@ internal fun addV2MigrationHelpers( } private fun configureDokkaTaskConventions(project: Project) { - project.tasks.withType().configureEach { - group = "" // hide from users + project.tasks.withType().configureEach { + // The DGPv1 tasks are only present to prevent buildscripts with references to them from breaking. + // The tasks are non-operable and should be hidden, to help nudge users to the DGPv2 tasks. + // Setting tasks with group null will hide it when running `gradle tasks`, + // and put it in the 'other' group in IntelliJ (which effectively hides it). + setGroup(null) onlyIf("Dokka V1 tasks are disabled due to the V2 flag being enabled") { false } enabled = false notCompatibleWithConfigurationCache("Dokka V1 tasks use deprecated Gradle features. Please migrate to Dokka Plugin V2, which fully supports Configuration Cache.") diff --git a/dokka-runners/dokka-gradle-plugin/src/test/kotlin/internal/MigrationHelpersTest.kt b/dokka-runners/dokka-gradle-plugin/src/test/kotlin/internal/MigrationHelpersTest.kt new file mode 100644 index 0000000000..a38bb07425 --- /dev/null +++ b/dokka-runners/dokka-gradle-plugin/src/test/kotlin/internal/MigrationHelpersTest.kt @@ -0,0 +1,107 @@ +/* + * Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. + */ +package org.jetbrains.dokka.gradle.internal + +import io.kotest.core.spec.style.FunSpec +import org.gradle.kotlin.dsl.withType +import org.gradle.testfixtures.ProjectBuilder +import org.jetbrains.dokka.gradle.AbstractDokkaTask +import org.jetbrains.dokka.gradle.utils.enableV2Plugin +import org.jetbrains.dokka.gradle.utils.shouldContainExactly + +class MigrationHelpersTest : FunSpec({ + context("when multi-module project has DGPv2 with migration helpers enabled") { + + val parentProject = ProjectBuilder.builder() + .build() + .enableV2Plugin(v2MigrationHelpers = true) + + val childProject = ProjectBuilder.builder() + .withParent(parentProject) + .build() + .enableV2Plugin() + .enableV2Plugin(v2MigrationHelpers = true) + + parentProject.plugins.apply("org.jetbrains.dokka") + childProject.plugins.apply("org.jetbrains.dokka") + + context("in parent project") { + val parentProjectDokkaTasks = parentProject.tasks.withType() + test("all DGPv1 tasks should have group 'null'") { + val dokkaTasks = parentProjectDokkaTasks.associate { it.name to it.group } + dokkaTasks.shouldContainExactly( + "dokkaGfm" to null, + "dokkaGfmCollector" to null, + "dokkaGfmMultiModule" to null, + + "dokkaHtml" to null, + "dokkaHtmlCollector" to null, + "dokkaHtmlMultiModule" to null, + + "dokkaJavadoc" to null, + "dokkaJavadocCollector" to null, + + "dokkaJekyll" to null, + "dokkaJekyllCollector" to null, + "dokkaJekyllMultiModule" to null, + ) + } + test("all DGPv1 tasks should be disabled") { + val dokkaTasks = parentProjectDokkaTasks.associate { it.name to it.enabled } + dokkaTasks.shouldContainExactly( + "dokkaGfm" to false, + "dokkaGfmCollector" to false, + "dokkaGfmMultiModule" to false, + + "dokkaHtml" to false, + "dokkaHtmlCollector" to false, + "dokkaHtmlMultiModule" to false, + + "dokkaJavadoc" to false, + "dokkaJavadocCollector" to false, + + "dokkaJekyll" to false, + "dokkaJekyllCollector" to false, + "dokkaJekyllMultiModule" to false, + ) + } + } + + context("in child project") { + val childProjectDokkaTasks = childProject.tasks.withType() + test("all DGPv1 tasks should have group 'null'") { + val dokkaTasks = childProjectDokkaTasks.associate { it.name to it.group } + dokkaTasks.shouldContainExactly( + "dokkaGfm" to null, + "dokkaGfmPartial" to null, + + "dokkaHtml" to null, + "dokkaHtmlPartial" to null, + + "dokkaJavadoc" to null, + "dokkaJavadocPartial" to null, + + "dokkaJekyll" to null, + "dokkaJekyllPartial" to null, + ) + } + test("all DGPv1 tasks should be disabled") { + val dokkaTasks = childProjectDokkaTasks.associate { it.name to it.enabled } + dokkaTasks.shouldContainExactly( + "dokkaGfm" to false, + "dokkaGfmPartial" to false, + + "dokkaHtml" to false, + "dokkaHtmlPartial" to false, + + "dokkaJavadoc" to false, + "dokkaJavadocPartial" to false, + + "dokkaJekyll" to false, + "dokkaJekyllPartial" to false, + ) + } + } + } +}) diff --git a/dokka-runners/dokka-gradle-plugin/src/testFixtures/kotlin/GradleProjectUtils.kt b/dokka-runners/dokka-gradle-plugin/src/testFixtures/kotlin/GradleProjectUtils.kt index 3dc5f57710..9e647cab27 100644 --- a/dokka-runners/dokka-gradle-plugin/src/testFixtures/kotlin/GradleProjectUtils.kt +++ b/dokka-runners/dokka-gradle-plugin/src/testFixtures/kotlin/GradleProjectUtils.kt @@ -6,9 +6,13 @@ package org.jetbrains.dokka.gradle.utils import org.gradle.api.Project fun Project.enableV2Plugin( + v2MigrationHelpers: Boolean = true, suppressV2Message: Boolean = true ): Project { - extensions.extraProperties.set("org.jetbrains.dokka.experimental.gradle.pluginMode", "V2Enabled") + extensions.extraProperties.set( + "org.jetbrains.dokka.experimental.gradle.pluginMode", + if (v2MigrationHelpers) "V2EnabledWithHelpers" else "V2Enabled", + ) extensions.extraProperties.set("org.jetbrains.dokka.experimental.gradle.pluginMode.noWarn", suppressV2Message) return this }