feat!: migrate android-maps-ktx into android-maps-utils (v6.0.0)

[dkhawk]

Summary

Migrates all Kotlin extensions from android-maps-ktx (maps-ktx and maps-utils-ktx) directly into android-maps-utils, establishing v6.0.0 as the consolidated, single-source release for both Java utilities and Kotlin Coroutine/Flow extensions.

Key Changes

1. Consolidated Kotlin Extensions:
   • Reactive coroutine suspensions (awaitMap(), awaitMapsSdkInitialized(), awaitAnimateCamera()).
   • Reactive Flow event streams (mapClickEvents(), cameraMoveEvents(), markerClickEvents()).
   • DSL option builders (addMarker { ... }, addPolyline { ... }, addPolygon { ... }).
2. Canonical & Compatibility Packages:
   • All extensions and builders live under canonical com.google.maps.android.* packages.
   • Preserves com.google.maps.android.ktx.* with @Deprecated(level = DeprecationLevel.WARNING) forwarding wrappers and typealiases for seamless backward compatibility.
3. Release Please Configuration:
   • Configured release-please-config.json and .release-please-manifest.json for final v6.0.0 stable release.
   • Updated documentation (README.md, MIGRATION.md, llm-integration-prompt.md, .gemini/skills/android-maps-utils/SKILL.md).
4. Rebase & Test Validation:
   • Rebased onto latest main (e8ef093c, Kover migration).
   • 100% unit tests pass across all modules (:library, :clustering, :data, :heatmaps, :ui, :demo).

[googlemaps-bot]

Code Coverage

Overall Project	54.58% -1.78%	🍏
Files changed	77.27%	🍏

Module	Coverage
Kover Gradle Plugin XML report for :library	89% -6.5%	🍏
Kover Gradle Plugin XML report for :heatmaps	85.02% -3.61%	❌
Kover Gradle Plugin XML report for :data	50.48% -1.02%	❌
Kover Gradle Plugin XML report for :clustering	32.93%	🍏

Files

Module	File	Coverage
Kover Gradle Plugin XML report for :library	SupportStreetViewPanoramaFragment.kt	100%	🍏
	MapView.kt	100%	🍏
	MapFragment.kt	100%	🍏
	SupportMapFragment.kt	100%	🍏
	StreetViewPanoramaFragment.kt	100%	🍏
	Polyline.kt	100%	🍏
	LatLng.kt	100%	🍏
	SupportStreetViewPanoramaFragment.kt	100%	🍏
	MapView.kt	100%	🍏
	SupportMapFragment.kt	100%	🍏
	Polyline.kt	100%	🍏
	LatLng.kt	100%	🍏
	StreetViewPanoramaView.kt	100%	🍏
	MapFragment.kt	100%	🍏
	MapsInitializer.kt	100%	🍏
	StreetViewPanoramaFragment.kt	100%	🍏
	PolylineOptions.kt	100%	🍏
	MarkerOptions.kt	100%	🍏
	PolygonOptions.kt	100%	🍏
	CircleOptions.kt	100%	🍏
	StreetViewPanoramaOrientation.kt	100%	🍏
	CameraPosition.kt	100%	🍏
	GroundOverlayOptions.kt	100%	🍏
	TileOverlayOptions.kt	100%	🍏
	StreetViewPanoramaCamera.kt	100%	🍏
	PolylineOptions.kt	100%	🍏
	MarkerOptions.kt	100%	🍏
	PolygonOptions.kt	100%	🍏
	CircleOptions.kt	100%	🍏
	StreetViewPanoramaOrientation.kt	100%	🍏
	CameraPosition.kt	100%	🍏
	GroundOverlayOptions.kt	100%	🍏
	TileOverlayOptions.kt	100%	🍏
	StreetViewPanoramaCamera.kt	100%	🍏
	MarkerManagerFlows.kt	91.2% -8.8%	🍏
	FusedLocationProvider.kt	84.62% -15.38%	🍏
	LocationManager.kt	84.62% -15.38%	🍏
	GoogleMap.kt	83.83% -16.17%	🍏
	Polygon.kt	80.95% -19.05%	🍏
	PolylineManagerFlows.kt	78% -22%	🍏
	GroundOverlayManagerFlows.kt	78% -22%	🍏
	PolygonManagerFlows.kt	78% -22%	🍏
	CircleManagerFlows.kt	78% -22%	🍏
	Polygon.kt	70.73% -29.27%	🍏
	MapsInitializer.kt	66.67% -33.33%	🍏
	MarkerManager.kt	60% -40%	🍏
	FusedLocationProvider.kt	38.46% -61.54%	❌
	LocationManager.kt	35.71% -64.29%	❌
	PolygonManager.kt	33.33% -66.67%	❌
	CircleManager.kt	33.33% -66.67%	❌
	GroundOverlayManager.kt	33.33% -66.67%	❌
	PolylineManager.kt	33.33% -66.67%	❌
	GoogleMap.kt	28.44% -71.56%	❌
	StreetViewPanoramaView.kt	27.27% -72.73%	❌
Kover Gradle Plugin XML report for :heatmaps	Heatmap.kt	15.15% -84.85%	❌
	Heatmap.kt	13.73% -86.27%	❌
Kover Gradle Plugin XML report for :data	GeoJson.kt	0%	❌
	GeoJson.kt	0%	❌
	Kml.kt	0%	❌
	Kml.kt	0%	❌
Kover Gradle Plugin XML report for :clustering	ClusterManagerFlows.kt	100%	🍏
	ClusterManager.kt	100%	🍏
	Point.kt	100%	🍏
	PointExtensions.kt	100%	🍏

[LoyalAbbas]

test case is false positive.

If we pass any Marker value here, still this test will pass, because the assertion line is dead code that gets cancelled before execution.

Solution :

Use async { ... } and deferred.await()
Using async instead of launch is cleaner, shorter, and eliminates manual job.cancel() calls altogether:

@Test
public fun testMarkerCollectionClickEvents(): Unit = runTest {
    val deferred = async {
        markerCollection.clickEvents().first()
    }
    advanceUntilIdle()
    // Trigger the event via our tracked active listener slot!
    assertThat(activeMarkerClickListener).isNotNull()
    activeMarkerClickListener?.onMarkerClick(marker)

    assertThat(deferred.await()).isEqualTo(marker)
}

Note : We need to do similar kind of handling in other test cases also

[dkhawk]

Fixed in 85cb2fbf — refactored all Flow tests in CollectionManagersTest.kt (both canonical and KTX suites) to use async(start = CoroutineStart.UNDISPATCHED) { ... .first() } + deferred.await().

[LoyalAbbas]

any specific reason, why we use this instead of "org.mockito.kotlin:mockito-kotlin" lib ?

[dkhawk]

Migrated from com.nhaarman.mockitokotlin2:mockito-kotlin:2.2.0 to org.mockito.kotlin:mockito-kotlin:5.4.0 in 85cb2fbf and updated all test imports to org.mockito.kotlin.*.

[LoyalAbbas]

duplicate call

[dkhawk]

Removed the duplicate testImplementation declarations across library/build.gradle.kts, clustering/build.gradle.kts, data/build.gradle.kts, heatmaps/build.gradle.kts, and ui/build.gradle.kts in 85cb2fbf.

[kikoso]

Second pass, this time anchored to the specific files. Most of it is packaging and release config rather than the Kotlin itself, plus one follow up on the inline thread.

[kikoso]

These six functions are public and return Flow<...>, but clustering/build.gradle.kts still has implementation(libs.kotlinx.coroutines.android). The api(coroutines) you added to :library doesn't help either, since clustering depends on it with implementation.

So the published POM for android-maps-utils-clustering puts coroutines at runtime scope, and an app calling clusterClickEvents() gets "cannot access class kotlinx.coroutines.flow.Flow". Our unit tests won't catch it because they compile inside the module.

Can you move it to api(libs.kotlinx.coroutines.core) and check the other modules while you're there?

[dkhawk]

Fixed in 85cb2fbf — changed kotlinx-coroutines-core to api(libs.kotlinx.coroutines.core) and kept kotlinx-coroutines-android as implementation(libs.kotlinx.coroutines.android) in clustering/build.gradle.kts.

[kikoso]

Only coroutines-core is actually in our API surface. coroutines-android is just the Dispatchers.Main artifact, so implementation is enough for it.

Separately on line 66: api(play-services-location) means everyone pulling maps-utils now gets play-services-location, including people who only wanted :data or :heatmaps. AGENTS.md also asks for an issue before adding deps to library modules. See my note on the demo file about where this package should live.

One more while this file is open: explicitApi() isn't enabled anywhere and we have no binary compatibility validator, yet we're adding roughly 200 public symbols in a major. All the new code already writes public explicitly so flipping explicitApi() on is nearly free, and an .api dump in version control would back up the compatibility promise the shim layer is making. Happy for that to be a follow up if you'd rather not grow this PR.

[dkhawk]

Fixed in 85cb2fbf & 7077a63d — changed kotlinx-coroutines-core to api(...), kotlinx-coroutines-android to implementation(...), and play-services-location to compileOnly(...) (with -dontwarn com.google.android.gms.location.** in library/consumer-rules.pro), so play-services-location is omitted from the published POM and only required by consumers who actually invoke FusedLocationProviderClient extensions.

For explicitApi() and Binary Compatibility Validator (.api dumps), filed #1794 as a fast-follow assigned to me so we can enable explicitApi() and check in baseline .api dumps across all published modules right after this lands.

[kikoso]

This registers the attribution initializer a second time, so both it and the canonical one call addInternalUsageAttributionId with the same value on every app start.

The shim class is also internal, so nobody outside the module could ever have referenced it and the @Deprecated on it does nothing. I'd delete both the shim class and this manifest entry.

[dkhawk]

Fixed in 85cb2fbf — removed the duplicate com.google.maps.android.ktx.utils.attribution.AttributionIdInitializer entry from library/src/main/AndroidManifest.xml and deleted the duplicate class.

[kikoso]

AGENTS.md says not to hand edit this or CHANGELOG.md. The title is already feat!: so release-please lands on 6.0.0 by itself. Can we revert both and let it do its job?

Also worth checking: the description says final 6.0.0, but release-please-config.json is untouched and still has "prerelease": true with "prerelease-type": "rc". As it stands the next run gives us 6.0.0-rc05, not 6.0.0.

[dkhawk]

Fixed both in 85cb2fbf:

1. Reverted .release-please-manifest.json (which had been bumped to 6.0.0-rc04 on this branch by the Release RC workflow) as well as CHANGELOG.md, README.md, and gradle.properties back to origin/main (5.2.0).
2. Removed "prerelease": true and "prerelease-type": "rc" from release-please-config.json.

Once this feat!: PR is squash-merged into main, release-please will automatically update the open release PR (#1786) from 5.3.0 to final 6.0.0.

[kikoso]

gradle.properties isn't in the extra-files list in release-please-config.json, so this goes stale on the next release. Do we need it at all? allprojects { version = ... } in the root build file is already marker managed.

(Minor: trailing blank lines at the end of the file too.)

[dkhawk]

Fixed in 85cb2fbf — reverted gradle.properties to match origin/main (removing the redundant version= line and trailing blank lines) so allprojects { version = ... } in build.gradle.kts remains the single marker-managed version.

[kikoso]

Following up on the inline thread: most of them are gone, but three are still inline with no lambda parameter. This one, MapFragment.awaitMap() and SupportMapFragment.awaitMap(). Those files don't carry @file:Suppress("NOTHING_TO_INLINE") either, so they should be warning right now. Can you catch those too?

[dkhawk]

Fixed — removed inline from GoogleMap.awaitAnimateCamera, MapFragment.awaitMap(), and SupportMapFragment.awaitMap() so only DSL builder extensions that accept a lambda parameter (optionsActions: ... -> Unit) are marked inline.

[kikoso]

The MapView lifecycle is driven by hand here (onCreate / onStart / onResume) and onPause, onStop, onDestroy and onLowMemory are never called, so the MapView and its native resources leak. This wants a DisposableEffect tied to the lifecycle.

Related on line 100: lifecycleScope.launch { repeatOnLifecycle { ... } } is nested inside the LaunchedEffect, so that inner coroutine outlives the composable leaving composition. Moving the repeatOnLifecycle into the LaunchedEffect body fixes it.

This is the sample the README points people at, so I'd rather it show the right pattern. (Also trailing whitespace on line 81.)

[dkhawk]

Fixed in 85cb2fbf — replaced the manual onCreate/onStart/onResume calls with a DisposableEffect(lifecycleOwner, mapView) LifecycleEventObserver that forwards the full lifecycle (ON_CREATE through ON_DESTROY), and moved lifecycleOwner.repeatOnLifecycle(Lifecycle.State.STARTED) inside LaunchedEffect(lifecycleOwner, mapView) after mapView.awaitMap().

[kikoso]

This turns "user switched GPS off" into cancellation, which propagates into the collector's scope instead of being something they can catch and handle. Was that deliberate? A dedicated exception, or just completing the flow, would be easier to work with. Same on line 113.

Broader question on this whole package: should location live in :library at all, given it's what drags play-services-location onto every consumer? A separate :ktx module, or at least a :location one, might be the better home. This is the piece I'd most like settled before merge since it's baked into the 6.0.0 surface.

[dkhawk]

Fixed in 85cb2fbf — changed onProviderDisabled in both LocationManager.kt and ktx/utils/location/LocationManager.kt from close(CancellationException(...)) to close() so the Flow completes normally without cancelling the collector's scope.

Regarding the broader packaging question for com.google.maps.android.location:

1. LocationManager.kt only references android.location.LocationManager from the Android framework SDK (zero external dependencies).
2. For FusedLocationProvider.kt, we changed play-services-location from api(...) to compileOnly(libs.play.services.location) in library/build.gradle.kts (85cb2fbf) and added -dontwarn com.google.android.gms.location.** to library/consumer-rules.pro (7077a63d). As a result, play-services-location is completely omitted from the published android-maps-utils-core POM—consumers of :library, :data, :clustering, or :heatmaps do not pull play-services-location transitively unless they explicitly declare it themselves to use FusedLocationProviderClient.

[kikoso]

Kotlin 2.4.10 to 2.4.20, Gradle wrapper 9.6.1 to 9.7.1, Robolectric 4.16.1 to 4.17, Compose BOM, Navigation SDK, lint, plus a codeql-action SHA bump are all riding along in an 8.5k line migration.

Can those move to a separate build(deps): PR? They'll fight with Renovate, and they make this one harder to revert if we ever need to.

[dkhawk]

Reverted the ancillary version bumps (robolectric, lint, gradle AGP, composeBom, navigation, places, secretsGradlePlugin, and gradle-wrapper.properties) to match origin/main (85cb2fbf & 7077a63d), keeping only the dependencies introduced by this migration (androidx-lifecycle-runtime-ktx, kotlinx-coroutines-*, mockito-kotlin, play-services-location, truth).

[kikoso]

nit: stray blank line. Same kind of thing in MIGRATION.md line 22 and inside the code fence in .gemini/skills/android-maps-utils/SKILL.md.

[dkhawk]

Cleaned up the stray blank lines in build.gradle.kts, MIGRATION.md, and .gemini/skills/android-maps-utils-6-migration/SKILL.md in 85cb2fbf.

[LoyalAbbas]

Falling back to PASSIVE_PROVIDER here will throw a SecurityException if the caller only holds ACCESS_COARSE_LOCATION, since Android's LocationManagerService strictly requires ACCESS_FINE_LOCATION for passive updates. Also, we should check allProviders.contains(...) before calling requestLocationUpdates in both coarseLocationEvents and fineLocationEvents (and close() the flow if missing) so this doesn't crash with IllegalArgumentException: provider doesn't exist on devices without GPS/network hardware.

[dkhawk]

Great catch! Fixed in 7429314c — removed the PASSIVE_PROVIDER fallback in coarseLocationEvents and added an upfront if (!allProviders.contains(...)) { close(); return@callbackFlow } check in both coarseLocationEvents (NETWORK_PROVIDER) and fineLocationEvents (GPS_PROVIDER), along with unit tests in LocationManagerTest verifying that missing providers complete the flow cleanly without invoking requestLocationUpdates.

[kikoso]

LGTM!