Development

This project uses Pipenv, which can be installed through Homebrew for Mac users. It must be installed before the Makefile targets, or the other commands listed in this document will work.

In order to run a command which relies on the project virtual environment, such as python foo.py, it is necessary to either run pipenv shell first, which will put you into a shell that has the correct Python installed, or prefix the command with pipenv run (e.g. pipenv run python foo.py).

# Get to work (from within project directory)
# This drops you into a shell inside the project virtual
# environment which means that commands that "pipenv run"
# may be elided from other commands.
pipenv shell

Makefile

A Makefile is available, run make or make help in the project root to see the available targets.

Dependencies

The Makefile has targets for managing dependencies, but it may be easier, particularly for Python developers, to simply invoke Pipenv directly. Example commands are listed below.

If you prefer not to use the Makefile, or if you need to add or remove dependencies, the following commands will allow you to manage dependencies.

# Fetch runtime dependencies
pipenv sync

# Fetch runtime and development dependencies
pipenv sync --dev

# Add a runtime dependency
pipenv install <package>

# Add a development dependency
pipenv install --dev <package>

Unit Tests

Unit tests use pytest. The linked documentation contains examples of how to use it to both write and run tests. The examples are quite extensive.

Documentation tests are also fine for simple cases.

# Run tests
pipenv run python -m pytest

# or
make check-fast check-slow

# or
make check

Docker Container

There is a Dockerfile in the repo root. The image it describes is used for running tests in CI and can be used locally for convenience.

When dependencies change the image must be rebuilt and the new version pushed to Docker Hub. This can be done with make container if you have the correct permissions. Otherwise, ask a maintainer to do it for you.

There is also a file called Dockerfile_run. This is a runner image that is available for users who prefer to run PolyA through Docker (which is often more convenient). The runner image can be built with tool/build-runner-image.sh and, assuming sufficient permissions, pushed to Docker Hub with tool/push-runner-image.sh.

The scripts assume you are building the latest version of the image and so set the latest tag. If this is not the case, it is fairly simple to issue the correct Docker commands manually.

This image can be found on Docker Hub: https://hub.docker.com/repository/docker/traviswheelerlab/polya

Documentation

We use Sphinx for project documentation. Run make docs to update the documentation sources and build the HTML. Use make docs-serve to serve the documentation locally.

Release Process

Generating a new release is a four step process. The first step MUST be completed first, but the rest may be done in any order.

First, update the value of VERSION in polyA/_version.py, incrementing the various portions of the version number accordingly. We would like to follow Semantic Versioning, at least in general. Commit your changes to the master branch.

Second, create a “release” on GitHub. The tag should consist of a “v”, followed immediately by the version number you chose above. For example: v1.2.3.

Third, run make build-package, followed by make publish-package assuming there aren’t any build errors.

Fourth, and finally, create and push a new runner image to Docker Hub. Build the image by running ./tool/build-runner-image.sh, and publish it with ./tool/push-runner-image.sh. The version tag will be set automatically and the latest tag will also be updated.