diff --git a/README.md b/README.md index f2f96655cf..101edfffce 100644 --- a/README.md +++ b/README.md @@ -3,8 +3,8 @@ python-for-android [![Build Status](https://travis-ci.org/kivy/python-for-android.svg?branch=master)](https://travis-ci.org/kivy/python-for-android) [![Coverage Status](https://coveralls.io/repos/github/kivy/python-for-android/badge.svg?branch=master&kill_cache=1)](https://coveralls.io/github/kivy/python-for-android?branch=master) -[![Backers on Open Collective](https://opencollective.com/kivy/backers/badge.svg)](#backers) -[![Sponsors on Open Collective](https://opencollective.com/kivy/sponsors/badge.svg)](#sponsors) +[![Backers on Open Collective](https://opencollective.com/kivy/backers/badge.svg)](#backers) +[![Sponsors on Open Collective](https://opencollective.com/kivy/sponsors/badge.svg)](#sponsors) python-for-android is a packager for Python apps on Android. You can create your own Python distribution including the modules and @@ -69,9 +69,15 @@ We also have [#support Discord channel](https://chat.kivy.org/). ## Contributing -We love pull requests and discussing novel ideas. Check out our -[contribution guide](http://kivy.org/docs/contribute.html) and feel -free to improve python-for-android. +We love pull requests and discussing novel ideas. Check out the Kivy +project [contribution guide](http://kivy.org/docs/contribute.html) and +feel free to improve python-for-android. + +See [our +documentation](https://python-for-android.readthedocs.io/en/latest/contribute/) +for more information about the python-for-android development and +release model, but don't worry about the details. You just need to +make a pull request, we'll take care of the rest. The following mailing list and IRC channel are used exclusively for discussions about developing the Kivy framework and its sister projects: @@ -139,4 +145,3 @@ Support this project by becoming a sponsor. Your logo will show up here with a l - diff --git a/doc/source/contribute.rst b/doc/source/contribute.rst index 8f9d661b26..749fb2ffed 100644 --- a/doc/source/contribute.rst +++ b/doc/source/contribute.rst @@ -1,8 +1,73 @@ -Contributing -============ +Development and Contributing +============================ The development of python-for-android is managed by the Kivy team `via Github `_. Issues and pull requests are welcome via the integrated `issue tracker `_. + +Read on for more information about how we manage development and +releases, but don't worry about the details! Pull requests are welcome +and we'll deal with the rest. + +Development model +----------------- + +python-for-android is developed using the following model:: + +- The ``master`` branch always represents the latest stable release. +- The ``develop`` branch is the most up to date with new contributions. +- Releases happen periodically, and consist of merging the current ``develop`` branch into ``master``. + +For reference, this is based on a `Git flow +`__ model, +although we don't follow this religiously. + +Versioning +---------- + +python-for-android releases currently use `calendar versioning +`__. Release numbers are of the form +YYYY.MM.DD. We aim to create a new release every four weeks, but more +frequent releases are also possible. + +We use calendar versioning because in practice, changes in +python-for-android are often driven by updates or adjustments in the +Android build tools. It's usually best for users to be working from +the latest release. We try to maintain backwards compatibility even +while internals are changing. + + +Creating a new release +---------------------- + +New releases follow these steps: + +- Create a new branch ``release/YYYY.MM.DD`` based on the ``develop`` branch. + - ``git checkout -b release/YYYY.MM.DD develop`` +- Create a Github pull request to merge ``release/YYYY.MM.DD`` into ``master``. +- Complete all steps in the `release checklist `_, + and document this in the pull request (copy the checklist into the PR text) + +At this point, wait for reviewer approval and conclude any discussion that arises. To complete the release: + +- Merge the release branch to the ``master`` branch. +- Also merge the release branch to the ``develop`` branch. +- Tag the release commit in ``master``. Include a short summary of the changes. +- Create the release distributions: ``python3 setup.py sdist`` +- Upload the release to pypi: ``python3 -m twine upload``. +- Upload the release ``.tar.gz`` to the Github tag. + +.. _release_checklist: + +Release checklist +~~~~~~~~~~~~~~~~~ + +- [ ] Check that the [build is passing](https://travis-ci.org/kivy/python-for-android) +- [ ] Run the tests locally via `tox`: this performs some long-running tests that are skipped on Travis. +- [ ] 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. +- [ ] Build and run the following [testapps](https://github.com/kivy/python-for-android/tree/master/testapps) for arch `armeabi-v7a` and `arm64-v8a`: + - [ ] `python3 setup_testapp_python3_sqlite_openssl.py apk` + - [ ] `python3 setup_testapp_python2.py apk` +- [ ] Check that the version number is correct