Update Gradle module metadata warnings: don't warn when it's enabled

Also add a suggestion to enable the module metadata publishing in
Gradle 5.3+ projects that consume Gradle module metadata by default but
don't produce it unless explicitly enabled.

Issue #KT-31023 Fixed

libraries/tools/kotlin-gradle-plugin-integration-tests/src/test/kotlin/org/jetbrains/kotlin/gradle/NewMultiplatformIT.kt

@@ -4,6 +4,7 @@
  */
 package org.jetbrains.kotlin.gradle
 
+import org.jetbrains.kotlin.gradle.internals.GRADLE_NO_METADATA_WARNING
 import org.jetbrains.kotlin.gradle.plugin.ProjectLocalConfigurations
 import org.jetbrains.kotlin.gradle.plugin.mpp.KotlinJvmWithJavaTargetPreset
 import org.jetbrains.kotlin.gradle.plugin.mpp.KotlinMultiplatformPlugin
@@ -1834,4 +1835,20 @@ class NewMultiplatformIT : BaseGradleIT() {
         doTestPomRewriting(mppProjectDependency = false, legacyPublishing = false, keepPomIntact = true)
         doTestPomRewriting(mppProjectDependency = false, legacyPublishing = true, keepPomIntact = true)
     }
+
+    @Test
+    fun testSuggestionToEnableMetadata() = with(Project("sample-lib", GradleVersionRequired.AtLeast("4.7"), "new-mpp-lib-and-app")) {
+        build {
+            assertNotContains(GRADLE_NO_METADATA_WARNING)
+
+            gradleSettingsScript().modify { it.replace("enableFeaturePreview(", "//") }
+            build {
+                if (testGradleVersionAtLeast("5.3-rc-2")) {
+                    assertContains(GRADLE_NO_METADATA_WARNING)
+                } else {
+                    assertNotContains(GRADLE_NO_METADATA_WARNING)
+                }
+            }
+        }
+    }
 }

libraries/tools/kotlin-gradle-plugin/src/main/kotlin/org/jetbrains/kotlin/gradle/plugin/mpp/KotlinMultiplatformPlugin.kt

@@ -145,11 +145,14 @@ class KotlinMultiplatformPlugin(
 
     private fun configurePublishingWithMavenPublish(project: Project) = project.pluginManager.withPlugin("maven-publish") { _ ->
 
-        if (project.multiplatformExtension.run { isGradleMetadataAvailable && isGradleMetadataExperimental }) {
+        if (isGradleVersionAtLeast(5, 3) &&
-            SingleWarningPerBuild.show(
+            project.multiplatformExtension.run { isGradleMetadataExperimental && !isGradleMetadataAvailable }
-                project,
+        ) {
-                GRADLE_METADATA_WARNING
+            SingleWarningPerBuild.show(project, GRADLE_NO_METADATA_WARNING)
-            )
+        }
+
+        if (!isGradleVersionAtLeast(4, 8) && project.multiplatformExtension.isGradleMetadataAvailable) {
+            SingleWarningPerBuild.show(project, GRADLE_OLD_METADATA_WARNING)
         }
 
         val targets = project.multiplatformExtension.targets
@@ -252,12 +255,16 @@ class KotlinMultiplatformPlugin(
     companion object {
         const val METADATA_TARGET_NAME = "metadata"
 
-        const val GRADLE_METADATA_WARNING =
+        internal const val GRADLE_NO_METADATA_WARNING = "This build consumes Gradle module metadata but does not produce " +
-        // TODO point the user to some MPP docs explaining this in more detail
+                "it when publishing Kotlin multiplatform libraries. \n" +
-            "This build is set up to publish Kotlin multiplatform libraries with experimental Gradle metadata. " +
+                "To enable Gradle module metadata in publications, add 'enableFeaturePreview(\"GRADLE_METADATA\")' " +
-                    "Future Gradle versions may fail to resolve dependencies on these publications. " +
+                "to the settings.gradle file. \n" +
-                    "You can disable Gradle metadata usage during publishing and dependencies resolution by removing " +
+                "See: https://kotlinlang.org/docs/reference/building-mpp-with-gradle.html#experimental-metadata-publishing-mode"
-                    "`enableFeaturePreview('GRADLE_METADATA')` from the settings.gradle file."
+
+        internal const val GRADLE_OLD_METADATA_WARNING = "This build is set up to publish a Kotlin multiplatform library " +
+                "with an outdated Gradle module metadata format, which newer Gradle versions won't be able to consume. \n" +
+                "Please update the Gradle version to 5.3 or newer. \n" +
+                "See: https://kotlinlang.org/docs/reference/building-mpp-with-gradle.html#experimental-metadata-publishing-mode"
     }
 }
 

libraries/tools/kotlin-gradle-plugin/src/test/kotlin/org/jetbrains/kotlin/gradle/internals/ExposedForIntegrationTests.kt

@@ -12,4 +12,7 @@ fun parseKotlinSourceSetMetadataFromXml(document: Document): KotlinProjectStruct
     org.jetbrains.kotlin.gradle.plugin.mpp.parseKotlinSourceSetMetadataFromXml(document)
 
 const val MULTIPLATFORM_PROJECT_METADATA_FILE_NAME =
-    org.jetbrains.kotlin.gradle.plugin.mpp.MULTIPLATFORM_PROJECT_METADATA_FILE_NAME
+    org.jetbrains.kotlin.gradle.plugin.mpp.MULTIPLATFORM_PROJECT_METADATA_FILE_NAME
+
+const val GRADLE_NO_METADATA_WARNING =
+    org.jetbrains.kotlin.gradle.plugin.mpp.KotlinMultiplatformPlugin.GRADLE_NO_METADATA_WARNING