[docs] Add documentation: testing a pull request

Author: opacam

doc/source/index.rst

@@ -38,6 +38,7 @@ Contents
    troubleshooting
    docker
    contribute
+   testing_pull_requests
 
 
 Indices and tables

doc/source/testing_pull_requests.rst

@@ -0,0 +1,178 @@
+Testing an python-for-android pull request
+==========================================
+
+In order to test a p4a pull requests we contemplate three possible scenarios:
+
+  - using python-for-android commands directly from the pull request files
+    that we want to test, without installing it (the recommended way for most
+    of the test cases)
+  - installing python-for-android using the github's branch of the pull request
+  - using buildozer and a custom app
+
+We will explain the first two methods using one of the distributed
+python-for-android test apps and we assume that you already have the
+python-for-android dependencies installed. For the `buildozer` method we assume that you
+already have a a properly working app to test and a working
+installation/configuration of `buildozer`. There is one step that it's shared
+with all the testing methods that we propose in here...we named it
+`Common steps`.
+
+
+Common steps
+^^^^^^^^^^^^
+
+- open a terminal, create a test directory and enter inside it, eg.::
+
+    .. codeblock:: bash
+
+        mkdir p4a_pull_requests
+        cd p4a_pull_requests
+
+- clone the pull request you wanna to test, let's imagine that you wanna to
+  test a pull request whose branch is named `feature-fix-numpy` and the github
+  nickname of the user who created the pull request is named `obiwankenoby`::
+
+    .. codeblock:: bash
+
+        git clone -b feature-fix-numpy \
+            --single-branch \
+            https://github.com/obiwankenoby/python-for-android.git \
+            p4a-feature-fix-numpy
+
+For what it's worth it about the command above explained line by line:
+
+    - `git clone -b feature-fix-numpy`: we tell git that we want to clone the
+      branch named `feature-fix-numpy`
+    - `--single-branch`: we tell git that we only want that branch
+    - `https://github.com/obiwankenoby/python-for-android.git`: noticed the
+      nickname of the user that created the pull request: `obiwankenoby` in the
+      middle of the line? that should be changed as needed for each pull
+      request that you wanna to test
+    - `p4a-feature-fix-numpy`: the name of the cloned repository, so we can
+      have multiple clones of different prs in the same folder
+
+.. note:: You can view the author/branch information looking at the
+          subtitle of the pull request, near the pull request status (expected
+          an `open` status)
+
+Using python-for-android commands directly from the pull request files
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- Enter inside the directory of the cloned repository in the above
+  step and run p4a command with proper args, eg::
+
+    .. codeblock:: bash
+
+        cd p4a-feature-fix-numpy
+        PYTHONPATH=. python3 -m pythonforandroid.toolchain apk \
+            --private=testapps/testapp_sqlite_openssl \
+            --dist-name=dist_test_app_python3_libs \
+            --package=org.kivy \
+            --name=test_app_python3_sqlite_openssl \
+            --version=0.1 \
+            --requirements=requests,peewee,sdl2,pyjnius,kivy,python3 \
+            --ndk-dir=/media/DEVEL/Android/android-ndk-r20 \
+            --sdk-dir=/media/DEVEL/Android/android-sdk-linux \
+            --android-api=27 \
+            --arch=arm64-v8a \
+            --permission=INTERNET \
+            --debug
+
+Things that you should know:
+
+
+    - The example above will build an testapp we will make use of the files of
+      the testapp named `testapp_sqlite_openssl.py` but we don't use the setup
+      file to build it so we must tell python-for-android what we want via
+      arguments
+    - be sure to at least edit the following arguments when running the above
+      command, since the default set in there it's unlikely that match your
+      installation:
+
+        - `--ndk-dir`: An absolute path to your android's NDK dir
+        - `--sdk-dir`: An absolute path to your android's SDK dir
+        - `--debug`: this one enables the debug mode of python-for-android,
+          which will show all log messages of the build. You can omit this one
+          but it's worth it to be mentioned, since this it's useful to us when
+          trying to find the source of the problem when things goes wrong
+    - The apk generated by the above command should be located at the root of
+      of the cloned repository, were you run the command to build the apk
+    - The testapps distributed with python-for-android are located at
+      `testapps` folder under the main folder project
+    - All the builds of python-for-android are located at
+      `~/.local/share/python-for-android`
+    - You should have a downloaded copy of the android's NDK and SDK
+
+Installing python-for-android using the github's branch of the pull request
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- Enter inside the directory of the cloned repository mentioned in
+  `Common steps` and install it via pip, eg.::
+
+    .. codeblock:: bash
+
+        cd p4a-feature-fix-numpy
+        pip3 install . --upgrade --user
+
+- Now, go inside the `testapps` directory (we assume that you still are inside
+  the cloned repository)::
+
+    .. codeblock:: bash
+
+        cd testapps
+
+- Run the build of the apk via the freshly installed copy of python-for-android
+  by running a similar command than below::
+
+    .. code-block:: bash
+
+        python3 setup_testapp_python3_sqlite_openssl.py apk \
+            --ndk-dir=/media/DEVEL/Android/android-ndk-r20 \
+            --sdk-dir=/media/DEVEL/Android/android-sdk-linux \
+            --android-api=27 \
+            --arch=arm64-v8a \
+            --debug
+
+
+Things that you should know:
+
+    - In the example above, we override some variables that are set in
+      `setup_testapp_python3_sqlite_openssl.py`, you could also override them
+      by editing this file
+    - be sure to at least edit the following arguments when running the above
+      command, since the default set in there it's unlikely that match your
+      installation:
+
+        - `--ndk-dir`: An absolute path to your android's NDK dir
+        - `--sdk-dir`: An absolute path to your android's SDK dir
+
+.. warning:: Once you finish the pull request tests remember to go back to the
+             master or develop versions of python-for-android, since you just
+             installed the python-for-android files of the `pull request`
+
+Using buildozer with a custom app
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- Edit your `buildozer.spec` file. You should search for the key
+  `p4a.source_dir` and set the right value so in the example posted in
+  `Common steps` it would look like this::
+
+    p4a.source_dir = /home/user/p4a_pull_requests/p4a-feature-fix-numpy
+
+- Run you buildozer command as usual, eg.::
+
+    buildozer android debug p4a --dist-name=dist-test-feature-fix-numpy
+
+.. note:: this method has the advantage, can be run without installing the
+          pull request version of python-for-android nor the android's
+          dependencies but has one problem...when things goes wrong you must
+          determine if it's a buildozer issue or a python-for-android one
+
+.. warning:: Once you finish the pull request tests remember to comment/edit
+             the `p4a.source_dir` constant that you just edited to test the
+             pull request
+
+.. tip:: this method it's useful for developing pull requests since you can
+         edit `p4a.source_dir` to point to your python-for-android fork and you
+         can test any branch you want only switching branches with:
+         `git checkout <branch-name>` from inside your python-for-android fork