Version Control, Continuous Integration and Deployment

For the use of git version control, there are two major branches, master and dev. The master branch is the default branch when a user downloads the source code from GitHub. It is recommended to keep this branch a relatively stable branch and only merge in new codes when they are reliable. The dev branch is intended to be the developing branch for a single maintainer.

For the version number, we suggest the three-part version number convention: [major version.minor version.patch]. For example, version 2.1.0 means major version 2, minor version 1, and patch 0. Major version should increase when there are large updates or a change of old APIs; minor version should increase when there are new features; patch number increases when it’s a bug fix. To tag a version, it is done on the GitHub repository webpage, so that new versions will trigger a release and the following deployment.

The software requires optionally a compiled C library. For users installing the software directly from The Python Package Index (PyPI) via pip command, Python will first check if a compiled binary file (called wheel) for the C library exists on PyPI and download the binary if so. Otherwise, it will try to compile the C library locally from the source code. We call uploading the source code and the compiled binary for Windows and macOS deployment.

As defined in .travis.yml, for each commit pushed to GitHub, Travis-CI will first run the tests under different platforms, notify the repository owner if tests fail, and try to deploy the code to PyPI. The branches also influence the behavior of the deployment. The current setting is that, for each new commit to dev branch, Travis-CI will try to deploy the software on test.pypi if there is not a duplicate version already, which usually means the version number defined in setup.py is updated. For the master, Travis-CI will not try to deploy the software to the official PyPI unless it’s tagged on GitHub as a new release.

Apart from Travis-CI, readthedocs also monitors new commits to the GitHub. It will create the online document you are now reading for any commits to the master and the dev branch, creating latest and dev version of the document. For any tagged version it will create a stable version of the document.