Maintainer Guide

This guide provides an overview of the basic steps required for testing, creating new releases, and deploying new builds of the framework. For installation instructions, refer to the installation guide [here].

As of November 2019 (v0.4.3), the framework’s Continuous Integration (CI) pipeline is based primarily on Travis CI and Docker Hub. Automated conda builds have slowly been getting harder and harder to fix on Travis, and have gradually been phased out in favor of installation from source.

Maintainers are expected to be using an installation from source and running on a platform that supports Makefiles. All commands below are also provided under the assumption that they will be executed from the root directory of the framework.

Testing

The simplest way to test whether local changes have broken something in the framework is to use make:

$ make test-all

This command will start by running linters (flake8, isort, twine, check-manifest), and then execute all tests and produce a coverage report. To only run the linters, you can use:

$ make check

The framework tests are based on pytest, and can be executed indenpendently via:

$ make test

Since Travis CI runs on GPU-less platforms, unit tests and integration tests with mocked device-aware components are preferred. Future regression tests should also keep this limitation in consideration.

Tests can leave some logs and artifacts in the working directory, especially if they are cancelled in the middle of a run. To get rid of these, you can use:

$ make clean-test

Releases

To tag a commit for a release, you should use bumpversion. It is pre-configured to update all framework version references everywhere and automatically create a new commit with the required tag. Bumping the version works by incrementing the patch (v0.0.X), minor (v0.X.0) or major (vX.0.0) integer:

$ bumpversion patch
    or
$ bumpversion minor
    or
$ bumpversion major

Creating and pushing any tag on GitHub will trigger the deployment phase on Travis CI.

Documentation

Building the documentation can be accomplished by simply calling:

$ make docs

This will create the documentation pages in HTML format and display them in your browser. The same documentation will be built and deployed on readthedocs.io.

Deployment

Travis CI will automatically attempt to deploy the framework after successfully testing a tagged version. The deployment will target PyPI, Docker Hub, and Anaconda. If any of these steps fail, the deployment can be completed manually as specified below.

Python Package Index (PyPI)

A source distribution (sdist) and be prepared and uploaded using the following commands:

$ python setup.py sdist
$ twine upload dist/* --skip-existing

This will allow you to upload to your own project page, or to the origin (if you have collaborator access).

Docker Hub

A docker image can be prepared and uploaded using the following commands:

$ docker build -t ${DOCKER_REPO}:${TAG} -t ${DOCKER_REPO}:latest .
$ docker push ${DOCKER_REPO}

Again, uploading to the original project page will require collaborator access, but you can also upload the image to your own private repository.

Anaconda

The Anaconda package build process is very long, and requires a lot of disk space. It tends to fail on Travis CI, and must often be completed manually. To do so, you must first configure your conda environment to use custom channels to find proper project dependencies:

$ conda config --prepend channels conda-forge
$ conda config --prepend channels albumentations
$ conda config --prepend channels pytorch

Then, updating conda itself is never a bad idea:

$ conda update -q conda

To build and upload a package, you must also install the correct CLI tools:

$ conda install conda-build conda-verify anaconda-client

Finally, using the meta-config already available inside the project, you can build the package via:

$ conda build ci/

Instructions will be printed in the terminal regarding how to upload the built packages.