1- Development and Contributing
2- ============================
1+ .. _contributing :
32
4- The development of python-for-android is managed by the Kivy team ` via
5- Github <https://github.com/kivy/python-for-android> `_.
3+ Contribution Guidelines
4+ =======================
65
7- Issues and pull requests are welcome via the integrated `issue tracker
8- <https://github.com/kivy/python-for-android/issues> `_.
6+ python-for-android is a complex product used by a large community of developers for free,
7+ but it is built entirely by the contributions of volunteers. We welcome (and rely on)
8+ users who want to give back to the community by contributing to the project.
99
10- Read on for more information about how we manage development and
11- releases, but don't worry about the details! Pull requests are welcome
12- and we'll deal with the rest.
10+ Contributions can come in many forms.
11+
12+ The latest `Kivy Contribution Guidelines
13+ <https://kivy.readthedocs.io/en/master/> `_explain how you can help us, how to submit code, and our
14+ community code of conduct.
15+
16+ .. warning ::
17+ The python-for-android process differs in small but important ways from the Kivy framework's process.
18+ Please read below.
1319
1420Development model
1521-----------------
1622
17- python-for-android is developed using the following model:
23+ Unlike the Kivy framework, python-for-android is developed using the following model:
1824
1925- The ``master `` branch always represents the latest stable release.
2026- The ``develop `` branch is the most up to date with new contributions.
2127- Releases happen periodically, and consist of merging the current ``develop `` branch into ``master ``.
2228
29+ This means pull requests for python-for-android code and documentation submissions should be made
30+ to the ``develop `` branch, not the ``master `` branch.
31+
2332For reference, this is based on a `Git flow
2433<https://nvie.com/posts/a-successful-git-branching-model/> `__ model,
2534although we don't follow this religiously.
@@ -29,8 +38,7 @@ Versioning
2938
3039python-for-android releases currently use `calendar versioning
3140<https://calver.org/> `__. Release numbers are of the form
32- YYYY.MM.DD. We aim to create a new release every four weeks, but more
33- frequent releases are also possible.
41+ YYYY.MM.DD.
3442
3543We use calendar versioning because in practice, changes in
3644python-for-android are often driven by updates or adjustments in the
@@ -42,6 +50,8 @@ while internals are changing.
4250Creating a new release
4351----------------------
4452
53+ (These instructions are for core developers, not casual contributors.)
54+
4555New releases follow these steps:
4656
4757- Create a new branch ``release-YYYY.MM.DD `` based on the ``develop `` branch.
@@ -87,10 +97,10 @@ How python-for-android uses `pip`
8797*Last update: July 2019 *
8898
8999This section is meant to provide a quick summary how
90- p4a (= python-for-android) uses pip and python packages in
100+ python-for-android uses pip and Python packages in
91101its build process.
92- **It is written for a python
93- packagers point of view, not for regular end users or
102+ **It is written for a Python
103+ packager's point of view, not for regular end users or
94104contributors, ** to assist with making pip developers and
95105other packaging experts aware of p4a's packaging needs.
96106
@@ -106,17 +116,17 @@ Basic concepts
106116*(This part repeats other parts of the docs, for the sake of
107117making this a more independent read) *
108118
109- p4a builds & packages a python application for use on Android.
119+ p4a builds & packages a Python application for use on Android.
110120It does this by providing a Java wrapper, and for graphical applications
111- an SDL2-based wrapper which can be used with the kivy UI toolkit if
112- desired (or alternatively just plain PySDL2). Any such python application
113- will of course have further library dependencies to do its work.
121+ an SDL2-based wrapper which can be used with the Kivy framework if
122+ desired (or alternatively just plain PySDL2). Any such the Python application
123+ will likely have further library dependencies to do its work.
114124
115125p4a supports two types of package dependencies for a project:
116126
117- **Recipe: ** install script in custom p4a format. Can either install
118- C/C++ or other things that cannot be pulled in via pip, or things
119- that can be installed via pip but break on android by default.
127+ **Recipe: ** Install a script in custom p4a format. Can either install
128+ C/C++ or other software that cannot be pulled in via pip, or software
129+ that can be installed via pip but break on Android by default.
120130These are maintained primarily inside the p4a source tree by p4a
121131contributors and interested folks.
122132
@@ -131,11 +141,11 @@ Install process regarding packages
131141~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
132142
133143The install/build process of a p4a project, as triggered by the
134- `p4a apk ` command, roughly works as follows in regards to python
144+ `p4a apk ` command, roughly works as follows in regards to Python
135145packages:
136146
1371471. The user has specified a project folder to install. This is either
138- just a folder with python scripts and a `main.py `, or it may
148+ just a folder with Python scripts and a `main.py `, or it may
139149 also have a `pyproject.toml ` for a more standardized install.
140150
1411512. Dependencies are collected: they can be either specified via
@@ -179,16 +189,17 @@ Overall process / package relevant notes for p4a
179189Here are some common things worth knowing about python-for-android's
180190dealing with python packages:
181191
182- - Packages will work fine without a recipe if they would also build
183- on Linux ARM, don't use any API not available in the NDK if they
184- use native code, and don't use any weird compiler flags the toolchain
185- doesn't like if they use native code. The package also needs to
186- work with cross compilation.
192+ - Packages will work fine without a recipe if:
193+
194+ * they would also build on Linux ARM,
195+ * don't use any API not available in the NDK if they use native code, and
196+ * don't use any weird compiler flags the toolchain doesn't like if they use native code.
197+ * works with cross compilation.
187198
188199- There is currently no easy way for a package to know it is being
189200 cross-compiled (at least that we know of) other than examining the
190201 `CC ` compiler that was set, or that it is being cross-compiled for
191- Android specifically. If that breaks a package it currently needs
202+ Android specifically. If that breaks a package, it currently needs
192203 to be worked around with a recipe.
193204
194205- If a package does **not ** work, p4a developers will often create a
@@ -210,16 +221,16 @@ Ideas for the future regarding packaging
210221~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
211222
212223- We in overall prefer to use the recipe mechanism less if we can.
213- In overall the recipes are just a collection of workarounds.
224+ Overall, the recipes are just a collection of workarounds.
214225 It may look quite hacky from the outside, since p4a
215226 version pins recipe-wrapped packages usually to make the patches reliably
216227 apply. This creates work for the recipes to be kept up-to-date, and
217228 obviously this approach doesn't scale too well. However, it has ended
218- up as a quite practical interims solution until better ways are found.
229+ up as a quite practical interim solution until better ways are found.
219230
220231- Obviously, it would be nice if packages could know they are being
221232 cross-compiled, and for Android specifically. We aren't currently aware
222- of a good mechanism for that.
233+ of any good mechanism for that.
223234
224235- If pip could actually run the recipes (instead of p4a wrapping pip and
225236 doing so) then this might even allow build isolation to work - but
0 commit comments