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.