|
| 1 | +# Releasing python-for-android |
| 2 | + |
| 3 | +This document describes the release process for python-for-android. It is |
| 4 | +intended for core developers who cut new releases. Casual contributors do |
| 5 | +not need to read it. |
| 6 | + |
| 7 | +## Versioning |
| 8 | + |
| 9 | +python-for-android uses [calendar versioning](https://calver.org/) of the |
| 10 | +form `YYYY.MM.DD` (e.g. `2026.05.09`). Calendar versioning is used because |
| 11 | +changes are often driven by Android build-tool updates, so users generally |
| 12 | +want the latest release. Backward compatibility is preserved across |
| 13 | +releases where possible. |
| 14 | + |
| 15 | +The single source of truth for the version is |
| 16 | +[`pythonforandroid/__init__.py`](pythonforandroid/__init__.py). `setup.py` |
| 17 | +parses `__version__` from that file and exposes it as the package version. |
| 18 | + |
| 19 | +## Branching model |
| 20 | + |
| 21 | +- `master` always represents the latest stable release. |
| 22 | +- `develop` is the active development branch and the target for all PRs. |
| 23 | +- Release branches `release-YYYY.MM.DD` are cut from `develop` for each |
| 24 | + release, then merged into both `master` and back into `develop`. |
| 25 | + |
| 26 | +## Release steps |
| 27 | + |
| 28 | +1. **Cut a release branch** from an up-to-date `develop`: |
| 29 | + |
| 30 | + ```bash |
| 31 | + git checkout develop && git pull |
| 32 | + git checkout -b release-YYYY.MM.DD |
| 33 | + ``` |
| 34 | + |
| 35 | +2. **Bump the version** in |
| 36 | + [`pythonforandroid/__init__.py`](pythonforandroid/__init__.py). |
| 37 | + |
| 38 | +3. **Regenerate `CHANGELOG.md`** using |
| 39 | + [`github-changelog-generator`](https://github.com/github-changelog-generator/github-changelog-generator). |
| 40 | + |
| 41 | +4. **Open a pull request** from `release-YYYY.MM.DD` targeting `master`. |
| 42 | + Copy the [release checklist](#release-checklist) into the PR |
| 43 | + description and tick items off as they are validated. |
| 44 | + |
| 45 | +5. **Wait for review and complete the checklist** before merging. |
| 46 | + |
| 47 | +6. **Merge the release branch into `master`**, then merge it back into |
| 48 | + `develop` so the version bump and changelog land on both branches. |
| 49 | + |
| 50 | +7. **Tag the release commit on `master`** with an annotated tag: |
| 51 | + |
| 52 | + ```bash |
| 53 | + git checkout master && git pull |
| 54 | + git tag -a vYYYY.MM.DD -m "Release YYYY.MM.DD" |
| 55 | + git push origin vYYYY.MM.DD |
| 56 | + ``` |
| 57 | + |
| 58 | + Tags follow the format `vYYYY.MM.DD`. |
| 59 | + |
| 60 | +8. **PyPI upload happens automatically** when the tag is pushed. The |
| 61 | + [`pypi-release.yml`](.github/workflows/pypi-release.yml) workflow |
| 62 | + builds `sdist` and `bdist_wheel`, runs `twine check`, and uploads via |
| 63 | + the `pypi_password` token. Non-tag pushes still build and check the |
| 64 | + artifacts but do not publish. |
| 65 | + |
| 66 | +9. **Create the GitHub Release** at |
| 67 | + <https://github.com/kivy/python-for-android/releases> from the new |
| 68 | + tag. Use GitHub's "Generate release notes" feature to auto-fill the |
| 69 | + title and description from merged PRs since the previous tag, then |
| 70 | + tweak as needed. |
| 71 | + |
| 72 | +10. **Announce the release on Discord** in the |
| 73 | + [#announcements](https://discord.com/channels/423249981340778496/490505571271704577) |
| 74 | + channel. Include the version number and a link to the GitHub |
| 75 | + release page. |
| 76 | + |
| 77 | +## Release checklist |
| 78 | + |
| 79 | +Use this as the PR description for the release branch. |
| 80 | + |
| 81 | +- [ ] Check that the builds are passing |
| 82 | + - [ ] [GitHub Action](https://github.com/kivy/python-for-android/actions) |
| 83 | +- [ ] Run the tests locally via `tox`: this performs some long-running tests that are skipped on github-actions. |
| 84 | +- [ ] Build and run the [on_device_unit_tests](https://github.com/kivy/python-for-android/tree/master/testapps/on_device_unit_tests) app using buildozer. Check that they all pass. |
| 85 | +- [ ] Build (or download from github actions) and run the following [testapps](https://github.com/kivy/python-for-android/tree/master/testapps/on_device_unit_tests) for arch `armeabi-v7a` and `arm64-v8a`: |
| 86 | + - [ ] on_device_unit_tests |
| 87 | + - [ ] `armeabi-v7a` (`cd testapps/on_device_unit_tests && PYTHONPATH=.:../../ python3 setup.py apk --ndk-dir=<your-ndk-dir> --sdk-dir=<your-sdk-dir> --arch=armeabi-v7a --debug`) |
| 88 | + - [ ] `arm64-v8a` (`cd testapps/on_device_unit_tests && PYTHONPATH=.:../../ python3 setup.py apk --ndk-dir=<your-ndk-dir> --sdk-dir=<your-sdk-dir> --arch=arm64-v8a --debug`) |
| 89 | +- [ ] Check that the version number is correct |
0 commit comments