Add documentation about need tools and versions to build our app (#963)

- Add documentation about need tools and versions to build our app
- Add a example launch.json file
- Add optional support for version manager 'asdf'
- Add a clean_build.sh script to execute fast a clean build

recipients_app/.tool-versions

@@ -0,0 +1 @@
+flutter 3.19.6

recipients_app/.vscode/launch.json.example

@@ -0,0 +1,56 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+
+    // This is our example launch config. Set the prefered flavor, SURVEY_BASE_URL and SENTRY_URL
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "stage_recipients_app (debug mode)",
+            "request": "launch",
+            "type": "dart",
+            "flutterMode": "debug",
+            "program": "lib/main.dart",
+            "args": [
+                "--flavor",
+                "stage",
+                "--dart-define",
+                "SURVEY_BASE_URL=staging.socialincome.org",
+                "--dart-define",
+                "SENTRY_URL=FILL IN SENTRY URL",
+
+            ],
+        },
+        {
+            "name": "stage_recipients_app (profile mode)",
+            "request": "launch",
+            "type": "dart",
+            "flutterMode": "profile",
+            "program": "lib/main.dart",
+            "args": [
+                "--flavor",
+                "stage",
+                "--dart-define",
+                "SURVEY_BASE_URL=staging.socialincome.org",
+                "--dart-define",
+                "SENTRY_URL=FILL IN SENTRY URL",
+            ],
+        },
+        {
+            "name": "stage_recipients_app (release mode)",
+            "request": "launch",
+            "type": "dart",
+            "flutterMode": "release",
+            "program": "lib/main.dart",
+            "args": [
+                "--flavor",
+                "stage",
+                "--dart-define",
+                "SURVEY_BASE_URL=staging.socialincome.org",
+                "--dart-define",
+                "SENTRY_URL=FILL IN SENTRY URL",
+            ],
+        }
+    ]
+}

recipients_app/README.md

@@ -2,24 +2,109 @@
 
 Mobile App for Recipients of a Social Income.
 
-## Basic Setup
-
-For the basic setup, please refer to the main [README](../README.md)
-
-## Getting Started
-
-Open `recipients_app` project folder in your development environment of
-choice. Building flavor should work seamlessly for Android Studio and VS
-Code with predefined build configs.
+## Tools needed for building the app on an Apple Silicon Mac
+
+- [Homebrew](https://brew.sh/de/)
+- Flutter 3.19.6, Dart 3.3.4
+- Java JDK 17
+- Android Studio LadyBug or later
+- Latest vsCode
+- Xcode 16.1
+
+## Configure the Apple Silicon Mac environment to build our app
+
+- Install [Homebrew](https://brew.sh/de/)
+  ```shell
+  /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+  ```
+- Install Android Studio
+  - Set ANDROID_HOME and deprecated ANDROID_SDK_ROOT. Add the following
+    lines in your USER's HOME directory in your .zshrc file:
+    ```shell
+    export ANDROID_HOME="YOUR PATH TO YOUR ANDROID SDK"
+    export ANDROID_SDK_ROOT="$ANDROID_HOME" # ANDROID_SDK_ROOT is deprecated, but still in use
+    export PATH="$PATH:$ANDROID_HOME/emulator:$ANDROID_HOME/tools:$ANDROID_HOME/tools/bin:$ANDROID_HOME/platform-tools"
+    ```
+  - Restart your terminal so that these changes take effect
+- Install Java 17 via Homebrew `brew install openjdk@17`
+  - Homebrew is telling you to execute a symlink command, so that the
+    system Java wrappers can find this JDK. Please do this.
+  - Additionally in your USER's HOME directory in the file '.zshrc', add
+    the lines to set the JAVA_HOME environment variable to Java 17 and
+    add Java to the PATH environment variable
+    ```shell
+    export JAVA_HOME=$(/usr/libexec/java_home -v17)
+    export PATH="$PATH:$JAVA_HOME/bin"
+    ```
+  - Restart your terminal so that these changes take effect
+- Install Flutter
+  - Tell Flutter to use our Java 17 JDK and not the one bundle with
+    Android Studio via `flutter config --jdk-dir $JAVA_HOME`. Otherwise,
+    you will get the error "Unsupported class file major version 65”
+    when building the app for Android.
+  - Restart your terminal and IDE so that these changes take effect
+- Install vsCode
+  - Install Flutter extension
+- Install Xcode
+  - Set is as default via `sudo xcode-select -s <path/to/>Xcode.app`
+  - To agree to the Xcode license from the command line, you can use the
+    following command: `sudo xcodebuild -license accept`
+
+## Optionally: Use the version manager [asdf](https://asdf-vm.com/)
+
+- Install [asdf](https://asdf-vm.com/) via Homebrew with
+  `brew install asdf`
+- Install flutter plugin for asdf via `asdf plugin-add flutter`
+- Add the following lines in your .zshrc file:
+  ```shell
+  export FLUTTER_ROOT="$(asdf where flutter)"
+  ### asdf stuff ############
+  source $(brew --prefix asdf)/libexec/asdf.sh
+  export ASDF_NODEJS_LEGACY_FILE_DYNAMIC_STRATEGY=latest_available
+  # This is optional. It installs tools defined in .tool-versions on terminal start
+  asdf install
+  ###########################
+  ```
+
+## Build and run the app the first time with vsCode
+
+- Checkout main branch:
+  `git clone https://github.com/socialincome-san/public.git ./social-income/`
+- Copy file `./.vscode/launch.json.example` and rename it to
+  `./.vscode/launch.json`
+  - Replace the value "FILL IN SENTRY URL" after "SENTRY_URL=" with the
+    real Sentry url to be able to use Sentry. If you do not prive a
+    Sentry Url, no issues will be reported to Sentry but you can still
+    run the app. To get the real Sentry url see
+    [here](https://social-income.sentry.io/settings/projects/si-mobileapp/keys/)
+    under "DSN".
+  - Decide which flavor and backend environment you want to use and
+    change it if necessary.
+- Open `recipients_app` project folder in vsCode
+- Open a terminal inside of vsCode and check `flutter --version` is
+  listing the right flutter version (See above or pubspec.yaml).
+- Add executable permissions to the script clean_build.sh via
+  `chmod +x clean_build.sh`
+- Run `./clean_build.sh`
+- Choose in vsCode the device to deploy on (iOS Simulator, Android
+  emulator, real Android or iOS device)
+- Run the launch configuration "stage_recipients_app (debug mode)" to
+  deploy and run the app on the selected devive in debug mode
+- Happy testing!!
+
+## Available app flavors
+
+Building flavor should work seamlessly for Android Studio and VS Code
+with predefined build configs.
 
 We have three build flavors:
 
 - `dev` -> Connecting with Firebase Emulators (Firestore and Auth)
 - `stage` -> Connecting with staging online firebase project
 - `prod` -> Connecting with production online firebase project and need
-  real Firebase configuration json / plist file
+  real Firebase configuration json / plist file (not in the repo)
 
-For development use `dev` flavor.
+For development, use the `dev` or `stage` flavor.
 
 As Firebase emulators work on your local host machine the easiest way to
 run app is on the Android emulator. Real devices need some additional
@@ -30,7 +115,9 @@ setup.
 1. Github for issue related discussion
 2. Everything else on [Slack](https://social-income.slack.com/home)
 
-## Rebuilding JSON Serialization
+## How tos
+
+### Rebuilding JSON Serialization
 
 ```
 dart run build_runner watch --delete-conflicting-outputs
@@ -42,7 +129,7 @@ or
 dart run build_runner build --delete-conflicting-outputs
 ```
 
-## Rebuilding Translations
+### Rebuilding Translations
 
 Translations are stored in lib/l10n/app_en.arb. To rebuild the
 translations after you changed something run:
@@ -55,6 +142,22 @@ To use a translated string in the code use:
 `AppLocalizations.of(context).helloWorld` and import:
 `import 'package:flutter_gen/gen_l10n/app_localizations.dart';`
 
+### Upgrade flutter version
+
+If you upgrade the flutter version, you have to change the following
+locations as well:
+
+- pubspec.yaml
+  - Under 'environment' adjust the 'sdk' and 'flutter' versions
+- .tool-versions (version file for version manager ASDF)
+  - If you use 'asdf' run the comman `asdf local flutter x.y.z` #Replace
+    x.y.z with the new Flutter version.
+  - Otherwise just update the version number in the file
+- Adjust variable 'REQUIRED_VERSION' in 'clean_build.sh'
+- README.md
+  - Find all places in the README.md which mentions the Flutter version
+    number
+
 ## Testing
 
 ### Manually

recipients_app/clean_build.sh

@@ -0,0 +1,34 @@
+#!/bin/zsh
+
+# Exit on error
+set -e
+
+# Check if Flutter is installed
+echo "Verify Flutter is installed..."
+if ! command -v flutter &> /dev/null; then
+    echo "Error: Flutter is not installed"
+    exit 1
+fi
+
+# Verify Flutter version
+echo "Verify Flutter version..."
+REQUIRED_VERSION="3.19.6"
+CURRENT_VERSION=$(flutter --version | head -n 1 | awk '{print $2}')
+if [ "$CURRENT_VERSION" != "$REQUIRED_VERSION" ]; then
+    echo "Error: Flutter version $REQUIRED_VERSION is required (current: $CURRENT_VERSION)"
+    exit 1
+fi
+
+echo "Cleaning Flutter build..."
+flutter clean
+
+echo "Getting dependencies..."
+flutter pub get
+
+echo "Running build runner..."
+dart run build_runner build --delete-conflicting-outputs
+
+echo "Generating localizations..."
+flutter gen-l10n
+
+echo "Build completed successfully!"

recipients_app/docu/app_release_guides/releasing.md

@@ -1,6 +1,14 @@
 # How to release the apps
 
 1. Increment app version and build number in pubspec.yaml
+
+   - Open 'pubspec.yaml' and increase 'version' with the desired app
+     version and the version code by incrementing the '+' part by 1.
+     Incrementing the version code is a must-have for a new prod
+     version. Otherwise, the stores will not accept the new app.
+
+     Example: Current: version: 1.1.0+12 New: version: 1.1.1+13
+
 1. Run CodeMagic Build "iOS Staging (Firebase App Distribution)"
 1. Run CodeMagic Build "Android Staging (Firebase App Distribution)"
 1. Test the app on the Staging environment. See