feat: Add StableApi marker and API diff check

.github/renovate-tracked-deps.json

@@ -16,6 +16,11 @@
         "mise"
       ]
     },
+    ".github/workflows/api-diff.yml": {
+      "regex": [
+        "mise"
+      ]
+    },
     ".github/workflows/build.yml": {
       "regex": [
         "mise"

.github/workflows/api-diff.yml

@@ -0,0 +1,79 @@
+---
+name: API Diff
+
+on:
+  pull_request:
+    types:
+      - opened
+      - synchronize
+      - reopened
+      - labeled
+      - unlabeled
+  workflow_dispatch:
+    inputs:
+      baseline_version:
+        description: Version to compare the PR artifacts against
+        required: false
+        default: "1.5.1"
+
+permissions:
+  contents: read
+
+jobs:
+  api-diff:
+    runs-on: ubuntu-24.04
+    env:
+      API_DIFF_BASELINE_VERSION: ${{ inputs.baseline_version || '1.5.1' }}
+      BREAKING_API_CHANGE_ACCEPTED: >-
+        ${{ contains(github.event.pull_request.labels.*.name, 'breaking-api-change-accepted') }}
+
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          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') }}
+      - name: Run japicmp API diff
+        run: mise run api-diff
+      - name: Fail on incompatible published API changes
+        run: |
+          python3 - <<'PY'
+          import os
+          from pathlib import Path
+          import sys
+          import xml.etree.ElementTree as ET
+
+          failures = []
+          for report in sorted(Path(".").glob("**/target/japicmp/api-diff.xml")):
+              parts = report.parts
+              module = "/".join(parts[: parts.index("target")])
+              tree = ET.parse(report)
+              for change in tree.findall(".//compatibilityChange"):
+                  binary = change.get("binaryCompatible") == "false"
+                  source = change.get("sourceCompatible") == "false"
+                  if binary or source:
+                      failures.append((module, change.get("type", "unknown")))
+
+          if not failures:
+              print("No incompatible published API changes detected.")
+              sys.exit(0)
+
+          print("Incompatible published API changes detected:")
+          for module, change_type in failures[:100]:
+              print(f"- {module}: {change_type}")
+          if len(failures) > 100:
+              print(f"... and {len(failures) - 100} more")
+          if os.environ.get("BREAKING_API_CHANGE_ACCEPTED") == "true":
+              print("Accepted by PR label `breaking-api-change-accepted`.")
+              sys.exit(0)
+          print("Run `mise run api-diff` locally for full japicmp output.")
+          print("Reports are written to `**/target/japicmp/*`.")
+          sys.exit(1)
+          PY

.github/workflows/codeql.yml

@@ -49,6 +49,7 @@ jobs:
       - name: Build (CodeQL traces the build)
         run: >
           ./mvnw clean compile
+          -P '!default'
           -DskipTests
           -Dcoverage.skip=true
           -Dcheckstyle.skip=true

mise.toml

@@ -59,6 +59,19 @@ run = "./mvnw verify"
 description = "build all modules without tests"
 run = "./mvnw install -DskipTests -Dcoverage.skip=true"
 
+[tasks."api-diff"]
+description = "Compare published API against the configured japicmp baseline"
+run = """
+BASELINE_VERSION="${API_DIFF_BASELINE_VERSION:-1.5.1}"
+./mvnw -B verify \
+  -P 'api-diff,!examples-and-integration-tests' \
+  -Dapi.diff.baseline.version="${BASELINE_VERSION}" \
+  -DskipTests \
+  -Dcoverage.skip=true \
+  -Dcheckstyle.skip=true \
+  -Dwarnings=-nowarn
+"""
+
 [tasks."lint"]
 description = "Run all lints"
 depends = ["lint:bom"]

pom.xml

@@ -29,6 +29,7 @@
     <otel.instrumentation.version>2.28.1-alpha</otel.instrumentation.version>
     <java.version>8</java.version>
     <test.java.version>25</test.java.version>
+    <api.diff.baseline.version>1.5.1</api.diff.baseline.version>
     <jacoco.line-coverage>0.70</jacoco.line-coverage>
     <checkstyle.skip>false</checkstyle.skip>
     <coverage.skip>false</coverage.skip>
@@ -38,6 +39,7 @@
 
   <modules>
     <module>prometheus-metrics-parent</module>
+    <module>prometheus-metrics-annotations</module>
     <module>prometheus-metrics-bom</module>
     <module>prometheus-metrics-core</module>
     <module>prometheus-metrics-config</module>
@@ -171,6 +173,11 @@
           <artifactId>exec-maven-plugin</artifactId>
           <version>3.6.3</version>
         </plugin>
+        <plugin>
+          <groupId>com.github.siom79.japicmp</groupId>
+          <artifactId>japicmp-maven-plugin</artifactId>
+          <version>0.26.1</version>
+        </plugin>
       </plugins>
     </pluginManagement>
     <plugins>
@@ -401,6 +408,71 @@
         </plugins>
       </build>
     </profile>
+    <profile>
+      <id>api-diff</id>
+      <build>
+        <plugins>
+          <plugin>
+            <groupId>com.github.siom79.japicmp</groupId>
+            <artifactId>japicmp-maven-plugin</artifactId>
+            <configuration>
+              <oldVersion>
+                <dependency>
+                  <groupId>${project.groupId}</groupId>
+                  <artifactId>${project.artifactId}</artifactId>
+                  <version>${api.diff.baseline.version}</version>
+                  <type>jar</type>
+                </dependency>
+              </oldVersion>
+              <newVersion>
+                <file>
+                  <path>${project.build.directory}/${project.build.finalName}.jar</path>
+                </file>
+              </newVersion>
+              <parameter>
+                <accessModifier>public</accessModifier>
+                <onlyModified>true</onlyModified>
+                <includes>
+                  <include>io.prometheus.metrics.annotations.StableApi</include>
+                  <include>@io.prometheus.metrics.annotations.StableApi</include>
+                </includes>
+                <excludes>
+                  <exclude>io.prometheus.metrics.expositionformats.generated</exclude>
+                  <exclude>io.prometheus.metrics.shaded</exclude>
+                </excludes>
+                <breakBuildOnModifications>false</breakBuildOnModifications>
+                <breakBuildOnBinaryIncompatibleModifications>
+                  false
+                </breakBuildOnBinaryIncompatibleModifications>
+                <breakBuildOnSourceIncompatibleModifications>
+                  false
+                </breakBuildOnSourceIncompatibleModifications>
+                <breakBuildBasedOnSemanticVersioning>false</breakBuildBasedOnSemanticVersioning>
+                <ignoreMissingClasses>true</ignoreMissingClasses>
+                <ignoreMissingOldVersion>true</ignoreMissingOldVersion>
+                <ignoreMissingOptionalDependency>true</ignoreMissingOptionalDependency>
+                <skipPomModules>true</skipPomModules>
+                <skipHtmlReport>true</skipHtmlReport>
+                <reportOnlyFilename>true</reportOnlyFilename>
+                <packagingSupporteds>
+                  <packagingSupported>bundle</packagingSupported>
+                  <packagingSupported>jar</packagingSupported>
+                </packagingSupporteds>
+              </parameter>
+            </configuration>
+            <executions>
+              <execution>
+                <id>api-diff</id>
+                <phase>verify</phase>
+                <goals>
+                  <goal>cmp</goal>
+                </goals>
+              </execution>
+            </executions>
+          </plugin>
+        </plugins>
+      </build>
+    </profile>
     <profile>
       <id>errorprone</id>
       <activation>

prometheus-metrics-annotations/pom.xml

@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+
+  <parent>
+    <groupId>io.prometheus</groupId>
+    <artifactId>client_java</artifactId>
+    <version>1.6.2-SNAPSHOT</version>
+  </parent>
+
+  <artifactId>prometheus-metrics-annotations</artifactId>
+  <packaging>bundle</packaging>
+
+  <name>Prometheus Metrics Annotations</name>
+  <description>
+    Annotations for Prometheus Metrics library API contracts.
+  </description>
+
+  <properties>
+    <automatic.module.name>io.prometheus.metrics.annotations</automatic.module.name>
+  </properties>
+</project>

prometheus-metrics-annotations/src/main/java/io/prometheus/metrics/annotations/StableApi.java

@@ -0,0 +1,22 @@
+package io.prometheus.metrics.annotations;
+
+import static java.lang.annotation.ElementType.CONSTRUCTOR;
+import static java.lang.annotation.ElementType.FIELD;
+import static java.lang.annotation.ElementType.METHOD;
+import static java.lang.annotation.ElementType.TYPE;
+import static java.lang.annotation.RetentionPolicy.CLASS;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.Retention;
+import java.lang.annotation.Target;
+
+/**
+ * Marks a Java element as part of the stable, published Prometheus Metrics API.
+ *
+ * <p>Use this on public or protected types to publish the type and its members. Use it on
+ * individual constructors, methods, and fields when only part of a public type is stable.
+ */
+@Documented
+@Retention(CLASS)
+@Target({TYPE, CONSTRUCTOR, METHOD, FIELD})
+public @interface StableApi {}

prometheus-metrics-bom/pom.xml

@@ -19,6 +19,11 @@
 
   <dependencyManagement>
     <dependencies>
+      <dependency>
+        <groupId>io.prometheus</groupId>
+        <artifactId>prometheus-metrics-annotations</artifactId>
+        <version>${project.version}</version>
+      </dependency>
       <dependency>
         <groupId>io.prometheus</groupId>
         <artifactId>prometheus-metrics-config</artifactId>

prometheus-metrics-config/pom.xml

@@ -21,6 +21,12 @@
   </properties>
 
   <dependencies>
+    <dependency>
+      <groupId>io.prometheus</groupId>
+      <artifactId>prometheus-metrics-annotations</artifactId>
+      <version>${project.version}</version>
+      <optional>true</optional>
+    </dependency>
     <dependency>
       <groupId>org.junit-pioneer</groupId>
       <artifactId>junit-pioneer</artifactId>

prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/EscapingScheme.java

@@ -1,7 +1,9 @@
 package io.prometheus.metrics.config;
 
+import io.prometheus.metrics.annotations.StableApi;
 import javax.annotation.Nullable;
 
+@StableApi
 public enum EscapingScheme {
   /** NO_ESCAPING indicates that a name will not be escaped. */
   ALLOW_UTF8("allow-utf-8"),

prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/ExemplarsProperties.java

@@ -1,8 +1,10 @@
 package io.prometheus.metrics.config;
 
+import io.prometheus.metrics.annotations.StableApi;
 import javax.annotation.Nullable;
 
 /** Properties starting with io.prometheus.exemplars */
+@StableApi
 public class ExemplarsProperties {
 
   private static final String PREFIX = "io.prometheus.exemplars";

prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/ExporterFilterProperties.java

@@ -1,12 +1,14 @@
 package io.prometheus.metrics.config;
 
+import io.prometheus.metrics.annotations.StableApi;
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.Collections;
 import java.util.List;
 import javax.annotation.Nullable;
 
 /** Properties starting with io.prometheus.exporter.filter */
+@StableApi
 public class ExporterFilterProperties {
 
   public static final String METRIC_NAME_MUST_BE_EQUAL_TO = "metric_name_must_be_equal_to";

prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/ExporterHttpServerProperties.java

@@ -1,8 +1,10 @@
 package io.prometheus.metrics.config;
 
+import io.prometheus.metrics.annotations.StableApi;
 import javax.annotation.Nullable;
 
 /** Properties starting with io.prometheus.exporter.http_server */
+@StableApi
 public class ExporterHttpServerProperties {
 
   private static final String PORT = "port";

prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/ExporterOpenTelemetryProperties.java

@@ -1,5 +1,6 @@
 package io.prometheus.metrics.config;
 
+import io.prometheus.metrics.annotations.StableApi;
 import java.util.HashMap;
 import java.util.Map;
 import javax.annotation.Nullable;
@@ -31,6 +32,7 @@
  *     href="https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/">OpenTelemetry
  *     SDK Environment Variables</a>
  */
+@StableApi
 public class ExporterOpenTelemetryProperties {
 
   // See

prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/ExporterProperties.java

@@ -1,8 +1,10 @@
 package io.prometheus.metrics.config;
 
+import io.prometheus.metrics.annotations.StableApi;
 import javax.annotation.Nullable;
 
 /** Properties starting with io.prometheus.exporter */
+@StableApi
 public class ExporterProperties {
 
   private static final String INCLUDE_CREATED_TIMESTAMPS = "include_created_timestamps";

prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/ExporterPushgatewayProperties.java

@@ -1,8 +1,10 @@
 package io.prometheus.metrics.config;
 
+import io.prometheus.metrics.annotations.StableApi;
 import java.time.Duration;
 import javax.annotation.Nullable;
 
+@StableApi
 public class ExporterPushgatewayProperties {
 
   private static final String ADDRESS = "address";

prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/MetricsProperties.java

@@ -2,12 +2,14 @@
 
 import static java.util.Collections.unmodifiableList;
 
+import io.prometheus.metrics.annotations.StableApi;
 import java.util.ArrayList;
 import java.util.Collections;
 import java.util.List;
 import javax.annotation.Nullable;
 
 /** Properties starting with io.prometheus.metrics */
+@StableApi
 public class MetricsProperties {
 
   private static final String EXEMPLARS_ENABLED = "exemplars_enabled";