Skip to content

Commit

Permalink
Update DGP opt-in warnings and messages
Browse files Browse the repository at this point in the history
  • Loading branch information
@adam-enko
adam-enko committed Sep 19, 2024
1 parent e6ac5b8 commit f95679a
Show file tree
Hide file tree
Showing 3 changed files with 192 additions and 159 deletions.
87 changes: 33 additions & 54 deletions dokka-runners/dokka-gradle-plugin/src/main/kotlin/internal/PluginFeaturesService.kt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -78,44 +78,43 @@ internal abstract class PluginFeaturesService : BuildService<PluginFeaturesServi

private fun logV1PluginMessage() {
if (primaryService) {
logger.warn(
logger.warn("warning: Dokka Gradle Plugin V1 mode is deprecated")
logger.lifecycle(
"""
|⚠ Warning: Dokka Gradle Plugin V1 mode is enabled
|
| V1 mode is deprecated, and will be removed in Dokka version 2.1.0
|Dokka Gradle Plugin V1 mode is deprecated, and will be removed in Dokka version 2.1.0
|
| Please migrate Dokka Gradle Plugin to V2. This will require updating your project.
| To get started check out the Dokka Gradle Plugin Migration guide
| https://kotl.in/dokka-gradle-migration
|Please migrate Dokka Gradle Plugin to V2. This will require updating your project.
|To get started check out the Dokka Gradle Plugin Migration guide
| https://kotl.in/dokka-gradle-migration
|
| Once you have prepared your project, enable V2 by adding
| $V2_PLUGIN_ENABLED_FLAG=true
| to your project's `gradle.properties`
|Once you have prepared your project, enable V2 by adding
| $V2_PLUGIN_ENABLED_FLAG=true
|to your project's `gradle.properties`
|
| Please report any feedback or problems to Dokka GitHub Issues
| https://github.com/Kotlin/dokka/issues/
""".trimMargin().surroundWithBorder()
|Please report any feedback or problems to Dokka GitHub Issues
| https://github.com/Kotlin/dokka/issues/
""".trimMargin().prependIndent(" > ")
)
}
}

private fun logV2PluginMessage() {
if (primaryService && !v2PluginNoWarn) {
logger.warn("warning: Dokka Gradle Plugin V2 is enabled")
logger.lifecycle(
"""
|Dokka Gradle Plugin V2 is enabled ♡
|We would appreciate your feedback on Dokka Gradle Plugin V2!
|
| We would appreciate your feedback!
| Please report any feedback or problems to Dokka GitHub Issues
| https://github.com/Kotlin/dokka/issues/
|Please report any feedback or problems to Dokka GitHub Issues
| https://github.com/Kotlin/dokka/issues/
|
| If you need help or advice, check out the migration guide
| https://kotl.in/dokka-gradle-migration
|If you need help or advice, check out the migration guide
| https://kotl.in/dokka-gradle-migration
|
| You can suppress this message by adding
| $V2_PLUGIN_NO_WARN_FLAG=true
| to your project's `gradle.properties`
""".trimMargin().surroundWithBorder()
|You can suppress this message by adding
| $V2_PLUGIN_NO_WARN_FLAG=true
|to your project's `gradle.properties`
""".trimMargin().prependIndent(" > ")
)
}
}
Expand All @@ -134,21 +133,20 @@ internal abstract class PluginFeaturesService : BuildService<PluginFeaturesServi

private fun logK2AnalysisMessage() {
if (primaryService && !parameters.k2AnalysisNoWarn.getOrElse(false)) {
logger.warn(
logger.warn("warning: Dokka K2 Analysis is enabled")
logger.lifecycle(
"""
|Dokka K2 Analysis is enabled
|Dokka K2 Analysis is Experimental and is still under active development.
|It can cause build failures or generate incorrect documentation.
|
| This feature is Experimental and is still under active development.
| It can cause build failures or generate incorrect documentation.
|We would appreciate your feedback!
|Please report any feedback or problems to Dokka GitHub Issues
| https://github.com/Kotlin/dokka/issues/
|
| We would appreciate your feedback!
| Please report any feedback or problems to Dokka GitHub Issues
| https://github.com/Kotlin/dokka/issues/
|
| You can suppress this message by adding
| $K2_ANALYSIS_NO_WARN_FLAG_PRETTY=true
| to your project's `gradle.properties`
""".trimMargin().surroundWithBorder()
|You can suppress this message by adding
| $K2_ANALYSIS_NO_WARN_FLAG=true
|to your project's `gradle.properties`
""".trimMargin().prependIndent(" > ")
)
}
}
Expand Down Expand Up @@ -243,24 +241,5 @@ internal abstract class PluginFeaturesService : BuildService<PluginFeaturesServi
.forUseAtConfigurationTimeCompat()
)
.map(String::toBoolean)

/**
* Draw a pretty ascii border around some text.
* This helps with logging a multiline message, so it is easier to view.
*/
private fun String.surroundWithBorder(): String {
val lines = lineSequence().map { it.trimEnd() }
val maxLength = lines.maxOf { it.length }
val horizontalBorder = "─".repeat(maxLength)

return buildString {
appendLine("┌─$horizontalBorder─┐")
lines.forEach { line ->
val paddedLine = line.padEnd(maxLength, padChar = ' ')
appendLine("│ $paddedLine │")
}
appendLine("└─$horizontalBorder─┘")
}
}
}
}
189 changes: 111 additions & 78 deletions dokka-runners/dokka-gradle-plugin/src/testFunctional/kotlin/MigrationMessagesTest.kt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,6 @@ package org.jetbrains.dokka.gradle
import io.kotest.core.spec.style.FunSpec
import io.kotest.matchers.string.shouldContainOnlyOnce
import io.kotest.matchers.string.shouldNotContain
import org.gradle.testkit.runner.BuildResult
import org.jetbrains.dokka.gradle.internal.DokkaConstants
import org.jetbrains.dokka.gradle.utils.*

Expand All @@ -15,50 +14,90 @@ class MigrationMessagesTest : FunSpec({

val project = migrationMessagesTestProject()

context("when no plugin flags are set") {
project.runner
.addArguments(
":help",
"--dry-run",
"--warn",
)
.addArguments()
.build {
test("output should contain V1 warning") {
shouldOnlyContainV1Warning()
}
listOf(
null,
"$V2_PLUGIN_ENABLED_FLAG=false"
).forEach { dgpFlag ->
context("when ${dgpFlag ?: "no"} DGP flag is set") {
context("and log level is set to 'warn'") {
project.runner
.addArguments(
":help",
"--dry-run",
"--warn",
)
.apply {
if (dgpFlag != null) {
addArguments("-P${dgpFlag}")
}
}
.build {
test("output should contain V1 warning") {
output shouldContainOnlyOnce expectedV1Warning
}
test("output should not contain V1 message") {
output shouldNotContain expectedV1Message
}
}
}
}

context("when v2 is disabled") {
project.runner
.addArguments(
":help",
"--dry-run",
"--warn",
"-P$V2_PLUGIN_ENABLED_FLAG=false",
)
.addArguments()
.build {
test("output should contain V1 warning") {
shouldOnlyContainV1Warning()
}
context("and log level is set to 'lifecycle'") {
project.runner
.addArguments(
":help",
"--dry-run",
)
.apply {
if (dgpFlag != null) {
addArguments("-P${dgpFlag}")
}
}
.build {
test("output should contain V1 warning") {
output shouldContainOnlyOnce expectedV1Warning
}
test("output should contain V1 message") {
output shouldContainOnlyOnce expectedV1Message
}
}
}
}
}

context("when v2 is enabled") {

project.runner
.addArguments(
":help",
"--dry-run",
"-P$V2_PLUGIN_ENABLED_FLAG=true",
)
.build {
test("output should only contain V2 message") {
shouldOnlyContainV2Message()
context("and log level is set to 'warn'") {
project.runner
.addArguments(
":help",
"--dry-run",
"--warn",
"-P$V2_PLUGIN_ENABLED_FLAG=true",
)
.build {
test("output should contain V2 warning") {
output shouldContainOnlyOnce expectedV2Warning
}
test("output should not contain V2 message") {
output shouldNotContain expectedV2Message
}
}
}
}
context("and log level is set to 'lifecycle'") {
project.runner
.addArguments(
":help",
"--dry-run",
"-P$V2_PLUGIN_ENABLED_FLAG=true",
)
.build {
test("output should contain V2 warning") {
output shouldContainOnlyOnce expectedV2Warning
}
test("output should contain V2 message") {
output shouldContainOnlyOnce expectedV2Message
}
}
}

listOf(
V2_PLUGIN_NO_WARN_FLAG,
Expand Down Expand Up @@ -102,48 +141,42 @@ class MigrationMessagesTest : FunSpec({
private const val V2_PLUGIN_NO_WARN_FLAG_PRETTY =
"${V2_PLUGIN_ENABLED_FLAG}.noWarn"

fun BuildResult.shouldOnlyContainV1Warning() {
output shouldContainOnlyOnce /* language=text */ """
|┌──────────────────────────────────────────────────────────────────────────────────────┐
|│ ⚠ Warning: Dokka Gradle Plugin V1 mode is enabled │
|│ │
|│ V1 mode is deprecated, and will be removed in Dokka version 2.1.0 │
|│ │
|│ Please migrate Dokka Gradle Plugin to V2. This will require updating your project. │
|│ To get started check out the Dokka Gradle Plugin Migration guide │
|│ https://kotl.in/dokka-gradle-migration │
|│ │
|│ Once you have prepared your project, enable V2 by adding │
|│ org.jetbrains.dokka.experimental.gradlePlugin.enableV2=true │
|│ to your project's `gradle.properties` │
|│ │
|│ Please report any feedback or problems to Dokka GitHub Issues │
|│ https://github.com/Kotlin/dokka/issues/ │
|└──────────────────────────────────────────────────────────────────────────────────────┘
""".trimMargin()
output shouldNotContain "Dokka Gradle Plugin V2"
}
private val expectedV1Warning = /* language=text */ """
|warning: Dokka Gradle Plugin V1 mode is deprecated
""".trimMargin()

fun BuildResult.shouldOnlyContainV2Message() {
output shouldContainOnlyOnce /* language=text */ """
|┌──────────────────────────────────────────────────────────────────────────┐
|│ Dokka Gradle Plugin V2 is enabled ♡ │
|│ │
|│ We would appreciate your feedback! │
|│ Please report any feedback or problems to Dokka GitHub Issues │
|│ https://github.com/Kotlin/dokka/issues/ │
|│ │
|│ If you need help or advice, check out the migration guide │
|│ https://kotl.in/dokka-gradle-migration │
|│ │
|│ You can suppress this message by adding │
|│ org.jetbrains.dokka.experimental.gradlePlugin.enableV2.nowarn=true │
|│ to your project's `gradle.properties` │
|└──────────────────────────────────────────────────────────────────────────┘
""".trimMargin()
output shouldNotContain "Dokka Gradle Plugin V1"
}
private val expectedV1Message = /* language=text */ """
|Dokka Gradle Plugin V1 mode is deprecated, and will be removed in Dokka version 2.1.0
|
|Please migrate Dokka Gradle Plugin to V2. This will require updating your project.
|To get started check out the Dokka Gradle Plugin Migration guide
| https://kotl.in/dokka-gradle-migration
|
|Once you have prepared your project, enable V2 by adding
| ${V2_PLUGIN_ENABLED_FLAG}=true
|to your project's `gradle.properties`
|
|Please report any feedback or problems to Dokka GitHub Issues
| https://github.com/Kotlin/dokka/issues/
""".trimMargin().prependIndent(" > ")

private val expectedV2Warning = /* language=text */ """
|warning: Dokka Gradle Plugin V2 is enabled
""".trimMargin()

private val expectedV2Message = /* language=text */ """
|We would appreciate your feedback on Dokka Gradle Plugin V2!
|
|Please report any feedback or problems to Dokka GitHub Issues
| https://github.com/Kotlin/dokka/issues/
|
|If you need help or advice, check out the migration guide
| https://kotl.in/dokka-gradle-migration
|
|You can suppress this message by adding
| $V2_PLUGIN_NO_WARN_FLAG=true
|to your project's `gradle.properties`
""".trimMargin().prependIndent(" > ")
}
}

Expand Down
Loading

0 comments on commit f95679a

Please sign in to comment.