Update README and make command.

Makefile

@@ -89,7 +89,7 @@ p4a_android_project: p4a_android_distro src/kolibri needs-version
 	@git stash push --quiet --include-untracked -- python-for-android
 
 .PHONY: update_project_from_p4a
-p4a_android_project: p4a_android_distro src/kolibri needs-version
+update_project_from_p4a: p4a_android_distro src/kolibri needs-version
 	$(P4A) bootstrap $(ARCH_OPTIONS) --version=$(APK_VERSION) --numeric-version=$(BUILD_NUMBER)
 
 .PHONY: needs-version

README.md

@@ -14,7 +14,7 @@ This project was primarily developed on Docker, so this method is more rigorousl
 
 4. The generated APK will end up in the `bin/` folder.
 
-## Building for Development
+## Development Flow
 
 1. Install the Android SDK and Android NDK.
 
@@ -33,14 +33,25 @@ Follow the instructions from the command to set the additional environment varia
 
 4. Build or download a Kolibri WHL file, and place it in the `whl/` directory.
 
-To download a Kolibri WHL file, you can use `make whl=<URL>` from the command line. It will download it and put it in the correct directory.
+To download a Kolibri WHL file, you can use `make get-whl whl=<URL>` from the command line. It will download it and put it in the correct directory.
 
-5. By default the APK will be built for most architectures supported by
-   Python for Android. To build for a smaller set of architectures, set
-   the `ARCHES` environment variable. Run `p4a archs` to see the
-   available targets.
+5. By default the APK/AAB will be built for most architectures supported by Python for Android. To build for a smaller set of architectures, set the `ARCHES` environment variable. Run `p4a archs` to see the available targets.
 
-6. Run `make kolibri.apk.unsigned` to build the apk. Watch for success at the end, or errors, which might indicate missing build dependencies or build errors. If successful, there should be an APK in the `dist/` directory.
+6. Run `make p4a_android_project` this will do all of the Python for Android setup up until the point of actually building an APK or AAB.
+
+N.B. You will need to rerun this step any time you update the Kolibri WHL file you are using, or any time you update the Python code in this repository.
+
+7. You can now run Android Studio and open the folder `python-for-android/dists/kolibri` as the project folder to work from. You should be able to make updates to Java code, resource files, etc. using Android Studio, and build and run the project using Android Studio, including launching into emulators and real physical devices.
+
+N.B. When you rerun step 6, it will complain loudly and exit early if you have uncommitted changes in the python-for-android folder. Any changes should be committed (even if in a temporary commit) before rerunning this step, as we use git stash to undo any changes in the Android project caused by the Python for Android project bootstrapping process. Also, when rerunning step 5, the Android version will not have incremented, meaning that any emulator or physical device will need to have Kolibri explicitly uninstalled for any changes to Python code to be updated on install.
+
+## Debugging the app
+
+1. When running the app from Android Studio, if you are using an emulator, it is possible that there will be many warning messages due to GPU emulation. In the logcat tab, update the filter to this `package:mine & -tag:eglCodecCommon` to hide those errors from the logcat output.
+
+## Building from the commandline
+
+1. Run `make kolibri.apk.unsigned` to build the development apk. Watch for success at the end, or errors, which might indicate missing build dependencies or build errors. If successful, there should be an APK in the `dist/` directory.
 
 ## Installing the apk
 1. Connect your Android device over USB, with USB Debugging enabled.
@@ -52,8 +63,6 @@ To download a Kolibri WHL file, you can use `make whl=<URL>` from the command li
 
 1. Run `adb shell am start -n org.learningequality.Kolibri/org.kivy.android.PythonActivity`
 
-## Debugging the app
-
 ### Server Side
 Run `adb logcat -v brief python:D *:F` to get all debug logs from the Kolibri server
 
@@ -83,3 +92,10 @@ You could also do so using [Weinre](https://people.apache.org/~pmuellr/weinre/do
 The image was optimized to limit rebuilding and to be run in a developer-centric way. `scripts/rundocker.sh` describes the options needed to get the build running properly.
 
 Unless you need to make edits to the build method or are debugging one of the build dependencies and would like to continue using docker, you shouldn't need to modify that script.
+
+
+## Updating Python for Android
+
+We maintain a fork of Python for Android that includes various changes we have made to the source code to support our specific needs. As P4A make new releases, we make a branch from the latest release tag, and then replay the commits on top of this tag using an interactive rebase. Sometimes, this allows us to drop commits as new features are merged into P4A. Our naming convention for the branch on our fork is `from_upstream_<tag_name>`. Any time we push new commits to this branch, we must also update the pinned commit in `requirements.txt`, so that we are always building with a completely predictable version of Python for Android.
+
+By default we stash any updates to our bootstrap coming from Python for Android, because mostly we have overwritten their bootstrap code to make the relevant changes for us. If there are upstream changes to code we have committed in this repo from the bootstraps, then if the diff is small, it is probably simplest to manually copy in these changes to our committed code. If the diff is larger, or the developer fancies exercising some git-fu, then the make command `make update_project_from_p4a` will update the bootstrap from Python for Android, and not stash any changes that introduces. Through judicious change reversion and diffing, the appropriate changes can then be applied. Here be dragons.