Add documentation about need tools and versions to build our app

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,103 @@
 
 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 a 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/)
+  ```
+  /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:
+    ```
+    export ANDROID_HOME="/Users/karinberg/Development/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
+    ```
+    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:
+  ```
+  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
+  - Decide which flavor and backend environment you what to use and
+    change it if necessary.
+- Open `recipients_app` project folder in vsCode
+- Open an terminal inside of vsCode and check `flutter --version` is
+  listing the right flutter version (See above or pubspec.yaml).
+- 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 +109,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 +123,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 +136,21 @@ 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
+- 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,26 @@
+#!/bin/zsh
+
+#!/bin/zsh
+
+# Exit on error
+set -e
+
+# Check if Flutter is installed
+if ! command -v flutter &> /dev/null; then
+    echo "Error: Flutter is not installed"
+    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,10 @@
 # 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.
 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