From 5db704fbcbd4c344d45fcb0588fc8d323085d3cf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Enrique=20Lo=CC=81pez=20Man=CC=83as?= Date: Thu, 5 Mar 2026 15:26:43 +0100 Subject: [PATCH 1/6] docs: added LLM guide --- llm-integration-prompt.md | 96 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 96 insertions(+) create mode 100644 llm-integration-prompt.md diff --git a/llm-integration-prompt.md b/llm-integration-prompt.md new file mode 100644 index 00000000..cdba4716 --- /dev/null +++ b/llm-integration-prompt.md @@ -0,0 +1,96 @@ +# Android Maps Compose - AI Integration Prompt + +You are an expert Android developer specializing in Jetpack Compose and modern Android architecture. Your task is to integrate the `android-maps-compose` library into the user's Android application. + +Please follow these instructions carefully to ensure a complete and idiomatic implementation. + +## 1. Setup Dependencies + +First, add the necessary dependencies to the app-level `build.gradle.kts` file. +Verify the latest versions if possible, but use these as a baseline: + +```kotlin +dependencies { + // Google Maps Compose library + implementation("com.google.maps.android:maps-compose:8.2.0") + + // Google Maps Play Services + implementation("com.google.android.gms:play-services-maps:8.2.0") + + // Optional: Maps Compose Utilities (for clustering, etc.) + // implementation("com.google.maps.android:maps-compose-utils:8.2.0") + + // Optional: Maps Compose Widgets (for UI components) + // implementation("com.google.maps.android:maps-compose-widgets:8.2.0") +} +``` + +## 2. Update AndroidManifest.xml + +Add the required permissions and the Google Maps API key meta-data to `AndroidManifest.xml`. Instruct the user to replace `YOUR_API_KEY` with their actual API key from the Google Cloud Console. + +```xml + + + + + + + + + ... + + +``` + +## 3. Implement the Map Composable + +Create a new file named `MapScreen.kt` (or similar, depending on the app's architecture) and add a basic Jetpack Compose map implementation. + +Use `CameraPositionState` to control the camera and `Marker` to display points of interest. + +```kotlin +import androidx.compose.foundation.layout.fillMaxSize +import androidx.compose.runtime.Composable +import androidx.compose.ui.Modifier +import com.google.android.gms.maps.model.CameraPosition +import com.google.android.gms.maps.model.LatLng +import com.google.maps.android.compose.GoogleMap +import com.google.maps.android.compose.Marker +import com.google.maps.android.compose.MarkerState +import com.google.maps.android.compose.rememberCameraPositionState + +@Composable +fun MapScreen() { + // Default location (e.g., Singapore) + val defaultLocation = LatLng(1.35, 103.87) + val cameraPositionState = rememberCameraPositionState { + position = CameraPosition.fromLatLngZoom(defaultLocation, 10f) + } + + GoogleMap( + modifier = Modifier.fillMaxSize(), + cameraPositionState = cameraPositionState + ) { + Marker( + state = MarkerState(position = defaultLocation), + title = "Singapore", + snippet = "Marker in Singapore" + ) + } +} +``` + +## 4. Best Practices & Guidelines +* **State Management:** Hoist state (like camera position and marker lists) to the ViewModel if the map is dynamic. +* **Performance:** For large numbers of markers, use the `Clustering` composable from the `maps-compose-utils` artifact instead of rendering thousands of individual `Marker` composables. +* **Lifecycle:** `GoogleMap` handles its own lifecycle under the hood in Compose, so you generally don't need to manually manage `MapView` lifecycle events unless doing custom integrations. + +## 5. Execution Steps +1. Create a new branch `feature/maps-compose-integration`. +2. Add the dependencies to `build.gradle.kts`. +3. Update `AndroidManifest.xml` with permissions and the API key placeholder. +4. Create the `MapScreen.kt` composable. +5. Provide a summary of the changes and instruct the user on how to add their API key. From c155d4413ea55bb6a40e992c990411e1b5090ed1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Enrique=20Lo=CC=81pez=20Man=CC=83as?= Date: Thu, 5 Mar 2026 15:30:27 +0100 Subject: [PATCH 2/6] docs: added release-please --- llm-integration-prompt.md | 11 ++++------- release-please-config.json | 3 ++- 2 files changed, 6 insertions(+), 8 deletions(-) diff --git a/llm-integration-prompt.md b/llm-integration-prompt.md index cdba4716..7dc0d504 100644 --- a/llm-integration-prompt.md +++ b/llm-integration-prompt.md @@ -12,16 +12,13 @@ Verify the latest versions if possible, but use these as a baseline: ```kotlin dependencies { // Google Maps Compose library - implementation("com.google.maps.android:maps-compose:8.2.0") - - // Google Maps Play Services - implementation("com.google.android.gms:play-services-maps:8.2.0") + implementation("com.google.maps.android:maps-compose:8.2.0") // x-release-please-version // Optional: Maps Compose Utilities (for clustering, etc.) - // implementation("com.google.maps.android:maps-compose-utils:8.2.0") - + // implementation("com.google.maps.android:maps-compose-utils:8.2.0") // x-release-please-version + // Optional: Maps Compose Widgets (for UI components) - // implementation("com.google.maps.android:maps-compose-widgets:8.2.0") + // implementation("com.google.maps.android:maps-compose-widgets:8.2.0") // x-release-please-version } ``` diff --git a/release-please-config.json b/release-please-config.json index a0c21d84..dbb400d7 100644 --- a/release-please-config.json +++ b/release-please-config.json @@ -4,7 +4,8 @@ "release-type": "simple", "extra-files": [ "build.gradle.kts", - "README.md" + "README.md", + "llm-integration-prompt.md" ] } } From 978bf3f318b060be2c48e25f0a3e7cff24430cc5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Enrique=20Lo=CC=81pez=20Man=CC=83as?= Date: Fri, 6 Mar 2026 15:13:38 +0100 Subject: [PATCH 3/6] docs: added android-maps-compose Gemini skill --- .gemini/skills/android-maps-compose/SKILL.md | 124 +++++++++++++++++++ 1 file changed, 124 insertions(+) create mode 100644 .gemini/skills/android-maps-compose/SKILL.md diff --git a/.gemini/skills/android-maps-compose/SKILL.md b/.gemini/skills/android-maps-compose/SKILL.md new file mode 100644 index 00000000..8da9e7a2 --- /dev/null +++ b/.gemini/skills/android-maps-compose/SKILL.md @@ -0,0 +1,124 @@ +--- +name: android-maps-compose +description: Guide for integrating the android-maps-compose library into an Android application. Use when users ask to add Google Maps Compose to their Android app or set up Maps in Compose. +--- + +# Android Maps Compose Integration + +You are an expert Android developer specializing in Jetpack Compose and modern Android architecture. Follow these instructions carefully to integrate the `android-maps-compose` library into the user's Android application. + +## 1. Setup Dependencies + +First, add the necessary dependencies to the app-level `build.gradle.kts` file. +Verify the latest versions if possible, but use these as a baseline: + +```kotlin +dependencies { + // Google Maps Compose library + implementation("com.google.maps.android:maps-compose:8.2.0") // x-release-please-version + + // Optional: Maps Compose Utilities (for clustering, etc.) + // implementation("com.google.maps.android:maps-compose-utils:8.2.0") // x-release-please-version + + // Optional: Maps Compose Widgets (for UI components) + // implementation("com.google.maps.android:maps-compose-widgets:8.2.0") // x-release-please-version +} +``` + +## 2. Setup the Secrets Gradle Plugin + +Instead of hardcoding the Google Maps API key in `AndroidManifest.xml`, use the Secrets Gradle Plugin for Android to inject the API key securely. + +First, add the plugin to the project-level `build.gradle.kts`: + +```kotlin +buildscript { + dependencies { + classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1") + } +} +``` + +Then, apply the plugin in the app-level `build.gradle.kts`: + +```kotlin +plugins { + // ... + id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin") +} +``` + +Add the API Key to `local.properties`: + +```properties +MAPS_API_KEY=YOUR_API_KEY +``` + +In `AndroidManifest.xml`, add the required permissions and reference the injected API key meta-data: + +```xml + + + + + + + + + ... + + +``` + +## 3. Implement the Map Composable + +Create a new file named `MapScreen.kt` (or similar, depending on the app's architecture) and add a basic Jetpack Compose map implementation. + +Use `CameraPositionState` to control the camera and `Marker` to display points of interest. + +```kotlin +import androidx.compose.foundation.layout.fillMaxSize +import androidx.compose.runtime.Composable +import androidx.compose.ui.Modifier +import com.google.android.gms.maps.model.CameraPosition +import com.google.android.gms.maps.model.LatLng +import com.google.maps.android.compose.GoogleMap +import com.google.maps.android.compose.Marker +import com.google.maps.android.compose.MarkerState +import com.google.maps.android.compose.rememberCameraPositionState + +@Composable +fun MapScreen() { + // Default location (e.g., Singapore) + val defaultLocation = LatLng(1.35, 103.87) + val cameraPositionState = rememberCameraPositionState { + position = CameraPosition.fromLatLngZoom(defaultLocation, 10f) + } + + GoogleMap( + modifier = Modifier.fillMaxSize(), + cameraPositionState = cameraPositionState + ) { + Marker( + state = MarkerState(position = defaultLocation), + title = "Singapore", + snippet = "Marker in Singapore" + ) + } +} +``` + +## 4. Best Practices & Guidelines +* **State Management:** Hoist state (like camera position and marker lists) to the ViewModel if the map is dynamic. +* **Performance:** For large numbers of markers, use the `Clustering` composable from the `maps-compose-utils` artifact instead of rendering thousands of individual `Marker` composables. +* **Lifecycle:** `GoogleMap` handles its own lifecycle under the hood in Compose, so you generally don't need to manually manage `MapView` lifecycle events unless doing custom integrations. + +## 5. Execution Steps +1. Create a new branch `feature/maps-compose-integration`. +2. Add the Maps Compose dependencies to the app-level `build.gradle.kts`. +3. Set up the Secrets Gradle Plugin in both project-level and app-level `build.gradle.kts`. +4. Update `AndroidManifest.xml` with permissions and the `${MAPS_API_KEY}` placeholder. +5. Create the `MapScreen.kt` composable. +6. Provide a summary of the changes and instruct the user on how to add their API key to `local.properties`. \ No newline at end of file From b25aa0ec2876d5d9f6cbdf6e2896b721956410aa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Enrique=20Lo=CC=81pez=20Man=CC=83as?= Date: Fri, 6 Mar 2026 15:20:02 +0100 Subject: [PATCH 4/6] docs: update LLM guide with secrets plugin instructions --- llm-integration-prompt.md | 44 ++++++++++++++++++++++++++++++++------- 1 file changed, 36 insertions(+), 8 deletions(-) diff --git a/llm-integration-prompt.md b/llm-integration-prompt.md index 7dc0d504..ee96c52f 100644 --- a/llm-integration-prompt.md +++ b/llm-integration-prompt.md @@ -22,9 +22,36 @@ dependencies { } ``` -## 2. Update AndroidManifest.xml +## 2. Setup the Secrets Gradle Plugin -Add the required permissions and the Google Maps API key meta-data to `AndroidManifest.xml`. Instruct the user to replace `YOUR_API_KEY` with their actual API key from the Google Cloud Console. +Instead of hardcoding the Google Maps API key in `AndroidManifest.xml`, use the Secrets Gradle Plugin for Android to inject the API key securely. + +First, add the plugin to the project-level `build.gradle.kts`: + +```kotlin +buildscript { + dependencies { + classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1") + } +} +``` + +Then, apply the plugin in the app-level `build.gradle.kts`: + +```kotlin +plugins { + // ... + id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin") +} +``` + +Add the API Key to `local.properties`: + +```properties +MAPS_API_KEY=YOUR_API_KEY +``` + +In `AndroidManifest.xml`, add the required permissions and reference the injected API key meta-data: ```xml @@ -33,10 +60,10 @@ Add the required permissions and the Google Maps API key meta-data to `AndroidMa - + + android:value="${MAPS_API_KEY}" /> ... @@ -87,7 +114,8 @@ fun MapScreen() { ## 5. Execution Steps 1. Create a new branch `feature/maps-compose-integration`. -2. Add the dependencies to `build.gradle.kts`. -3. Update `AndroidManifest.xml` with permissions and the API key placeholder. -4. Create the `MapScreen.kt` composable. -5. Provide a summary of the changes and instruct the user on how to add their API key. +2. Add the Maps Compose dependencies to the app-level `build.gradle.kts`. +3. Set up the Secrets Gradle Plugin in both project-level and app-level `build.gradle.kts`. +4. Update `AndroidManifest.xml` with permissions and the `${MAPS_API_KEY}` placeholder. +5. Create the `MapScreen.kt` composable. +6. Provide a summary of the changes and instruct the user on how to add their API key to `local.properties`. \ No newline at end of file From f5398b0289b1e5da47e44360a85bf2df4e98a8bd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Enrique=20Lo=CC=81pez=20Man=CC=83as?= Date: Fri, 6 Mar 2026 15:20:37 +0100 Subject: [PATCH 5/6] chore: add SKILL.md to release-please extra files --- release-please-config.json | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/release-please-config.json b/release-please-config.json index dbb400d7..8d338c8c 100644 --- a/release-please-config.json +++ b/release-please-config.json @@ -5,7 +5,8 @@ "extra-files": [ "build.gradle.kts", "README.md", - "llm-integration-prompt.md" + "llm-integration-prompt.md", + ".gemini/skills/android-maps-compose/SKILL.md" ] } } From 4376fafccea0afb0e663a15d433444465608e6c5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Enrique=20Lo=CC=81pez=20Man=CC=83as?= Date: Tue, 10 Mar 2026 03:39:43 +0100 Subject: [PATCH 6/6] docs: update LLM guide with version catalogs instructions --- llm-integration-prompt.md | 36 ++++++++++++++++++++++++++++++++++-- 1 file changed, 34 insertions(+), 2 deletions(-) diff --git a/llm-integration-prompt.md b/llm-integration-prompt.md index ee96c52f..79db3e8f 100644 --- a/llm-integration-prompt.md +++ b/llm-integration-prompt.md @@ -6,8 +6,40 @@ Please follow these instructions carefully to ensure a complete and idiomatic im ## 1. Setup Dependencies -First, add the necessary dependencies to the app-level `build.gradle.kts` file. -Verify the latest versions if possible, but use these as a baseline: +You can add dependencies using either version catalogs (recommended) or directly in your `build.gradle.kts` file. Verify the latest versions if possible, but use these as a baseline: + +### Option A: Using Version Catalogs (Recommended) + +Add the following to your `gradle/libs.versions.toml` file: + +```toml +[versions] +mapsCompose = "8.2.0" # x-release-please-version + +[libraries] +maps-compose = { group = "com.google.maps.android", name = "maps-compose", version.ref = "mapsCompose" } +maps-compose-utils = { group = "com.google.maps.android", name = "maps-compose-utils", version.ref = "mapsCompose" } +maps-compose-widgets = { group = "com.google.maps.android", name = "maps-compose-widgets", version.ref = "mapsCompose" } +``` + +Then add them to your app-level `build.gradle.kts`: + +```kotlin +dependencies { + // Google Maps Compose library + implementation(libs.maps.compose) + + // Optional: Maps Compose Utilities (for clustering, etc.) + // implementation(libs.maps.compose.utils) + + // Optional: Maps Compose Widgets (for UI components) + // implementation(libs.maps.compose.widgets) +} +``` + +### Option B: Direct Dependencies + +If you are not using version catalogs, add the dependencies directly to your app-level `build.gradle.kts`: ```kotlin dependencies {