Enforce semantic versioning at publication with japicmp (#119)

Author: kennethshackleton

.github/workflows/publication.yml

@@ -28,6 +28,16 @@ jobs:
         run: ./gradlew check -x integrationTest
       - name: 'Integration test'
         run: ./gradlew :pushiko-fcm:integrationTest
+      - name: 'Check semantic versioning'
+        if: github.event_name == 'release' && github.event.action == 'published'
+        run: ./gradlew checkSemver
+      - name: 'Archive semver reports'
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: semver-reports
+          path: '**/build/reports/japicmp/'
+          if-no-files-found: ignore
       - name: 'Publish release to Maven Central'
         if: github.event_name == 'release' && github.event.action == 'published'
         env:

README.md

@@ -45,6 +45,10 @@ We believe Pushiko is both mature and generic enough to represent a useful contr
 
 Please refer to the main documentation: For APNs see [Getting started > APNs](https://bloomberg.github.io/pushiko/getting_started_apns/) and for FCM see [Getting started > FCM](https://bloomberg.github.io/pushiko/getting_started_fcm/).
 
+## Versioning
+
+Pushiko follows [Semantic Versioning](https://semver.org/). Breaking changes to the public API are released only in major versions and are documented in the [change log](https://bloomberg.github.io/pushiko/changelog/).
+
 ## Acknowledgements
 
 The original implementation of the Netty channel pool in Pushiko was heavily influenced by Jon Chambers' own APNs Java channel pool in Pushy :bow:. Taking this as our template for how to begin designing our pool, any mistakes introduced in subsequent work are entirely our own.

build-logic/semver/build.gradle.kts

@@ -0,0 +1,7 @@
+plugins {
+    `kotlin-dsl`
+}
+
+dependencies {
+    implementation(libs.japicmp.gradle.plugin)
+}

build-logic/semver/src/main/kotlin/semver.gradle.kts

@@ -0,0 +1,106 @@
+import me.champeau.gradle.japicmp.JapicmpTask
+import me.champeau.gradle.japicmp.JApiCmpWorkerAction
+import org.gradle.api.tasks.bundling.Jar
+import org.gradle.kotlin.dsl.named
+import org.gradle.kotlin.dsl.register
+import java.io.FileNotFoundException
+import java.net.URI
+
+plugins {
+    java
+}
+
+val groupPath = project.group.toString().replace('.', '/')
+
+val baselineVersion = project.findProperty("japicmpBaseline")?.toString() ?: run {
+    val currentVersion = project.version.toString()
+    val currentMajor = currentVersion.substringBefore('.')
+    val metadataUrl = "https://repo1.maven.org/maven2/$groupPath/${project.name}/maven-metadata.xml"
+    val metadata = try {
+        URI.create(metadataUrl).toURL().openStream().bufferedReader().use { it.readText() }
+    } catch (_: FileNotFoundException) {
+        return@run ""
+    }
+    val allVersions = """<version>([^<]+)</version>""".toRegex().findAll(metadata)
+        .map { it.groupValues[1] }
+        .filter { it.startsWith("$currentMajor.") }
+        .toList()
+
+    allVersions.maxWithOrNull { first, second ->
+        val firstComponents = first.drop(currentMajor.length + 1).split('.')
+        val secondComponents = second.drop(currentMajor.length + 1).split('.')
+        for (i in 0 until minOf(firstComponents.size, secondComponents.size)) {
+            val firstVersion = firstComponents[i].toInt()
+            val secondVersion = secondComponents[i].toInt()
+            firstVersion.compareTo(secondVersion).let {
+                if (it != 0) {
+                    return@maxWithOrNull it
+                }
+            }
+        }
+        firstComponents.size.compareTo(secondComponents.size)
+    } ?: ""
+}
+
+val baselineJar = layout.buildDirectory.file(project.provider {
+    "japicmp/${project.name}-$baselineVersion.jar"
+})
+
+val downloadJapicmpBaseline = tasks.register("downloadJapicmpBaseline") {
+    group = "verification"
+    description = "Download baseline JAR from Maven Central for japicmp comparison."
+    onlyIf { baselineVersion.isNotEmpty() }
+    outputs.file(baselineJar)
+    notCompatibleWithConfigurationCache("downloads from Maven Central")
+
+    doLast {
+        val downloadUrl = "https://repo1.maven.org/maven2/$groupPath/${project.name}/$baselineVersion/${project.name}-$baselineVersion.jar"
+        val dest = baselineJar.get().asFile
+        if (!dest.exists()) {
+            dest.parentFile.mkdirs()
+            runCatching {
+                logger.info("Downloading baseline JAR from {}", downloadUrl)
+                URI.create(downloadUrl).toURL().openStream().use {
+                    dest.outputStream().use(it::copyTo)
+                }
+                logger.info("Baseline JAR downloaded: {}", dest.absolutePath)
+            }.onFailure {
+                logger.info("Failed to download baseline JAR ({}), skipping check", it.message)
+                dest.writeText("")
+            }
+        }
+    }
+}
+
+val jarTask = tasks.named<Jar>("jar")
+
+val checkSemver = tasks.register<JapicmpTask>("checkSemver") {
+    dependsOn(downloadJapicmpBaseline, jarTask)
+    group = "verification"
+    description = "Fails on binary-incompatible changes vs $baselineVersion."
+    onlyIf { baselineJar.get().asFile.exists() && baselineJar.get().asFile.length() > 0 }
+
+    oldArchiveList.add(project.provider {
+        JApiCmpWorkerAction.Archive(baselineJar.get().asFile, baselineVersion)
+    })
+    newArchiveList.add(project.provider {
+        JApiCmpWorkerAction.Archive(jarTask.get().archiveFile.get().asFile, project.version.toString())
+    })
+
+    oldClasspath.from(configurations.runtimeClasspath)
+    newClasspath.from(configurations.runtimeClasspath)
+
+    onlyBinaryIncompatibleModified = true
+    failOnModification = true
+    ignoreMissingClasses = true
+
+    // Filter Kotlin bytecode idioms that are JVM-public but not part of the API.
+    methodExcludes = listOf("*#*\$*(*)")
+    fieldExcludes = listOf("*#*\$*")
+    classExcludes = listOf("*\$WhenMappings")
+
+    txtOutputFile = layout.buildDirectory.file("reports/japicmp/${project.name}.txt")
+    htmlOutputFile = layout.buildDirectory.file("reports/japicmp/${project.name}.html")
+}
+
+rootProject.tasks.named("checkSemver") { dependsOn(checkSemver) }

build-logic/settings.gradle.kts

@@ -0,0 +1,15 @@
+rootProject.name = "build-logic"
+
+include(":semver")
+
+dependencyResolutionManagement {
+    repositories {
+        mavenCentral()
+        gradlePluginPortal()
+    }
+    versionCatalogs {
+        register("libs") {
+            from(files("../gradle/libs.versions.toml"))
+        }
+    }
+}

build.gradle.kts

@@ -226,6 +226,11 @@ tasks.named("check") {
     dependsOn("koverVerify")
 }
 
+tasks.register("checkSemver") {
+    group = "verification"
+    description = "Binary-compatibility check across all published modules."
+}
+
 idea.project.settings {
     copyright {
         useDefault = "Bloomberg"

buildSrc/build.gradle.kts

@@ -32,4 +32,5 @@ dependencies {
     compileOnly(gradleKotlinDsl())
     implementation(platform(libs.kotlin.bom))
     implementation(kotlin("gradle-plugin", version=libs.versions.kotlin.get()))
+    implementation(libs.japicmp.gradle.plugin)
 }

buildSrc/settings.gradle.kts

@@ -27,5 +27,6 @@ dependencyResolutionManagement {
     @Suppress("UnstableApiUsage")
     repositories {
         mavenCentral()
+        gradlePluginPortal()
     }
 }

gradle/libs.versions.toml

@@ -9,6 +9,7 @@ atomicfu = { module = "org.jetbrains.kotlinx:atomicfu-gradle-plugin", version =
 findbugs-jsr305 = { module = "com.google.code.findbugs:jsr305", version = "3.0.2" }
 google-auth = { module = "com.google.auth:google-auth-library-oauth2-http", version = "1.43.0" }
 gson = { module = "com.google.code.gson:gson", version = "2.10.1" }
+japicmp-gradle-plugin = { module = "me.champeau.gradle:japicmp-gradle-plugin", version = "0.4.6" }
 kotlin-bom = { module = "org.jetbrains.kotlin:kotlin-bom", version.ref = "kotlin" }
 kotlin-reflect = { module = "org.jetbrains.kotlin:kotlin-reflect" }
 kotlin-test-junit5 = { module = "org.jetbrains.kotlin:kotlin-test-junit5" }

pushiko-api/build.gradle.kts

@@ -18,6 +18,7 @@ description = "API commonly exposed by multiple subprojects of Pushiko"
 
 plugins {
     kotlin("jvm")
+    id("semver")
     alias(libs.plugins.dokka)
     `library-conventions`
     alias(libs.plugins.kover)