Skip to content

feat: Add StableApi marker and API diff check#2168

Merged
zeitlinger merged 2 commits into
mainfrom
api-diff-baseline-japicmp
Jun 2, 2026
Merged

feat: Add StableApi marker and API diff check#2168
zeitlinger merged 2 commits into
mainfrom
api-diff-baseline-japicmp

Conversation

@zeitlinger
Copy link
Copy Markdown
Member

@zeitlinger zeitlinger commented Jun 1, 2026

Summary

  • add @StableApi as the opt-in marker for published Java API
  • seed the guessed stable API surface from docs plus Micrometer/JMX usage
  • add mise run api-diff using japicmp against the configured baseline
  • add an API diff workflow that fails on incompatible published API changes

Notes

This is the bootstrap PR for the annotation-based API surface. Since 1.5.1 does not contain
@StableApi, the first diff is noisy and mostly shows the seeded API surface as new. After a
release contains the annotations, future diffs should be normal compatibility diffs.

The workflow does not post PR comments or upload artifacts. If the check fails, run this locally:

mise run api-diff

Reports are written to **/target/japicmp/*.

Intentional incompatible changes can be accepted by adding the PR label
breaking-api-change-accepted.

Validation

  • mise run api-diff
  • mise run build
  • mise run lint

@zeitlinger zeitlinger changed the title Add StableApi marker and API diff check feat: Add StableApi marker and API diff check Jun 1, 2026
@zeitlinger zeitlinger force-pushed the api-diff-baseline-japicmp branch 2 times, most recently from cbd01a5 to e296cbd Compare June 1, 2026 16:56
@zeitlinger zeitlinger added the breaking-api-change-accepted Accept breaking API changes label Jun 1, 2026
@zeitlinger zeitlinger force-pushed the api-diff-baseline-japicmp branch from e296cbd to 974e23a Compare June 1, 2026 17:09
Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>
@zeitlinger zeitlinger force-pushed the api-diff-baseline-japicmp branch from 974e23a to 3431634 Compare June 1, 2026 17:15
baseline_version:
description: Version to compare the PR artifacts against
required: false
default: "1.5.1"
Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

how should we keep this up to date? should we create an issue to add a post-release step automation?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

created #2170

Comment thread docs/stable-api-rationale.md Outdated
Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>
@zeitlinger zeitlinger merged commit 768fd3a into main Jun 2, 2026
18 checks passed
@zeitlinger zeitlinger deleted the api-diff-baseline-japicmp branch June 2, 2026 09:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

breaking-api-change-accepted Accept breaking API changes

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants