Skip to content

Best Practices

Jump to bottom
Jennings Zhang edited this page Oct 3, 2022 · 18 revisions

Versioning

Please use semantic versioning.

Version Pinning

Ensure that builds are reproducible by being specific about the versions (aka "freezing") of other software which your ChRIS plugin depends on. Reproducibility means that other people are able to replicate your methods and get the same results.

Docker as a software "containerization" technology guarantees that if your ChRIS plugin can build and run on your computer, then it can be built and run anywhere.

Arbitrary Dependencies

The Dockerfile describes with precision how to install your software from first-principles. Inside Dockerfile you can install anything. The more precise you can be in your Dockerfile, the more "reproducible" it will be.

Hence, it is important to use a specific base image version tag in the FROM line of Dockerfile

  • ✔️ FROM python:3.9.1-buster

  • 👎 FROM fnndsc/ubuntu-python3:latest

You can install whatever else you want into your container image by listing the commands to install them in Dockerfile. For example, let’s say your Python code makes calls to node.js scripts.

Dockerfile
FROM python:3.9.1-buster

RUN apt-get update && apt-get install -y nodejs \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /usr/local/src
COPY . .
RUN pip install .

CMD ["{{ cookiecutter.app_name }}", "--help"]

Python Dependencies

Packages for a specific language are usually installed with a language-specific tool. The project created by cookiecutter-chrisapp is mostly Python. You can add Python dependencies to the install_requires list of setup.py.

After a successful build, track which dependencies you have installed by generating the requirements.txt file.

docker build -t local/pl-app .
docker run --rm local/pl-app pip freeze | grep -v '@ file://' > requirements.txt
git add requirements.txt
git commit -m "Bump requirements.txt"

Release Checklist

  1. Do local test runs. See the Developer’s Guide

  2. Make sure dependency versions in requirements.txt and Dockerfile are correct. See Version Pinning

  3. Publish! See below, Making A Release

Making A Release

To publish a ChRIS plugin, you need to make its parts available in three places:

  • Github for your app’s code

  • DockerHub for your app’s image/executable

  • The ChRIS Store for your app’s description

First, increase the version number in setup.py. See Versioning for advice.

Your next steps depend on your project configuration. If you’ve answered "yes" to publish_from_github_actions, see Automatic Release. Else, you’ll have to do a Manual Release.

Manual Release

Build your ChRIS plugin as a Docker container image with a versioned tag. For example, if your project repository is myorg/pl-dosomething and the version is 1.0.2

docker build -t myorg/pl-dosomething:1.0.2 .
docker push myorg/pl-dosomething:1.0.2

Next, generate a JSON representation of your ChRIS plugin.

docker run --rm myorg/pl-dosomething:1.0.2 dosomething --json > ~/Downloads/description.json

Finally, you can upload ~/Downloads/description.json to https://chrisstore.co/create

Automatic Release

If you are using Automatic Builds from Github Actions, all you need to do is create a git tag. After pushing a tag, Github will automatically build and push your app to DockerHub and the ChRIS Store.

The best and easiest way is to make a Github release. Consult Github Docs for instructions.

Alternatively, you can push a simple git tag.

git tag 1.0.2
git push --tags

Style

Python code style and lint

  • pylint

  • flake8

  • isort

Clone this wiki locally