Minor refactoring of dokka versioning and publishing (#2401)

* Minor refactoring of dokka versioning and publishing

* Added RC version type
* Added gradle-plugin-portal as a publication channel
* Removed `dokka_version_base` in favour of `dokka_version`
* Change dokka_version to the relevant SNAPSHOT
* Revert explicit flag for version checking, it will be executed automatically if publication channels are present
* Update publish to GH pages script to include SNAPSHOT docs

5 files changed, 67 insertions, 64 deletions

diff --git a/buildSrc/src/main/kotlin/org/jetbrains/DokkaPublicationChannel.kt b/buildSrc/src/main/kotlin/org/jetbrains/DokkaPublicationChannel.kt
index 6b78edba..03f607e8 100644
--- a/buildSrc/src/main/kotlin/org/jetbrains/DokkaPublicationChannel.kt
+++ b/buildSrc/src/main/kotlin/org/jetbrains/DokkaPublicationChannel.kt
@@ -5,30 +5,31 @@ package org.jetbrains
 import org.gradle.api.Project
 
 enum class DokkaPublicationChannel {
-    SpaceDokkaDev,
-    MavenCentral,
-    MavenCentralSnapshot;
-
-    val isSpaceRepository get() = this == SpaceDokkaDev
-
-    val isMavenRepository
-        get() = when (this) {
-            MavenCentral, MavenCentralSnapshot -> true
-            else -> false
-        }
+    SPACE_DOKKA_DEV,
+    MAVEN_CENTRAL,
+    MAVEN_CENTRAL_SNAPSHOT,
+    GRADLE_PLUGIN_PORTAL;
 
     val acceptedDokkaVersionTypes: List<DokkaVersionType>
         get() = when(this) {
-            MavenCentral -> listOf(DokkaVersionType.Release)
-            MavenCentralSnapshot -> listOf(DokkaVersionType.Snapshot)
-            SpaceDokkaDev -> listOf(DokkaVersionType.Release, DokkaVersionType.Dev, DokkaVersionType.MC, DokkaVersionType.Snapshot)
+            MAVEN_CENTRAL -> listOf(DokkaVersionType.RELEASE, DokkaVersionType.RC)
+            MAVEN_CENTRAL_SNAPSHOT -> listOf(DokkaVersionType.SNAPSHOT)
+            SPACE_DOKKA_DEV -> listOf(DokkaVersionType.RELEASE, DokkaVersionType.RC, DokkaVersionType.DEV, DokkaVersionType.SNAPSHOT)
+            GRADLE_PLUGIN_PORTAL -> listOf(DokkaVersionType.RELEASE, DokkaVersionType.RC)
         }
 
+    fun isSpaceRepository() = this == SPACE_DOKKA_DEV
+
+    fun isMavenRepository() =  this == MAVEN_CENTRAL || this == MAVEN_CENTRAL_SNAPSHOT
+
+    fun isGradlePluginPortal() = this == GRADLE_PLUGIN_PORTAL
+
     companion object {
         fun fromPropertyString(value: String): DokkaPublicationChannel = when (value) {
-            "space-dokka-dev" -> SpaceDokkaDev
-            "maven-central-release" -> MavenCentral
-            "maven-central-snapshot" -> MavenCentralSnapshot
+            "space-dokka-dev" -> SPACE_DOKKA_DEV
+            "maven-central-release" -> MAVEN_CENTRAL
+            "maven-central-snapshot" -> MAVEN_CENTRAL_SNAPSHOT
+            "gradle-plugin-portal" -> GRADLE_PLUGIN_PORTAL
             else -> throw IllegalArgumentException("Unknown dokka_publication_channel=$value")
         }
     }
diff --git a/buildSrc/src/main/kotlin/org/jetbrains/DokkaVersion.kt b/buildSrc/src/main/kotlin/org/jetbrains/DokkaVersion.kt
index 05585d06..517c7731 100644
--- a/buildSrc/src/main/kotlin/org/jetbrains/DokkaVersion.kt
+++ b/buildSrc/src/main/kotlin/org/jetbrains/DokkaVersion.kt
@@ -4,26 +4,16 @@ import org.gradle.api.Project
 import org.gradle.kotlin.dsl.extra
 import org.gradle.kotlin.dsl.provideDelegate
 
+@Suppress("LocalVariableName") // property name with underscore as taken from gradle.properties
 fun Project.configureDokkaVersion(): String {
-    var dokka_version: String? by this.extra
-    if (dokka_version == null) {
-        val dokka_version_base: String by this
-        dokka_version = dokkaVersionFromBase(dokka_version_base)
-    }
+    val dokka_version: String? by this.extra
     return checkNotNull(dokka_version)
 }
 
-private fun dokkaVersionFromBase(baseVersion: String): String {
-    val buildNumber = System.getenv("BUILD_NUMBER")
-    val forceSnapshot = System.getenv("FORCE_SNAPSHOT") != null
-    if (forceSnapshot || buildNumber == null) {
-        return "$baseVersion-SNAPSHOT"
-    }
-    return "$baseVersion-$buildNumber"
-}
-
 val Project.dokkaVersion: String
     get() = configureDokkaVersion()
 
 val Project.dokkaVersionType: DokkaVersionType?
-    get() = DokkaVersionType.values().find { it.suffix.matches(dokkaVersion.substringAfter("-", "")) }
+    get() = DokkaVersionType.values().find {
+        it.suffix.matches(dokkaVersion.substringAfter("-", ""))
+    }
diff --git a/buildSrc/src/main/kotlin/org/jetbrains/DokkaVersionType.kt b/buildSrc/src/main/kotlin/org/jetbrains/DokkaVersionType.kt
index dbf2d312..077cd854 100644
--- a/buildSrc/src/main/kotlin/org/jetbrains/DokkaVersionType.kt
+++ b/buildSrc/src/main/kotlin/org/jetbrains/DokkaVersionType.kt
@@ -1,5 +1,8 @@
 package org.jetbrains
 
 enum class DokkaVersionType(val suffix: Regex) {
-    Release("^$".toRegex()), Snapshot("SNAPSHOT".toRegex()), Dev("dev-\\d+".toRegex()), MC("mc-\\d+".toRegex())
+    RELEASE("^$".toRegex()),
+    RC("RC\\d?".toRegex()),
+    SNAPSHOT("SNAPSHOT".toRegex()),
+    DEV("dev-\\d+".toRegex());
 }
diff --git a/buildSrc/src/main/kotlin/org/jetbrains/ValidatePublications.kt b/buildSrc/src/main/kotlin/org/jetbrains/ValidatePublications.kt
index 921ec025..af35a847 100644
--- a/buildSrc/src/main/kotlin/org/jetbrains/ValidatePublications.kt
+++ b/buildSrc/src/main/kotlin/org/jetbrains/ValidatePublications.kt
@@ -3,6 +3,7 @@ package org.jetbrains
 import org.gradle.api.DefaultTask
 import org.gradle.api.GradleException
 import org.gradle.api.Project
+import org.gradle.api.artifacts.Dependency
 import org.gradle.api.artifacts.ProjectDependency
 import org.gradle.api.publish.PublishingExtension
 import org.gradle.api.publish.maven.MavenPublication
@@ -11,22 +12,21 @@ import org.gradle.kotlin.dsl.findByType
 
 open class ValidatePublications : DefaultTask() {
 
-    class UnpublishedProjectDependencyException(
-        project: Project, dependencyProject: Project
-    ) : GradleException(
-        "Published project ${project.path} cannot depend on unpublished project ${dependencyProject.path}"
-    )
-
+    init {
+        group = "verification"
+        project.tasks.named("check") {
+            dependsOn(this@ValidatePublications)
+        }
+    }
 
     @TaskAction
     fun validatePublicationConfiguration() {
-        @Suppress("LocalVariableName")
         project.subprojects.forEach { subProject ->
             val publishing = subProject.extensions.findByType<PublishingExtension>() ?: return@forEach
             publishing.publications
                 .filterIsInstance<MavenPublication>()
                 .filter { it.version == project.dokkaVersion }
-                .forEach { publication ->
+                .forEach { _ ->
                     checkProjectDependenciesArePublished(subProject)
                     subProject.assertPublicationVersion()
                 }
@@ -34,8 +34,12 @@ open class ValidatePublications : DefaultTask() {
     }
 
     private fun checkProjectDependenciesArePublished(project: Project) {
-        (project.configurations.findByName("implementation")?.allDependencies.orEmpty() +
-                project.configurations.findByName("api")?.allDependencies.orEmpty())
+        val implementationDependencies = project.findDependenciesByName("implementation")
+        val apiDependencies = project.findDependenciesByName("api")
+
+        val allDependencies = implementationDependencies + apiDependencies
+
+        allDependencies
             .filterIsInstance<ProjectDependency>()
             .forEach { projectDependency ->
                 val publishing = projectDependency.dependencyProject.extensions.findByType<PublishingExtension>()
@@ -52,23 +56,24 @@ open class ValidatePublications : DefaultTask() {
             }
     }
 
-    private fun Project.assertPublicationVersion() {
-        if (System.getenv("SKIP_VERSION_CHECK")?.contains("true", ignoreCase = true) == true)
-            return
+    private fun Project.findDependenciesByName(name: String): Set<Dependency> {
+        return configurations.findByName(name)?.allDependencies.orEmpty()
+    }
 
-        if (!publicationChannels.all { publicationChannel ->
-                publicationChannel.acceptedDokkaVersionTypes.any { acceptedVersionType ->
-                    acceptedVersionType == dokkaVersionType
-                }
-            }) {
+    private fun Project.assertPublicationVersion() {
+        val versionTypeMatchesPublicationChannels = publicationChannels.all { publicationChannel ->
+            publicationChannel.acceptedDokkaVersionTypes.any { acceptedVersionType ->
+                acceptedVersionType == dokkaVersionType
+            }
+        }
+        if (!versionTypeMatchesPublicationChannels) {
             throw AssertionError("Wrong version $dokkaVersion for configured publication channels $publicationChannels")
         }
     }
 
-    init {
-        group = "verification"
-        project.tasks.named("check") {
-            dependsOn(this@ValidatePublications)
-        }
-    }
+    private class UnpublishedProjectDependencyException(
+        project: Project, dependencyProject: Project
+    ): GradleException(
+        "Published project ${project.path} cannot depend on unpublished project ${dependencyProject.path}"
+    )
 }
diff --git a/buildSrc/src/main/kotlin/org/jetbrains/publication.kt b/buildSrc/src/main/kotlin/org/jetbrains/publication.kt
index c3fc2ac7..10353b97 100644
--- a/buildSrc/src/main/kotlin/org/jetbrains/publication.kt
+++ b/buildSrc/src/main/kotlin/org/jetbrains/publication.kt
@@ -46,13 +46,13 @@ fun Project.registerDokkaArtifactPublication(publicationName: String, configure:
 }
 
 fun Project.configureSpacePublicationIfNecessary(vararg publications: String) {
-    if (SpaceDokkaDev in this.publicationChannels) {
+    if (SPACE_DOKKA_DEV in this.publicationChannels) {
         configure<PublishingExtension> {
             repositories {
                 /* already registered */
-                findByName(SpaceDokkaDev.name)?.let { return@repositories }
+                findByName(SPACE_DOKKA_DEV.name)?.let { return@repositories }
                 maven {
-                    name = SpaceDokkaDev.name
+                    name = SPACE_DOKKA_DEV.name
                     url = URI.create("https://maven.pkg.jetbrains.space/kotlin/p/dokka/dev")
                     credentials {
                         username = System.getenv("SPACE_PACKAGES_USER")
@@ -65,7 +65,7 @@ fun Project.configureSpacePublicationIfNecessary(vararg publications: String) {
 
     whenEvaluated {
         tasks.withType<PublishToMavenRepository> {
-            if (this.repository.name == SpaceDokkaDev.name) {
+            if (this.repository.name == SPACE_DOKKA_DEV.name) {
                 this.isEnabled = this.isEnabled && publication.name in publications
                 if (!this.isEnabled) {
                     this.group = "disabled"
@@ -77,18 +77,22 @@ fun Project.configureSpacePublicationIfNecessary(vararg publications: String) {
 
 fun Project.createDokkaPublishTaskIfNecessary() {
     tasks.maybeCreate("dokkaPublish").run {
-        if (publicationChannels.any { it.isSpaceRepository }) {
+        if (publicationChannels.any { it.isSpaceRepository() }) {
             dependsOn(tasks.named("publish"))
         }
 
-        if (publicationChannels.any { it.isMavenRepository }) {
+        if (publicationChannels.any { it.isMavenRepository() }) {
             dependsOn(tasks.named("publishToSonatype"))
         }
+
+        if (publicationChannels.any { it.isGradlePluginPortal() }) {
+            dependsOn(tasks.named("publishPlugins"))
+        }
     }
 }
 
 fun Project.configureSonatypePublicationIfNecessary(vararg publications: String) {
-    if (publicationChannels.any { it.isMavenRepository }) {
+    if (publicationChannels.any { it.isMavenRepository() }) {
         signPublicationsIfKeyPresent(*publications)
     }
 }