feat: track api-diff baseline via Renovate and store diffs in docs/apidiffs

.gitattributes

@@ -1,3 +1,4 @@
 CHANGELOG.md linguist-generated
 **/src/main/generated/** linguist-generated
+docs/apidiffs/** linguist-generated
 docs/** linguist-documentation

.github/renovate-tracked-deps.json

@@ -26,6 +26,11 @@
         "mise"
       ]
     },
+    ".github/workflows/generate-api-diff-baseline.yml": {
+      "regex": [
+        "mise"
+      ]
+    },
     ".github/workflows/generate-protobuf.yml": {
       "regex": [
         "mise"
@@ -176,6 +181,11 @@
       "maven-wrapper": [
         "maven-wrapper"
       ]
+    },
+    "pom.xml": {
+      "regex": [
+        "io.prometheus:prometheus-metrics-core"
+      ]
     }
   }
 }

.github/renovate.json5

@@ -37,6 +37,20 @@
       matchDepNames: ["com.google.protobuf:protobuf-java", "protoc"],
       groupName: "protobuf",
       separateMajorMinor: false,
+    },
+    {
+      description: "Isolate the api-diff baseline on renovate/api-diff-baseline so generate-api-diff-baseline can regenerate docs/apidiffs; merge manually after a close/reopen re-runs CI",
+      matchFileNames: ["pom.xml"],
+      matchPackageNames: ["io.prometheus:prometheus-metrics-core"],
+      groupName: "api-diff-baseline",
+      automerge: false,
+    },
+    {
+      "description": "Flint autofix: align extractVersion for protoc",
+      "extractVersion": "^(?<version>.+)\\.0\\.0$",
+      "matchDepNames": [
+        "protoc"
+      ]
     }
   ],
   customManagers: [
@@ -48,5 +62,13 @@
          "# renovate: datasource=(?<datasource>[a-z-]+?)(?: depName=(?<depName>.+?))?(?: packageName=(?<packageName>.+?))?(?: versioning=(?<versioning>[a-z-]+?))?\\s.+?_VERSION\\s*=\\s*\"?(?<currentValue>[^@\"]+?)(?:@(?<currentDigest>sha256:[a-f0-9]+))?\"?\\s"
        ]
      },
+     {
+       "customType": "regex",
+       "description": "update the api-diff baseline to the latest published release",
+       "managerFilePatterns": ["/^pom\\.xml$/"],
+       "matchStrings": [
+         "<!-- renovate: datasource=(?<datasource>[a-z-]+?) packageName=(?<packageName>.+?) -->\\s*<api\\.diff\\.baseline\\.version>(?<currentValue>[^<]+)</api\\.diff\\.baseline\\.version>"
+       ]
+     },
   ],
 }

.github/scripts/sync-api-diffs.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# Refresh docs/apidiffs/current_vs_latest/ from the japicmp reports produced by
+# `mvn verify -P api-diff`.
+#
+# Each StableApi module gets one committed <module>.txt describing how its
+# published API surface differs from the baseline release
+# (<api.diff.baseline.version> in pom.xml). Committing these makes every API
+# change visible in the pull request diff. The CI check fails when the
+# regenerated files differ from what is committed.
+#
+# The layout and format match opentelemetry-java's docs/apidiffs: the
+# "Comparing ... .jar against ... .jar" header is kept, while the constant
+# ignore-missing-classes warning and the semantic-versioning suggestion are
+# dropped as noise.
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+out_dir="$repo_root/docs/apidiffs/current_vs_latest"
+
+shopt -s nullglob globstar
+
+reports=("$repo_root"/**/target/japicmp/api-diff.diff)
+if [ "${#reports[@]}" -eq 0 ]; then
+	echo "No japicmp reports found. Run 'mvn verify -P api-diff' first." >&2
+	exit 1
+fi
+
+rm -rf "$out_dir"
+mkdir -p "$out_dir"
+
+for report in "${reports[@]}"; do
+	# report path: <repo>/<module path>/target/japicmp/api-diff.diff
+	module="$(basename "$(dirname "$(dirname "$(dirname "$report")")")")"
+	grep -vE '^(WARNING: You are using the option|Semantic versioning suggestion)' \
+		"$report" >"$out_dir/$module.txt"
+done
+
+echo "Wrote ${#reports[@]} API diff report(s) to docs/apidiffs/current_vs_latest/."

.github/workflows/api-diff.yml

@@ -12,9 +12,11 @@ on:
   workflow_dispatch:
     inputs:
       baseline_version:
-        description: Version to compare the PR artifacts against
+        description: >-
+          Override the baseline version to compare against.
+          Defaults to <api.diff.baseline.version> in pom.xml.
         required: false
-        default: "1.5.1"
+        default: ""
 
 permissions:
   contents: read
@@ -23,7 +25,9 @@ jobs:
   api-diff:
     runs-on: ubuntu-24.04
     env:
-      API_DIFF_BASELINE_VERSION: ${{ inputs.baseline_version || '1.5.1' }}
+      # Empty unless overridden via workflow_dispatch; the api-diff task then
+      # falls back to <api.diff.baseline.version> in pom.xml.
+      API_DIFF_BASELINE_VERSION: ${{ inputs.baseline_version }}
       BREAKING_API_CHANGE_ACCEPTED: >-
         ${{ contains(github.event.pull_request.labels.*.name, 'breaking-api-change-accepted') }}
 
@@ -42,6 +46,13 @@ jobs:
           key: ${{ runner.os }}-maven-${{ hashFiles('**/pom.xml') }}
       - name: Run japicmp API diff
         run: mise run api-diff
+      - name: Check docs/apidiffs is up to date
+        run: |
+          if ! git diff --exit-code -- docs/apidiffs; then
+            echo "::error::Published API surface changed but docs/apidiffs is stale."
+            echo "Run 'mise run api-diff' locally and commit the updated docs/apidiffs."
+            exit 1
+          fi
       - name: Fail on incompatible published API changes
         run: |
           python3 - <<'PY'

.github/workflows/generate-api-diff-baseline.yml

@@ -0,0 +1,117 @@
+---
+name: Generate API Diff Baseline
+
+# When Renovate bumps <api.diff.baseline.version> (on the renovate/api-diff-baseline
+# branch), regenerate docs/apidiffs against the new baseline and push the result
+# back onto the PR. Renovate only proposes versions already published to Maven
+# Central, so japicmp can always resolve the new baseline.
+#
+# Before regenerating, the previous current_vs_latest is archived as
+# docs/apidiffs/<new>_vs_<old>/ to keep a per-release history (like
+# opentelemetry-java). This is an approximation of a release-vs-release diff:
+# the archived files compare the dev snapshot (which has just become <new>)
+# against <old>, so any commits merged between the release and this bump are
+# included too.
+#
+# Mirrors generate-protobuf.yml: a read-only `generate` job produces a patch
+# artifact and a privileged `publish` job pushes it back.
+
+on:
+  push:
+    branches:
+      - "renovate/api-diff-baseline"
+
+permissions: {}
+
+jobs:
+  generate:
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: read # checkout + read-only `git fetch origin main` for the verify step
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          ref: ${{ github.ref }}
+          persist-credentials: false
+      - uses: jdx/mise-action@1648a7812b9aeae629881980618f079932869151 # v4.0.1
+        with:
+          version: v2026.5.18
+          sha256: cfac593469d028d7ae5fe36e37bd7c59118b5238e92d8a876209578464f24a84
+      - name: Cache local Maven repository
+        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+        with:
+          path: ~/.m2/repository
+          key: ${{ runner.os }}-maven-${{ hashFiles('**/pom.xml') }}
+          restore-keys: |
+            ${{ runner.os }}-maven-
+      - name: Archive the previous current_vs_latest
+        run: |
+          git fetch origin main
+          baseline() {
+            grep -oP '(?<=<api\.diff\.baseline\.version>)[^<]+' "$1"
+          }
+          OLD=$(git show origin/main:pom.xml | baseline /dev/stdin)
+          NEW=$(baseline pom.xml)
+          if [[ -z "$OLD" || -z "$NEW" ]]; then
+            echo "::error::Could not read api.diff.baseline.version"
+            exit 1
+          fi
+          if [[ "$OLD" == "$NEW" ]]; then
+            echo "::error::api.diff.baseline.version unchanged ($NEW); nothing to bump"
+            exit 1
+          fi
+          if [[ -d docs/apidiffs/current_vs_latest ]]; then
+            cp -r docs/apidiffs/current_vs_latest "docs/apidiffs/${NEW}_vs_${OLD}"
+            echo "Archived current_vs_latest as ${NEW}_vs_${OLD}"
+          fi
+      - name: Regenerate docs/apidiffs
+        run: mise run api-diff
+      - name: Validate and export docs/apidiffs as a patch
+        run: |
+          # Stage first so newly added files (the archived dir) are captured.
+          git add docs/apidiffs
+          OUTSIDE=$(git status --porcelain -- ':(exclude)docs/apidiffs')
+          if [[ -n "$OUTSIDE" ]]; then
+            echo "::error::Unexpected changes outside docs/apidiffs:"
+            echo "$OUTSIDE"
+            exit 1
+          fi
+          git diff --cached -- docs/apidiffs > /tmp/api-diff-baseline.patch
+      - name: Upload generated patch
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: api-diff-baseline-patch
+          path: /tmp/api-diff-baseline.patch
+          retention-days: 5
+
+  publish:
+    runs-on: ubuntu-24.04
+    needs: generate
+    permissions:
+      contents: write # push regenerated docs/apidiffs back to the renovate branch
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          ref: ${{ github.ref }}
+          # zizmor: ignore[artipacked] -- needs credentials to push
+          persist-credentials: true
+      - name: Download generated patch
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: api-diff-baseline-patch
+          path: /tmp/patch
+      - name: Commit and push regenerated docs/apidiffs
+        run: |
+          PATCH=/tmp/patch/api-diff-baseline.patch
+          if [[ ! -s "$PATCH" ]]; then
+            echo "No regenerated changes to commit"
+            exit 0
+          fi
+          git apply "$PATCH"
+          # Note: GITHUB_TOKEN pushes don't trigger CI re-runs.
+          # Close and reopen the PR to trigger CI after this commit.
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add docs/apidiffs
+          git commit -m "chore: regenerate docs/apidiffs"
+          git push

.mise/lib/jmx_exporter_compat.py

@@ -97,6 +97,12 @@ def install_local_artifacts(root_dir: Path = Path.cwd()) -> None:
             # our main artifacts, and our test sources target a newer release than
             # the compatibility JDK supports.
             "-Dmaven.test.skip=true",
+            # Deactivate the activeByDefault profiles that add test-only
+            # dependencies (incl. a test-jar). With maven.test.skip those are not
+            # built, so leaving the profile active breaks dependency resolution.
+            # Same approach the release task uses (-P 'release,!default').
+            "-P",
+            "!default",
             "-Dcoverage.skip=true",
             "-Dcheckstyle.skip=true",
             "-Dwarnings=-nowarn",

.mise/lib/micrometer_compat.py

@@ -129,6 +129,12 @@ def install_local_artifacts(root_dir: Path = Path.cwd()) -> None:
             # our main artifacts, and our test sources target a newer release than
             # the compatibility JDK supports.
             "-Dmaven.test.skip=true",
+            # Deactivate the activeByDefault profiles that add test-only
+            # dependencies (incl. a test-jar). With maven.test.skip those are not
+            # built, so leaving the profile active breaks dependency resolution.
+            # Same approach the release task uses (-P 'release,!default').
+            "-P",
+            "!default",
             "-Dcoverage.skip=true",
             "-Dcheckstyle.skip=true",
             "-Dwarnings=-nowarn",