Contributing

Installing prerequisites

Resolwe runs on Python 3.6 or later If you don’t have it yet, follow these instructions.

It’s easiest to run other required services in Docker containers, which is assumed in this tutorial. If you don’t have it yet, you can follow the official Docker tutorial for Mac and for Windows or install it as a distribution’s package in most of standard Linux distributions (Fedora, Ubuntu,…).

Preparing environment

Fork the main Resolwe’s git repository.

If you don’t have Git installed on your system, follow these instructions.

Clone your fork (replace <username> with your GitHub account name) and change directory:

git clone https://github.com/<username>/resolwe.git
cd resolwe

Prepare Resolwe for development:

pip install -e .[docs,package,test]

Note

We recommend using pyvenv to create an isolated Python environment for Resolwe.

Preparing database

Start Docker containers:

cd tests
docker-compose up --detach

Set-up database:

./manage.py migrate
./manage.py createsuperuser --username admin --email admin@genialis.com

Registering processes

cd tests
./manage.py register

Running tests

To run the tests, use:

cd tests
./manage.py test resolwe --parallel=2

To run the tests with Tox, use:

tox -r

Building documentation

python setup.py build_sphinx

Submitting changes upstream

Signed commits are required in the Resolwe upstream repository. Generate your personal GPG key and configure Git to use it automatically.

Preparing release

Checkout the latest code and create a release branch:

git checkout master
git pull
git checkout -b release-<new-version>

Replace the Unreleased heading in docs/CHANGELOG.rst with the new version, followed by release’s date (e.g. 13.2.0 - 2018-10-23).

Commit changes to git:

git commit -a -m "Prepare release <new-version>"

Push changes to your fork and open a pull request:

git push --set-upstream <resolwe-fork-name> release-<new-version>

Wait for the tests to pass and the pull request to be approved. Merge the code to master:

git checkout master
git merge --ff-only release-<new-version>
git push <resolwe-upstream-name> master <new-version>

Tag the new release from the latest commit:

git checkout master
git tag -sm "Version <new-version>" <new-version>

Note

Project’s version will be automatically inferred from the git tag using setuptools_scm.

Push the tag to the main Resolwe’s git repository:

git push <resolwe-upstream-name> master <new-version>

The tagged code will we be released to PyPI automatically. Inspect Travis logs of the Release step if errors occur.

Preparing pre-release

When preparing a pre-release (i.e. an alpha release), one can skip the “release” commit that updates the change log and just tag the desired commit with a pre-release tag (e.g. 13.3.0a1). By pushing it to GitHub, the tagged code will be automatically tested by Travis CI and then released to PyPI.