From 11f5758ce9e0877c6a664d915b48fd3c27754b92 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Enrique=20Lo=CC=81pez=20Man=CC=83as?= Date: Tue, 24 Mar 2026 08:41:09 +0100 Subject: [PATCH 1/5] docs: add AI integration standards to rewrite branch --- .gemini/skills/android-maps-utils/SKILL.md | 51 ++++++++++++++++++++++ .geminiignore | 40 +++++++++++++++++ CONTRIBUTING.md | 6 +++ README.md | 4 ++ llm-integration-prompt.md | 51 ++++++++++++++++++++++ 5 files changed, 152 insertions(+) create mode 100644 .gemini/skills/android-maps-utils/SKILL.md create mode 100644 .geminiignore create mode 100644 llm-integration-prompt.md diff --git a/.gemini/skills/android-maps-utils/SKILL.md b/.gemini/skills/android-maps-utils/SKILL.md new file mode 100644 index 000000000..77522eb3d --- /dev/null +++ b/.gemini/skills/android-maps-utils/SKILL.md @@ -0,0 +1,51 @@ +--- +name: maps-utils-android +description: Guide for integrating the Google Maps Utility Library for Android (android-maps-utils) into an application. Use when users ask to add features like Marker Clustering, Heatmaps, GeoJSON, KML, or Polyline encoding/decoding. +--- + +# Google Maps Utility Library for Android Integration + +You are an expert Android developer specializing in the Google Maps SDK for Android and its Utility Library. Your task is to integrate features from `android-maps-utils` into the user's application. + +## 1. Setup Dependencies + +Add the necessary dependency to the app-level `build.gradle.kts` file: + +```kotlin +dependencies { + // Google Maps Utility Library + implementation("com.google.maps.android:android-maps-utils:3.9.0") // Check for the latest version +} +``` +*(Note: If the user is using Jetpack Compose, they should ideally be using `maps-compose-utils` from the `android-maps-compose` repository instead of this library directly, though this library is the underlying foundation).* + +## 2. Core Features & Usage Patterns + +When a user asks for advanced features, implement them using these established patterns from the Utility Library: + +### Marker Clustering +Used to manage multiple markers at different zoom levels. +1. Create a `ClusterItem` data class. +2. Initialize a `ClusterManager` inside `onMapReady`. +3. Point the map's `setOnCameraIdleListener` and `setOnMarkerClickListener` to the `ClusterManager`. +4. Add items using `clusterManager.addItem()`. + +### Heatmaps +Used to represent the density of data points. +1. Provide a `Collection` or `Collection`. +2. Create a `HeatmapTileProvider` with the builder `HeatmapTileProvider.Builder().data(list).build()`. +3. Add the overlay to the map: `map.addTileOverlay(TileOverlayOptions().tileProvider(provider))`. + +### GeoJSON and KML +Used to import geographic data from external files. +* **GeoJSON:** `val layer = GeoJsonLayer(map, R.raw.geojson_file, context); layer.addLayerToMap()` +* **KML:** `val layer = KmlLayer(map, R.raw.kml_file, context); layer.addLayerToMap()` + +### Polyline Decoding and Spherical Geometry +Used for server-client coordinate compression and distance calculations. +* **Decoding:** `PolyUtil.decode(encodedPathString)` +* **Distance:** `SphericalUtil.computeDistanceBetween(latLng1, latLng2)` + +## 3. Best Practices +1. **Performance:** For massive datasets (e.g., parsing huge GeoJSON files), do not block the main thread. Parse on a background dispatcher and only call `layer.addLayerToMap()` on the UI thread. +2. **Custom Renderers:** If the user wants custom cluster icons, extend `DefaultClusterRenderer` and override `onBeforeClusterItemRendered` and `onBeforeClusterRendered`. diff --git a/.geminiignore b/.geminiignore new file mode 100644 index 000000000..9079d3bc3 --- /dev/null +++ b/.geminiignore @@ -0,0 +1,40 @@ +# Ignore build and generated directories +build/ +**/build/ +.gradle/ +.idea/ +.kotlin/ +.vscode/ + +# Ignore outputs +*.apk +*.ap_ +*.aab +*.dex +*.class + +# Ignore large media assets (images, fonts, etc) unless specifically required +**/*.png +**/*.jpg +**/*.jpeg +**/*.gif +**/*.webp +**/*.svg +**/*.mp4 +**/*.mp3 +**/*.wav +**/*.ttf +**/*.woff +**/*.woff2 +**/*.otf + +# Ignore temporary and cache files +tmp/ +**/tmp/ +*.log +*.tmp +*.bak +*.swp +*~.nib +local.properties +.DS_Store diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9a86ba025..fa09ca821 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -26,3 +26,9 @@ information on using pull requests. This project follows [Google's Open Source Community Guidelines](https://opensource.google/conduct/). + +## Using AI to Contribute + +This repository provides an official Gemini Skill to help AI agents navigate and contribute to the project effectively. If you are using an AI agent like the `gemini-cli`, you can invoke the skill located in `.gemini/skills/android-maps-utils` to learn how to interact with the codebase. + +Additionally, the `.geminiignore` file prevents AI tools from consuming large or irrelevant files to preserve context limits. You can also reference the generic `llm-integration-prompt.md` to feed into web-based LLMs for general assistance. diff --git a/README.md b/README.md index cbed94e74..400de9b7c 100644 --- a/README.md +++ b/README.md @@ -176,6 +176,10 @@ If you wish to disable this, you can do so by removing the initializer in your ` Contributions are welcome and encouraged! If you'd like to contribute, send us a [pull request] and refer to our [code of conduct] and [contributing guide]. +### Using AI +This repository provides an official Gemini Skill and an `llm-integration-prompt.md` to help AI agents navigate the codebase and provide assistance. Refer to the [contributing guide] for more details on AI usage. + + ## Terms of Service This library uses Google Maps Platform services. Use of Google Maps Platform services through this library is subject to the Google Maps Platform [Terms of Service]. diff --git a/llm-integration-prompt.md b/llm-integration-prompt.md new file mode 100644 index 000000000..77522eb3d --- /dev/null +++ b/llm-integration-prompt.md @@ -0,0 +1,51 @@ +--- +name: maps-utils-android +description: Guide for integrating the Google Maps Utility Library for Android (android-maps-utils) into an application. Use when users ask to add features like Marker Clustering, Heatmaps, GeoJSON, KML, or Polyline encoding/decoding. +--- + +# Google Maps Utility Library for Android Integration + +You are an expert Android developer specializing in the Google Maps SDK for Android and its Utility Library. Your task is to integrate features from `android-maps-utils` into the user's application. + +## 1. Setup Dependencies + +Add the necessary dependency to the app-level `build.gradle.kts` file: + +```kotlin +dependencies { + // Google Maps Utility Library + implementation("com.google.maps.android:android-maps-utils:3.9.0") // Check for the latest version +} +``` +*(Note: If the user is using Jetpack Compose, they should ideally be using `maps-compose-utils` from the `android-maps-compose` repository instead of this library directly, though this library is the underlying foundation).* + +## 2. Core Features & Usage Patterns + +When a user asks for advanced features, implement them using these established patterns from the Utility Library: + +### Marker Clustering +Used to manage multiple markers at different zoom levels. +1. Create a `ClusterItem` data class. +2. Initialize a `ClusterManager` inside `onMapReady`. +3. Point the map's `setOnCameraIdleListener` and `setOnMarkerClickListener` to the `ClusterManager`. +4. Add items using `clusterManager.addItem()`. + +### Heatmaps +Used to represent the density of data points. +1. Provide a `Collection` or `Collection`. +2. Create a `HeatmapTileProvider` with the builder `HeatmapTileProvider.Builder().data(list).build()`. +3. Add the overlay to the map: `map.addTileOverlay(TileOverlayOptions().tileProvider(provider))`. + +### GeoJSON and KML +Used to import geographic data from external files. +* **GeoJSON:** `val layer = GeoJsonLayer(map, R.raw.geojson_file, context); layer.addLayerToMap()` +* **KML:** `val layer = KmlLayer(map, R.raw.kml_file, context); layer.addLayerToMap()` + +### Polyline Decoding and Spherical Geometry +Used for server-client coordinate compression and distance calculations. +* **Decoding:** `PolyUtil.decode(encodedPathString)` +* **Distance:** `SphericalUtil.computeDistanceBetween(latLng1, latLng2)` + +## 3. Best Practices +1. **Performance:** For massive datasets (e.g., parsing huge GeoJSON files), do not block the main thread. Parse on a background dispatcher and only call `layer.addLayerToMap()` on the UI thread. +2. **Custom Renderers:** If the user wants custom cluster icons, extend `DefaultClusterRenderer` and override `onBeforeClusterItemRendered` and `onBeforeClusterRendered`. From 5c3b838d2ad6085e2b17f0f56a1aed777d442209 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Enrique=20Lo=CC=81pez=20Man=CC=83as?= Date: Tue, 24 Mar 2026 08:42:49 +0100 Subject: [PATCH 2/5] chore: add release-please annotation to AI prompts --- .gemini/skills/android-maps-utils/SKILL.md | 2 +- llm-integration-prompt.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.gemini/skills/android-maps-utils/SKILL.md b/.gemini/skills/android-maps-utils/SKILL.md index 77522eb3d..b885c7c5a 100644 --- a/.gemini/skills/android-maps-utils/SKILL.md +++ b/.gemini/skills/android-maps-utils/SKILL.md @@ -14,7 +14,7 @@ Add the necessary dependency to the app-level `build.gradle.kts` file: ```kotlin dependencies { // Google Maps Utility Library - implementation("com.google.maps.android:android-maps-utils:3.9.0") // Check for the latest version + implementation("com.google.maps.android:android-maps-utils:3.9.0") // x-release-please-version } ``` *(Note: If the user is using Jetpack Compose, they should ideally be using `maps-compose-utils` from the `android-maps-compose` repository instead of this library directly, though this library is the underlying foundation).* diff --git a/llm-integration-prompt.md b/llm-integration-prompt.md index 77522eb3d..b885c7c5a 100644 --- a/llm-integration-prompt.md +++ b/llm-integration-prompt.md @@ -14,7 +14,7 @@ Add the necessary dependency to the app-level `build.gradle.kts` file: ```kotlin dependencies { // Google Maps Utility Library - implementation("com.google.maps.android:android-maps-utils:3.9.0") // Check for the latest version + implementation("com.google.maps.android:android-maps-utils:3.9.0") // x-release-please-version } ``` *(Note: If the user is using Jetpack Compose, they should ideally be using `maps-compose-utils` from the `android-maps-compose` repository instead of this library directly, though this library is the underlying foundation).* From a8dd144a8b3e4cc44dcf451ce6bf8ff3e7ea309b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Enrique=20Lo=CC=81pez=20Man=CC=83as?= Date: Tue, 24 Mar 2026 08:43:45 +0100 Subject: [PATCH 3/5] chore: add AI prompt files to release-please-config.json --- release-please-config.json | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/release-please-config.json b/release-please-config.json index 1f9377b9e..f4ee714d8 100644 --- a/release-please-config.json +++ b/release-please-config.json @@ -5,7 +5,9 @@ "release-type": "simple", "extra-files": [ "README.md", - "build.gradle.kts" + "build.gradle.kts", + ".gemini/skills/android-maps-utils/SKILL.md", + "llm-integration-prompt.md" ] } } From 96e110d54bc95ad457ac8b0afc6e632597ffc589 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Enrique=20Lo=CC=81pez=20Man=CC=83as?= Date: Tue, 24 Mar 2026 08:44:25 +0100 Subject: [PATCH 4/5] docs: bump version in AI prompts to 4.1.1 --- .gemini/skills/android-maps-utils/SKILL.md | 2 +- llm-integration-prompt.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.gemini/skills/android-maps-utils/SKILL.md b/.gemini/skills/android-maps-utils/SKILL.md index b885c7c5a..2b51d92c5 100644 --- a/.gemini/skills/android-maps-utils/SKILL.md +++ b/.gemini/skills/android-maps-utils/SKILL.md @@ -14,7 +14,7 @@ Add the necessary dependency to the app-level `build.gradle.kts` file: ```kotlin dependencies { // Google Maps Utility Library - implementation("com.google.maps.android:android-maps-utils:3.9.0") // x-release-please-version + implementation("com.google.maps.android:android-maps-utils:4.1.1") // x-release-please-version } ``` *(Note: If the user is using Jetpack Compose, they should ideally be using `maps-compose-utils` from the `android-maps-compose` repository instead of this library directly, though this library is the underlying foundation).* diff --git a/llm-integration-prompt.md b/llm-integration-prompt.md index b885c7c5a..2b51d92c5 100644 --- a/llm-integration-prompt.md +++ b/llm-integration-prompt.md @@ -14,7 +14,7 @@ Add the necessary dependency to the app-level `build.gradle.kts` file: ```kotlin dependencies { // Google Maps Utility Library - implementation("com.google.maps.android:android-maps-utils:3.9.0") // x-release-please-version + implementation("com.google.maps.android:android-maps-utils:4.1.1") // x-release-please-version } ``` *(Note: If the user is using Jetpack Compose, they should ideally be using `maps-compose-utils` from the `android-maps-compose` repository instead of this library directly, though this library is the underlying foundation).* From 85a64e6dbc5fe0a32fed80d052b6b233794cdbbf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Enrique=20Lo=CC=81pez=20Man=CC=83as?= Date: Tue, 24 Mar 2026 08:45:51 +0100 Subject: [PATCH 5/5] docs: remove compose utils reference from AI prompts --- .gemini/skills/android-maps-utils/SKILL.md | 1 - llm-integration-prompt.md | 1 - 2 files changed, 2 deletions(-) diff --git a/.gemini/skills/android-maps-utils/SKILL.md b/.gemini/skills/android-maps-utils/SKILL.md index 2b51d92c5..c094ae05e 100644 --- a/.gemini/skills/android-maps-utils/SKILL.md +++ b/.gemini/skills/android-maps-utils/SKILL.md @@ -17,7 +17,6 @@ dependencies { implementation("com.google.maps.android:android-maps-utils:4.1.1") // x-release-please-version } ``` -*(Note: If the user is using Jetpack Compose, they should ideally be using `maps-compose-utils` from the `android-maps-compose` repository instead of this library directly, though this library is the underlying foundation).* ## 2. Core Features & Usage Patterns diff --git a/llm-integration-prompt.md b/llm-integration-prompt.md index 2b51d92c5..c094ae05e 100644 --- a/llm-integration-prompt.md +++ b/llm-integration-prompt.md @@ -17,7 +17,6 @@ dependencies { implementation("com.google.maps.android:android-maps-utils:4.1.1") // x-release-please-version } ``` -*(Note: If the user is using Jetpack Compose, they should ideally be using `maps-compose-utils` from the `android-maps-compose` repository instead of this library directly, though this library is the underlying foundation).* ## 2. Core Features & Usage Patterns