Add japicmp

.github/workflows/build-common.yml

@@ -56,6 +56,22 @@ jobs:
       - name: Build
         run: ./gradlew build -x spotlessCheck -x test ${{ inputs.no-build-cache && '--no-build-cache' || '' }}
 
+      - name: Check for jApiCmp diffs
+        # The jApiCmp diff compares current to latest, which isn't appropriate for release branches
+        if: ${{ !startsWith(github.ref_name, 'release/') && !startsWith(github.base_ref, 'release/') }}
+        run: |
+          # need to "git add" in case any generated files did not already exist
+          git add docs/apidiffs
+          if git diff --cached --quiet
+          then
+            echo "No diff detected."
+          else
+            echo "Diff detected - did you run './gradlew jApiCmp'?"
+            git diff --cached --name-only
+            git diff --cached
+            exit 1
+          fi
+
   test:
     name: Test
     runs-on: ${{ matrix.os }}

.github/workflows/release.yml

@@ -173,13 +173,15 @@ jobs:
 
           echo "version=$VERSION" >> $GITHUB_OUTPUT
 
-  merge-change-log-to-main:
+  post-release-updates:
     permissions:
       contents: write # for git push to PR branch
     runs-on: ubuntu-latest
     needs:
       - release
     steps:
+      # add change log sync (if any) into this PR since the apidiff update
+      # is required before any other PR can be merged anyway
       - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
 
       - name: Copy change log section from release branch
@@ -201,6 +203,37 @@ jobs:
           release_date=$(gh release view v$VERSION --json publishedAt --jq .publishedAt | sed 's/T.*//')
           RELEASE_DATE=$release_date .github/scripts/merge-change-log-after-release.sh
 
+      - name: Wait for release to be available in maven central
+        env:
+          VERSION: ${{ needs.release.outputs.version }}
+        run: |
+          until curl --silent \
+                     --show-error \
+                     --output /dev/null \
+                     --head \
+                     --fail \
+                      https://repo1.maven.org/maven2/io/opentelemetry/contrib/opentelemetry-aws-xray/$VERSION/opentelemetry-aws-xray-$VERSION.jar
+          do
+            sleep 60
+          done
+
+      - name: Set up JDK for running Gradle
+        uses: actions/setup-java@dded0888837ed1f317902acf8a20df0ad188d165 # v5.0.0
+        with:
+          distribution: temurin
+          java-version: 17
+
+      - name: Set up Gradle
+        uses: gradle/actions/setup-gradle@017a9effdb900e5b5b2fddfb590a105619dca3c3 # v4.4.2
+
+      - name: Update apidiff baseline
+        env:
+          VERSION: ${{ needs.release.outputs.version }}
+          PRIOR_VERSION: ${{ needs.release.outputs.prior-version }}
+        run: |
+          ./gradlew japicmp -PapiBaseVersion=$PRIOR_VERSION -PapiNewVersion=$VERSION
+          ./gradlew --refresh-dependencies japicmp
+
       - name: Use CLA approved bot
         run: .github/scripts/use-cla-approved-bot.sh
 
@@ -216,22 +249,14 @@ jobs:
           # not using secrets.GITHUB_TOKEN since pull requests from that token do not run workflows
           GH_TOKEN: ${{ steps.otelbot-token.outputs.token }}
         run: |
-          if git diff --quiet; then
-            if [[ $VERSION == *.0 ]]; then
-              echo there are no updates to merge, not creating pull request
-              exit 0 # success
-            else
-              echo patch release notes did not get applied for some reason
-              exit 1 # failure
-            fi
-          fi
-
-          message="Merge change log updates from $GITHUB_REF_NAME"
-          body="Merge log updates from \`$GITHUB_REF_NAME\`."
-          branch="otelbot/merge-change-log-updates-from-${GITHUB_REF_NAME//\//-}"
+          message="Post-release updates for $VERSION"
+          body="Post-release updates for `$VERSION`."
+          branch="otelbot/update-apidiff-baseline-to-released-version-${VERSION}"
 
           git checkout -b $branch
-          git commit -a -m "$message"
+          git add CHANGELOG.md
+          git add docs/apidiffs
+          git commit -m "$message"
           git push --set-upstream origin $branch
           gh pr create --title "$message" \
                        --body "$body" \

buildSrc/build.gradle.kts

@@ -18,6 +18,8 @@ dependencies {
   implementation("org.owasp:dependency-check-gradle:12.1.3")
   implementation("ru.vyarus.animalsniffer:ru.vyarus.animalsniffer.gradle.plugin:2.0.1")
   implementation("com.gradle:develocity-gradle-plugin:4.1.1")
+  implementation("me.champeau.gradle:japicmp-gradle-plugin:0.4.6")
+  implementation("com.google.auto.value:auto-value-annotations:1.11.0")
 }
 
 spotless {

buildSrc/src/main/kotlin/otel.japicmp-conventions.gradle.kts

@@ -0,0 +1,158 @@
+import com.google.auto.value.AutoValue
+import japicmp.model.*
+import me.champeau.gradle.japicmp.JapicmpTask
+import me.champeau.gradle.japicmp.report.Violation
+import me.champeau.gradle.japicmp.report.stdrules.*
+
+
+plugins {
+  base
+
+  id("me.champeau.gradle.japicmp")
+}
+
+/**
+ * The latest *released* version of the project. Evaluated lazily so the work is only done if necessary.
+ */
+val latestReleasedVersion: String by lazy {
+  // hack to find the current released version of the project
+  val temp: Configuration = configurations.create("tempConfig") {
+    resolutionStrategy.cacheChangingModulesFor(0, "seconds")
+    resolutionStrategy.cacheDynamicVersionsFor(0, "seconds")
+  }
+  // pick aws-xray, since it's a stable module that's always there.
+  dependencies.add(temp.name, "io.opentelemetry.contrib:opentelemetry-aws-xray:latest.release")
+  val moduleVersion = configurations["tempConfig"].resolvedConfiguration.firstLevelModuleDependencies.elementAt(0).moduleVersion
+  configurations.remove(temp)
+  logger.debug("Discovered latest release version: " + moduleVersion)
+  moduleVersion
+}
+
+class AllowNewAbstractMethodOnAutovalueClasses : AbstractRecordingSeenMembers() {
+  override fun maybeAddViolation(member: JApiCompatibility): Violation? {
+    val allowableAutovalueChanges = setOf(JApiCompatibilityChangeType.METHOD_ABSTRACT_ADDED_TO_CLASS,
+      JApiCompatibilityChangeType.METHOD_ADDED_TO_PUBLIC_CLASS, JApiCompatibilityChangeType.ANNOTATION_ADDED)
+    if (member.compatibilityChanges.filter { !allowableAutovalueChanges.contains(it.type) }.isEmpty() &&
+      member is JApiMethod && isAutoValueClass(member.getjApiClass()))
+    {
+      return Violation.accept(member, "Autovalue will automatically add implementation")
+    }
+    if (member.compatibilityChanges.isEmpty() &&
+      member is JApiClass && isAutoValueClass(member)) {
+      return Violation.accept(member, "Autovalue class modification is allowed")
+    }
+    return null
+  }
+
+  fun isAutoValueClass(japiClass: JApiClass): Boolean {
+    return japiClass.newClass.get().getAnnotation(AutoValue::class.java) != null ||
+        japiClass.newClass.get().getAnnotation(AutoValue.Builder::class.java) != null
+  }
+}
+
+class SourceIncompatibleRule : AbstractRecordingSeenMembers() {
+  override fun maybeAddViolation(member: JApiCompatibility): Violation? {
+    if (!member.isSourceCompatible()) {
+      return Violation.error(member, "Not source compatible: $member")
+    }
+    return null
+  }
+}
+
+/**
+ * Locate the project's artifact of a particular version.
+ */
+fun findArtifact(version: String): File {
+  val existingGroup = group
+  try {
+    // Temporarily change the group name because we want to fetch an artifact with the same
+    // Maven coordinates as the project, which Gradle would not allow otherwise.
+    group = "virtual_group"
+    val depModule = "io.opentelemetry.contrib:${base.archivesName.get()}:$version@jar"
+    val depJar = "${base.archivesName.get()}-$version.jar"
+    val configuration: Configuration = configurations.detachedConfiguration(
+      dependencies.create(depModule),
+    )
+    return files(configuration.files).filter {
+      it.name.equals(depJar)
+    }.singleFile
+  } finally {
+    group = existingGroup
+  }
+}
+
+// generate the api diff report for any module that is stable and publishes a jar.
+if (project.findProperty("otel.stable") == "true" && !project.name.startsWith("bom")) {
+  afterEvaluate {
+    tasks {
+      val jApiCmp by registering(JapicmpTask::class) {
+        dependsOn("jar")
+
+        // the japicmp "new" version is either the user-specified one, or the locally built jar.
+        val apiNewVersion: String? by project
+        val newArtifact = apiNewVersion?.let { findArtifact(it) }
+          ?: file(getByName<Jar>("jar").archiveFile)
+        newClasspath.from(files(newArtifact))
+
+        // only output changes, not everything
+        onlyModified.set(true)
+
+        // the japicmp "old" version is either the user-specified one, or the latest release.
+        val apiBaseVersion: String? by project
+        val baselineVersion = apiBaseVersion ?: latestReleasedVersion
+        oldClasspath.from(
+          try {
+            files(findArtifact(baselineVersion))
+          } catch (e: Exception) {
+            // if we can't find the baseline artifact, this is probably one that's never been published before,
+            // so publish the whole API. We do that by flipping this flag, and comparing the current against nothing.
+            onlyModified.set(false)
+            files()
+          },
+        )
+
+        // Reproduce defaults from https://github.com/melix/japicmp-gradle-plugin/blob/09f52739ef1fccda6b4310cf3f4b19dc97377024/src/main/java/me/champeau/gradle/japicmp/report/ViolationsGenerator.java#L130
+        // with some changes.
+        val exclusions = mutableListOf<String>()
+        // Generics are not detected correctly
+        exclusions.add("CLASS_GENERIC_TEMPLATE_CHANGED")
+        // Allow new default methods on interfaces
+        exclusions.add("METHOD_NEW_DEFAULT")
+        // Allow adding default implementations for default methods
+        exclusions.add("METHOD_ABSTRACT_NOW_DEFAULT")
+        // Bug prevents recognizing default methods of superinterface.
+        // Fixed in https://github.com/siom79/japicmp/pull/343 but not yet available in me.champeau.gradle.japicmp
+        exclusions.add("METHOD_ABSTRACT_ADDED_IN_IMPLEMENTED_INTERFACE")
+        compatibilityChangeExcludes.set(exclusions)
+        richReport {
+          addSetupRule(RecordSeenMembersSetup::class.java)
+          addRule(JApiChangeStatus.NEW, SourceCompatibleRule::class.java)
+          addRule(JApiChangeStatus.MODIFIED, SourceCompatibleRule::class.java)
+          addRule(JApiChangeStatus.UNCHANGED, UnchangedMemberRule::class.java)
+          // Allow new abstract methods on autovalue
+          addRule(AllowNewAbstractMethodOnAutovalueClasses::class.java)
+          addRule(BinaryIncompatibleRule::class.java)
+          // Disallow source incompatible changes, which are allowed by default for some reason
+          addRule(SourceIncompatibleRule::class.java)
+        }
+
+        // this is needed so that we only consider the current artifact, and not dependencies
+        ignoreMissingClasses.set(true)
+        packageExcludes.addAll(
+          "*.internal",
+          "*.internal.*"
+        )
+        annotationExcludes.add("@kotlin.Metadata")
+        val baseVersionString = if (apiBaseVersion == null) "latest" else baselineVersion
+        txtOutputFile.set(
+          apiNewVersion?.let { file("$rootDir/docs/apidiffs/${apiNewVersion}_vs_$baselineVersion/${base.archivesName.get()}.txt") }
+            ?: file("$rootDir/docs/apidiffs/current_vs_$baseVersionString/${base.archivesName.get()}.txt"),
+        )
+      }
+      // have the check task depend on the api comparison task, to make it more likely it will get used.
+      named("check") {
+        dependsOn(jApiCmp)
+      }
+    }
+  }
+}

buildSrc/src/main/kotlin/otel.java-conventions.gradle.kts

@@ -7,6 +7,7 @@ plugins {
 
   id("otel.errorprone-conventions")
   id("otel.spotless-conventions")
+  id("otel.japicmp-conventions")
   id("org.owasp.dependencycheck")
 }
 

docs/apidiffs/current_vs_latest/opentelemetry-aws-xray.txt

@@ -0,0 +1,2 @@
+Comparing source compatibility of opentelemetry-aws-xray-1.50.0-SNAPSHOT.jar against opentelemetry-aws-xray-1.49.0.jar
+No changes.