Contributing

Installing prerequisites

Make sure you have Python 3.6 installed on your system. If you don’t have it yet, follow these instructions.

Resolwe requires PostgreSQL (9.4+). Many Linux distributions already include the required version of PostgreSQL (e.g. Fedora 22+, Debian 8+, Ubuntu 15.04+) and you can simply install it via distribution’s package manager. Otherwise, follow these instructions.

The pip tool will install all Resolwe’s dependencies from PyPI. Installing some (indirect) dependencies from PyPI will require having a C compiler (e.g. GCC) as well as Python development files installed on the system.

Note

The preferred way to install the C compiler and Python development files is to use your distribution’s packages, if they exist. For example, on a Fedora/RHEL-based system, that would mean installing gcc and python3-devel packages.

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

Create a resolwe database:

# Remove database if exists
dropdb resolwe

# Create database
createdb resolwe

Set-up database:

cd tests
./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).

Note

Use Semantic versioning.

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 -m "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.