[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,226 @@
+Testing an python-for-android pull request
+==========================================
+
+In order to test a pull request, we recommend to consider the following points:
+
+  #. of course, check if the overall thing makes sense
+  #. is the CI passing? if not what specifically fails
+  #. is it working locally at compile time?
+  #. is it working on device at runtime?
+
+This document will focus on the third point:
+`is it working locally at compile time?` so we will give some hints about how
+to proceed in order to create a local copy of the pull requests and build an
+apk. We expect that the contributors has enough criteria/knowledge to perform
+the other steps mentioned, so let's begin...
+
+To create an apk from a python-for-android pull request 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 also
+expect 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
+^^^^^^^^^^^^
+The first step to do it's to get a copy of the pull request, we can do it of
+several ways, and that it will depend of the circumstances but all the methods
+presented here will do the job, so...
+
+Fetch the pull request by number
+--------------------------------
+For the example, we will use `1901` for the example) and the pull request
+branch that we will use is `feature-fix-numpy`, then you will use a variation
+of the following git command:
+`git fetch origin pull/<#>/head:<local_branch_name>`, eg.::
+
+    .. codeblock:: bash
+
+        git fetch upstream pull/1901/head:feature-fix-numpy
+
+.. note:: Notice that we fetch from `upstream`, since that is the original
+          project, where the pull request is supposed to be
+
+.. tip:: The amount of work of some users maybe worth it to add his remote
+       to your fork's git configuration, to do so with the imaginary
+       github user `Obi-Wan Kenobi` which nickname is `obiwankenobi`, you
+       will do::
+
+          .. codeblock:: bash
+
+              git remote add obiwankenobi https://github.com/obiwankenobi/python-for-android.git
+
+       And to fetch the pull request branch that we put as example, you
+       would do::
+
+          .. codeblock:: bash
+
+              git fetch obiwankenobi
+              git checkout obiwankenobi/feature-fix-numpy
+
+
+Clone the pull request branch from the user's fork
+--------------------------------------------------
+Sometimes you may prefer to use directly the fork of the user, so you will get
+the nickname of the user who created the pull request, let's take the same
+imaginary user than before `obiwankenobi`::
+
+    .. codeblock:: bash
+
+        git clone -b feature-fix-numpy \
+            --single-branch \
+            https://github.com/obiwankenobi/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/obiwankenobi/python-for-android.git`: noticed the
+  nickname of the user that created the pull request: `obiwankenobi` in the
+  middle of the line? that should be changed as needed for each pull
+  request that you want 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
+
+.. tip:: if you don't want to mess up with the system's python, you could do
+          the same steps but inside a virtualenv
+
+.. 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