Release notes generator: RC support and ignore prereleases to generate changelog since previous release (#503)

## What is the goal of this PR?

We update the release notes generator tool to be able to handle `-rc1`
in a version tag, and to generate the complete change log during a full
release since previous full release.

We also only emit a PR description once per PR. Github lists as pulls
for a given commit all pull requests involving the commit, which
includes e.g. merges from development into master. We now restrict each
PR description to only be emitted once, and fallback to the commit
message if all PRs have been filtered out.

Author: dmitrii-ubskii

tool/release/notes/Commit.kt

@@ -54,10 +54,18 @@ private fun getPrecedingVersion(org: String, repo: String, version: Version, git
     tags.addAll(body.asArray().map { release -> Version.parse(release.asObject().get("tag_name").asString()) })
     tags.sort()
     val currentIdx = tags.indexOf(version)
-    val preceding =
-        if (currentIdx >= 1) tags[currentIdx - 1]
-        else if (currentIdx == 0) null
-        else throw IllegalStateException("Version '$version' not found: currentIdx = '$currentIdx'")
+    val preceding = when {
+        currentIdx < 0 -> throw IllegalStateException("Version '$version' not found: currentIdx = '$currentIdx'")
+        currentIdx == 0 -> null
+        version.isPrerelease() -> tags[currentIdx - 1]
+        else -> {
+            var previousRelease = currentIdx - 1
+            while (previousRelease >= 0 && tags[previousRelease].isPrerelease()) previousRelease--
+
+            if (previousRelease < 0) null
+            else tags[previousRelease]
+        }
+    }
     return preceding
 }
 

tool/release/notes/Note.kt

@@ -124,14 +124,16 @@ ${others.map(Note::toMarkdown).joinToString("\n")}
 }
 
 fun collectNotes(org: String, repo: String, commits: List<String>, githubToken: String): List<Note> {
+    val seenPRs = HashSet<Int>()
     return commits.flatMap { commit ->
         val pullsRes = httpGet("$github/repos/$org/$repo/commits/$commit/pulls", githubToken)
         val pullsJSON = Json.parse(pullsRes.parseAsString())
-        val prs = pullsJSON.asArray()
-        if (prs.size() > 0) {
+        val prs = pullsJSON.asArray().filterNot { pr -> seenPRs.contains(pr.asObject().get("number").asInt()) }
+        if (prs.size > 0) {
             val notes = prs.map { pr ->
                 val prNumber = pr.asObject().get("number").asInt()
                 println("collecting PR #$prNumber from commit '$commit'...")
+                seenPRs.add(prNumber)
                 Note.fromGithubPR(pr.asObject())
             }
             notes

tool/release/notes/Version.kt

@@ -21,65 +21,76 @@
 
 package com.vaticle.dependencies.tool.release.notes
 
-data class Version(val major: Int, val minor: Int, val patch: Int, val alpha: Int?): Comparable<Version> {
+data class Version(val major: Int, val minor: Int, val patch: Int, val rc: Int?, val alpha: Int?): Comparable<Version> {
     companion object {
         fun parse(version: String): Version {
-            val version1 = version.split("-")
-            require(version1.isNotEmpty() && version1.size <= 3) {
-                "version '$version1' does not follow the form 'x.y.z', 'x.y.z-alpha', or 'x.y.z-alpha-n'"
-            }
-            val version2 = version1[0].split(".")
-            if (version1.size == 1) {
-                require(version2.size == 3) { "version must be of the form x.y.z" }
-                return Version(
-                    major = version2[0].toInt(),
-                    minor = version2[1].toInt(),
-                    patch = version2[2].toInt(),
-                    alpha = null
-                )
-            } else if (version1.size == 2) {
-                return Version(
-                    major = version2[0].toInt(),
-                    minor = version2[1].toInt(),
-                    patch = version2[2].toInt(),
-                    alpha = 1
-                )
-            } else {
-                return Version(
-                    major = version2[0].toInt(),
-                    minor = version2[1].toInt(),
-                    patch = version2[2].toInt(),
-                    alpha = version1[2].toInt()
-                )
+            val components = version.split("-")
+            val (major, minor, patch) = components[0].split(".").map(String::toInt)
+            return when (components.size) {
+                1 -> Version(major = major, minor = minor, patch = patch, rc = null, alpha = null)
+                2 -> when {
+                    components[1] == "alpha" -> Version(major = major, minor = minor, patch = patch, rc = null, alpha = 1)
+                    components[1].startsWith("rc") -> Version(
+                        major = major,
+                        minor = minor,
+                        patch = patch,
+                        rc = components[1].removePrefix("rc").toInt(),
+                        alpha = null
+                    )
+                    else -> {
+                        throw IllegalArgumentException(
+                            "version '$version' does not follow the form 'x.y.z', 'x.y.z-rcN', 'x.y.z-alpha', or 'x.y.z-alpha-N'"
+                        )
+                    }
+                }
+                3 -> {
+                    require(components[1] == "alpha") {
+                        "version '$version' does not follow the form 'x.y.z', 'x.y.z-rcN', 'x.y.z-alpha', or 'x.y.z-alpha-N'"
+                    }
+                    Version(major = major, minor = minor, patch = patch, rc = null, alpha = components[2].toInt())
+                }
+                else -> {
+                    throw IllegalArgumentException(
+                        "version '$version' does not follow the form 'x.y.z', 'x.y.z-rcN', 'x.y.z-alpha', or 'x.y.z-alpha-N'"
+                    ) 
+                }
             }
         }
     }
 
     override fun compareTo(other: Version): Int {
         val major = major.compareTo(other.major)
-        if (major == 0) {
-            val minor = minor.compareTo(other.minor)
-            if (minor == 0) {
-                val patch = patch.compareTo(other.patch)
-                if (patch == 0) {
-                    if (alpha == null) {
-                        if (other.alpha == null) return 0
-                        else return 1
-                    } else {
-                        if (other.alpha != null) return alpha.compareTo(other.alpha)
-                        else return -1
-                    }
-                } else return patch
-            } else return minor
-        } else return major
+        if (major != 0) return major
+
+        val minor = minor.compareTo(other.minor)
+        if (minor != 0) return minor
+
+        val patch = patch.compareTo(other.patch)
+        if (patch != 0) return patch
+
+        if (rc != null) {
+            if (other.rc != null) return rc.compareTo(other.rc)
+            else if (other.alpha != null) return 1
+            else return -1
+        }
+
+        if (alpha != null) {
+            if (other.alpha != null) return alpha.compareTo(other.alpha)
+            else return -1
+        }
+
+        return 1 // x.y.z is always after x.y.z-prereleases
     }
 
     override fun toString(): String {
-        val alpha =
-            if (alpha != null) {
-                if (alpha == 1) "-alpha"
-                else "-alpha-$alpha"
-            } else ""
-        return "$major.$minor.$patch$alpha"
+        val prerelease = when {
+            rc != null -> "-rc$rc"
+            alpha == 1 -> "-alpha"
+            alpha != null -> "-alpha-$alpha"
+            else -> ""
+        }
+        return "$major.$minor.$patch$prerelease"
     }
+
+    fun isPrerelease(): Boolean = rc != null || alpha != null
 }