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

Derive the api-diff baseline from the latest published release instead of a
hardcoded version, and commit per-module diffs so API changes are visible in
review.

- Move the baseline to the <api.diff.baseline.version> pom property (the single
  source of truth) and let Renovate bump it: a custom regex manager tracks the
  latest published io.prometheus:prometheus-metrics-core on Maven Central, on
  the renovate/api-diff-baseline branch.
- generate-api-diff-baseline.yml regenerates docs/apidiffs on that branch and
  pushes the result back (mirrors generate-protobuf.yml).
- mise run api-diff now syncs japicmp reports into docs/apidiffs via
  .github/scripts/sync-api-diffs.sh (volatile preamble stripped so files only
  churn on real API changes); the api-diff workflow fails if they are stale.
- Mark docs/apidiffs as generated so flint skips it.

Closes #2170
Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>

Author: zeitlinger

.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,37 @@
+#!/usr/bin/env bash
+# Refresh docs/apidiffs/ from the japicmp reports produced by `mvn verify -P api-diff`.
+#
+# Each StableApi module gets one committed <module>.diff 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 two-line japicmp preamble (the "Comparing ...SNAPSHOT.jar against
+# ...<baseline>.jar" line and the constant ignore-missing-classes warning) is
+# stripped so the files only churn on real API changes, not on every version or
+# snapshot bump.
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+out_dir="$repo_root/docs/apidiffs"
+
+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 '^(Comparing source compatibility of|WARNING: You are using the option)' \
+		"$report" >"$out_dir/$module.diff"
+done
+
+echo "Wrote ${#reports[@]} API diff report(s) to docs/apidiffs/."

.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,95 @@
+---
+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.
+#
+# 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: Verify the baseline version was updated
+        run: |
+          git fetch origin main
+          if ! git diff origin/main -- pom.xml | grep -q 'api.diff.baseline.version'; then
+            echo "::error::api.diff.baseline.version not updated in pom.xml"
+            exit 1
+          fi
+      - name: Regenerate docs/apidiffs
+        run: mise run api-diff
+      - name: Validate and export docs/apidiffs as a patch
+        run: |
+          UNEXPECTED=$(git diff --name-only | grep -v '^docs/apidiffs/' || true)
+          if [[ -n "$UNEXPECTED" ]]; then
+            echo "::error::Unexpected files changed:"
+            echo "$UNEXPECTED"
+            exit 1
+          fi
+          git diff > /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