[DRAFT] Add Metalava API signature generation and compatibility tracking

[rahul-lohra]

STILL IN DRAFT, CI PPL IS NOT TESTED

Goal

Add automated public API surface tracking using Metalava to detect breaking API changes before they reach develop. This gives us a Java/Android-aware API signature file (api/current.txt) per module — complementing the existing binary-compatibility-validator .api files.

Implementation

Convention Plugin (io.getstream.video.android.metalava)

All metalava setup is encapsulated in a reusable convention plugin inside build-logic/. This keeps module build files minimal and makes it easy to share across repos.

Files added:

• build-logic/convention/src/main/kotlin/MetalavaConventionPlugin.kt — Plugin entry point
• build-logic/convention/src/main/kotlin/io/getstream/video/MetalavaSetup.kt — Shared configuration logic

What the convention plugin does automatically:

• Applies the me.tylerbwong.gradle.metalava plugin (v0.5.0)
• Outputs API signature to api/current.txt
• Suppresses known lint issues for internal API references (ReferencesHidden, HiddenTypeParameter, UnavailableSymbol, IoError)
• Hooks metalavaGenerateSignatureRelease into apiDump so both files are generated together
• Respects metalava.enabled Gradle property for toggling on/off

CI Workflow (.github/workflows/api-compatibility-check.yml)

Runs on PRs to develop/main:

1. Checks API compatibility against committed api/current.txt
2. If breaking changes detected → generates a diff in the Job Summary
3. Blocks merge unless the approved-api-change label is added
4. Re-triggers automatically when the label is added

---

How to Integrate Into a Module

Simple module (no customization needed) — 1 line:

plugins {
    id("io.getstream.video.android.library")
    id("io.getstream.video.android.metalava")  // ← add this
}

Module with hidden annotations (e.g., internal APIs):

plugins {
    id("io.getstream.video.android.library")
    id("io.getstream.video.android.metalava")
}

metalava {
    hiddenAnnotations.set(
        setOf("com.example.internal.InternalApi"),
    )
}

Available Gradle Tasks

Task	Description
apiDump	img

Task	Description
apiDump	Generates both .api and api/current.txt files (metalava hooks into this automatically)
metalavaGenerateSignatureRelease	Generates api/current.txt for release variant
metalavaGenerateSignatureDebug	Generates api/current.txt for debug variant
metalavaCheckCompatibilityRelease	Checks current code against committed api/current.txt — fails on breaking changes
metalavaCheckCompatibilityDebug	Same as above for debug variant

Examples:

# Generate API files (recommended — runs both binary-compat-validator + metalava)
./gradlew apiDump

# Check for breaking changes
./gradlew metalavaCheckCompatibilityRelease

# Run for a specific module
./gradlew :stream-video-android-core:metalavaCheckCompatibilityRelease

How to Disable Metalava

# Per-invocation
./gradlew apiDump -Pmetalava.enabled=false

# Permanently (in gradle.properties)
metalava.enabled=false

When disabled, apiDump still generates .api files as before — only metalava tasks are skipped.

Modules Enabled

[x] stream-video-android-core
[x] stream-video-android-ui-core

🎨 UI Changes

None

Testing

Todo [WIP]

Run ./gradlew apiDump and verify both api/current.txt and .api files are generated
Run ./gradlew metalavaCheckCompatibilityRelease and verify it passes with no changes
Make a breaking API change (e.g., remove a public method), run metalavaCheckCompatibilityRelease, and verify it fails
Run ./gradlew apiDump -Pmetalava.enabled=false and verify metalava tasks are skipped
Verify CI workflow runs on PR and blocks merge on breaking changes
Verify adding approved-api-change label allows the PR to pass

[github-actions]

PR checklist ❌

The following issues were detected:

• Missing required label: at least one label starting with pr:.

What we check

1. Title is concise (5–18 words) unless labeled pr:ignore-for-release.
2. At least one pr: label exists (e.g., pr:bug, pr:new-feature).
3. Sections ### Goal, ### Implementation, and ### Testing contain content.

[aleksandar-apostolov]

Note to self: We should look for a way to add binary compatibility check in conventions.

[github-actions]

SDK Size Comparison 📏

SDK	Before	After	Difference	Status
stream-video-android-core	12.00 MB	12.00 MB	0.00 MB	🟢
stream-video-android-ui-xml	5.68 MB	5.68 MB	0.00 MB	🟢
stream-video-android-ui-compose	6.27 MB	6.27 MB	0.00 MB	🟢

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud