From 4c07bda59ce8253c56bdf254e5800c8bff28fa3d Mon Sep 17 00:00:00 2001
From: Andrea Diaz Correia <andrea.diaz.correia@gmail.com>
Date: Mon, 27 Oct 2025 17:10:30 -0300
Subject: [PATCH] docs: improve Android signing setup documentation and
 examples

---
 android/key.properties.example | 18 +++++++----
 docs/DEBUG_RELEASE_CONFLICT.md | 56 ++++++++++++++++++++++++++++++++++
 2 files changed, 68 insertions(+), 6 deletions(-)
 create mode 100644 docs/DEBUG_RELEASE_CONFLICT.md

diff --git a/android/key.properties.example b/android/key.properties.example
index d5ec66de..3fbfeff1 100644
--- a/android/key.properties.example
+++ b/android/key.properties.example
@@ -1,6 +1,12 @@
-# Example key.properties for local development
-# Copy this to key.properties and fill in your actual values
-storePassword=your_store_password_here
-keyPassword=your_key_password_here  
-keyAlias=your_key_alias_here
-storeFile=your_keystore_file_name.jks
\ No newline at end of file
+# Android Release Signing Configuration
+# 
+# Copy this file: cp android/key.properties.example android/key.properties
+# Then fill with your actual keystore values
+# 
+# NEVER commit key.properties to git - it's already in .gitignore
+# For complete setup instructions, see: docs/GITHUB_SECRETS_SETUP.md
+
+storeFile=upload-keystore.jks
+storePassword=YOUR_STORE_PASSWORD_HERE
+keyAlias=upload
+keyPassword=YOUR_KEY_PASSWORD_HERE
\ No newline at end of file
diff --git a/docs/DEBUG_RELEASE_CONFLICT.md b/docs/DEBUG_RELEASE_CONFLICT.md
new file mode 100644
index 00000000..da696588
--- /dev/null
+++ b/docs/DEBUG_RELEASE_CONFLICT.md
@@ -0,0 +1,56 @@
+# Debug/Release APK Install Conflict
+
+## The Problem
+
+When you run the app with `flutter run` (debug mode) and then try to install a release APK, Android shows a **"App not installed" conflict error**.
+
+**Why this happens:**
+- **Debug builds** (`flutter run`) → Signed with Flutter's debug keystore
+- **Release builds** → Signed with your production keystore (or debug if not configured)
+- Android won't install an APK signed with a different certificate over an existing app
+
+## Quick Solution
+
+Uninstall the existing app first:
+
+```bash
+# Uninstall the app
+adb uninstall network.mostro.app
+
+# Then install the release APK
+adb install build/app/outputs/flutter-apk/app-release.apk
+```
+
+Or from your device: **Settings → Apps → Mostro → Uninstall**, then install the new APK.
+
+## Permanent Solution
+
+Configure your local development to use the same keystore for both debug and release builds. This way you can switch between `flutter run` and release APKs without conflicts.
+
+**See the complete setup guide:** [`docs/GITHUB_SECRETS_SETUP.md`](docs/GITHUB_SECRETS_SETUP.md)
+
+The guide covers:
+- Creating a keystore from scratch
+- Configuring `key.properties` for local builds
+- Setting up GitHub Actions for CI/CD
+- Troubleshooting signing issues
+
+## Additional Notes
+
+### Verifying which keystore is being used
+
+```bash
+flutter build apk --release 2>&1 | grep -i "signing\|keystore"
+```
+
+**Good**: No warnings  
+**Bad**: "Release build using debug signing - keystore not available"
+
+### Want to keep using debug signing?
+
+If you prefer to keep debug and release builds separate (and don't mind uninstalling between switches), simply don't create a `key.properties` file. The build will automatically use debug signing for both.
+
+## References
+
+- [Flutter - Build and release an Android app](https://docs.flutter.dev/deployment/android)
+- [Android - Sign your app](https://developer.android.com/studio/publish/app-signing)