Integrate Kotlin binary compatibility validator.

.circleci/config.yml

@@ -23,6 +23,9 @@ workflows:
       - verify-docs:
           requires:
             - verify-code
+      - verify-kotlin-binary-compatibility:
+          requires:
+            - verify-code
       - verify-api:
           requires:
             - verify-code
@@ -372,6 +375,17 @@ jobs:
           name: docs
           command: sh scripts/kdoc-validate.sh
 
+  verify-kotlin-binary-compatibility:
+    executor: ubuntu
+    steps:
+      - checkout
+      - restore-gradle-cache
+      - run:
+          no_output_timeout: 30m
+          name: verify-kotlin-binary-compatibility
+          command: |
+            ./gradlew apiCheck
+
   verify-api:
     executor: ubuntu
     steps:

.github/pull_request_template.md

@@ -33,6 +33,7 @@ If this PR introduces user-facing changes, please note them here.
  - [ ] Optimize code for java consumption (`@JvmOverloads`, `@file:JvmName`, etc).
  - [ ] Add example if relevant.
  - [ ] Document any changes to public APIs.
+ - [ ] Run `./gradlew apiDump` to update generated api files, if there's public API changes, otherwise the `verify-kotlin-binary-compatibility` CI will fail.
  - [ ] Apply changelog label ('breaking change', 'bug :beetle:', 'build', 'docs', 'feature :green_apple:', 'performance :zap:', 'testing :100:') or use the label 'skip changelog'
  - [ ] Add an entry inside this element for inclusion in the `mapbox-maps-android` changelog: `<changelog></changelog>`.
  - [ ] If this PR is a `v10.[version]` release branch fix / enhancement, merge it to `main` firstly and then port to `v10.[version]` release branch.

.gitignore

@@ -27,3 +27,4 @@ release-docs/
 release-docs.zip
 /tmp/checksum.txt
 api_compat_report/
+logs/

build.gradle.kts

@@ -50,7 +50,8 @@ allprojects {
 }
 
 plugins {
-  id("org.jetbrains.dokka") version Versions.pluginDokka
+  id(Plugins.dokkaId) version Versions.pluginDokka
+  id(Plugins.binaryCompatibilityValidatorId) version Versions.pluginBinaryCompatibilityValidator
 }
 repositories {
   maven(url = "https://dl.bintray.com/kotlin/dokka")
@@ -60,4 +61,35 @@ tasks.withType<org.jetbrains.dokka.gradle.DokkaTask>().configureEach {
 }
 tasks.withType<Test> {
   maxParallelForks = (Runtime.getRuntime().availableProcessors() / 2).takeIf { it > 0 } ?: 1
+}
+
+apiValidation {
+  /**
+   * Packages that are excluded from public API dumps even if they
+   * contain public API.
+   */
+//  ignoredPackages.add("kotlinx.coroutines.internal")
+
+  /**
+   * Sub-projects that are excluded from API validation
+   */
+  ignoredProjects.addAll(listOf("extension-style-app", "android-auto-app", "app"))
+
+  /**
+   * Classes (fully qualified) that are excluded from public API dumps even if they
+   * contain public API.
+   */
+//  ignoredClasses.add("com.company.BuildConfig")
+
+  /**
+   * Set of annotations that exclude API from being public.
+   * Typically, it is all kinds of `@InternalApi` annotations that mark
+   * effectively private API that cannot be actually private for technical reasons.
+   */
+//  nonPublicMarkers.add("com.mapbox.maps.MapboxExperimental")
+
+  /**
+   * Flag to programmatically disable compatibility validator
+   */
+  validationDisabled = false
 }

buildSrc/src/main/kotlin/Project.kt

@@ -13,6 +13,8 @@ object Plugins {
   const val mapboxAccessToken = "com.mapbox.gradle.plugins:access-token:${Versions.mapboxAccessToken}"
   const val mapboxSdkRegistry = "com.mapbox.gradle.plugins:sdk-registry:${Versions.mapboxSdkRegistry}"
   const val mapboxSdkVersionsPlugin = "com.mapbox.mapboxsdk:mapbox-android-sdk-versions:${Versions.mapboxSdkVersionsPlugin}"
+  const val dokkaId = "org.jetbrains.dokka"
+  const val binaryCompatibilityValidatorId = "org.jetbrains.kotlinx.binary-compatibility-validator"
 }
 
 object Dependencies {
@@ -74,6 +76,7 @@ object Versions {
   const val pluginLicense = "0.8.5"
   const val pluginDokka =  "1.4.10.2"
   const val pluginJacoco = "0.2"
+  const val pluginBinaryCompatibilityValidator = "0.8.0"
   const val mapboxAccessToken="0.2.1"
   const val mapboxSdkRegistry="0.4.0"
   const val mapboxGestures = "0.7.0"

extension-androidauto/api/extension-androidauto.api

@@ -0,0 +1,29 @@
+public final class com/mapbox/maps/extension/androidauto/BuildConfig {
+	public static final field BUILD_TYPE Ljava/lang/String;
+	public static final field DEBUG Z
+	public static final field LIBRARY_PACKAGE_NAME Ljava/lang/String;
+	public static final field VERSION_CODE I
+	public static final field VERSION_NAME Ljava/lang/String;
+	public fun <init> ()V
+}
+
+public abstract interface class com/mapbox/maps/extension/androidauto/MapSurfaceReadyCallback {
+	public abstract fun onMapSurfaceReady (Lcom/mapbox/maps/MapSurface;)V
+}
+
+public final class com/mapbox/maps/extension/androidauto/MapboxCarUtilsKt {
+	public static final fun initMapSurface (Landroidx/car/app/Session;Lcom/mapbox/maps/MapInitOptions;Lcom/mapbox/maps/extension/androidauto/MapSurfaceReadyCallback;)V
+	public static final fun initMapSurface (Landroidx/car/app/Session;Lcom/mapbox/maps/MapInitOptions;Lcom/mapbox/maps/extension/androidauto/OnMapScrollListener;Lcom/mapbox/maps/extension/androidauto/MapSurfaceReadyCallback;)V
+	public static final fun initMapSurface (Landroidx/car/app/Session;Lcom/mapbox/maps/MapInitOptions;Lcom/mapbox/maps/extension/androidauto/OnMapScrollListener;Lcom/mapbox/maps/extension/androidauto/OnMapScaleListener;Lcom/mapbox/maps/extension/androidauto/MapSurfaceReadyCallback;)V
+	public static final fun initMapSurface (Landroidx/car/app/Session;Lcom/mapbox/maps/extension/androidauto/MapSurfaceReadyCallback;)V
+	public static synthetic fun initMapSurface$default (Landroidx/car/app/Session;Lcom/mapbox/maps/MapInitOptions;Lcom/mapbox/maps/extension/androidauto/OnMapScrollListener;Lcom/mapbox/maps/extension/androidauto/OnMapScaleListener;Lcom/mapbox/maps/extension/androidauto/MapSurfaceReadyCallback;ILjava/lang/Object;)V
+}
+
+public abstract interface class com/mapbox/maps/extension/androidauto/OnMapScaleListener {
+	public abstract fun onMapScale ()V
+}
+
+public abstract interface class com/mapbox/maps/extension/androidauto/OnMapScrollListener {
+	public abstract fun onMapScroll ()V
+}
+

extension-localization/api/extension-localization.api

@@ -0,0 +1,15 @@
+public final class com/mapbox/maps/extension/localization/BuildConfig {
+	public static final field BUILD_TYPE Ljava/lang/String;
+	public static final field DEBUG Z
+	public static final field LIBRARY_PACKAGE_NAME Ljava/lang/String;
+	public static final field VERSION_CODE I
+	public static final field VERSION_NAME Ljava/lang/String;
+	public fun <init> ()V
+}
+
+public final class com/mapbox/maps/extension/localization/StyleInterfaceExtensionKt {
+	public static final fun localizeLabels (Lcom/mapbox/maps/extension/style/StyleInterface;Ljava/util/Locale;)V
+	public static final fun localizeLabels (Lcom/mapbox/maps/extension/style/StyleInterface;Ljava/util/Locale;Ljava/util/List;)V
+	public static synthetic fun localizeLabels$default (Lcom/mapbox/maps/extension/style/StyleInterface;Ljava/util/Locale;Ljava/util/List;ILjava/lang/Object;)V
+}
+