Versioning works as follows: vSYSTEM.FEATURE.IMPROVEMENT.BUG-/HOTFIX

See tutorial.

• Primary development is located at gitlab.com.

Development can be done using only docker and docker-compose, then you can skip this step and the node setup.

For the Python dependencies, usage of virtual environments is recommended. All dependencies are listed in requirements.in. Using pip-tools we compile a list of the dependencies with pinned versions, which are contained in requirements.txt. To install the dependencies in a virtual environment, run the following commands:

virtualenv venv/ -p /usr/bin/python3
. venv/bin/activate
pip install pip-tools
pip-sync

The config of viaduct is done using the database. To create an initial database with basic settings configured run:

docker-compose run --rm backend python manage.py createdb

To check that all code has been written in a correct style, we have server side hooks installed. To mirror these hooks client side, the hooks need to be installed. Next to coding style checks, there are also hooks for automatically compiling translations and updating submodules.

Finally, set up the awesome hooks:

cd .git
rm -rf hooks
ln -s ../hooks .
cd ..
.git/hooks/post-merge

On most Linux distributions, just install docker and docker-compose with your favourite package manager. Add your user to the docker group (gpasswd -a $USER docker) so you don't have to use sudo all the time.

On macOS, grab Docker for Mac and install docker-compose with your favourite macOS package manager.

On Windows, God help you.

Note: Only needed for running outside docker

Build dependencies are npm:

• Install Grunt build dependencies and install JSHint:

  • sudo npm install -g grunt-cli
  • sudo npm install -g jshint
  • npm install

• Get a live database of the via server by asking the coordinator. Use it by database by installing mysql and running:

  • docker-compose up database
  • psql -h localhost -p 5400 -d viaduct viaduct -f viaduct.sql

• Add yourself to the administrators group:

  • python manage.py admin add <your name>

Run site with:

docker-compose up

For troubleshooting tips, see bottom of document.

To make changing the database easy you can use the models to update the actual database. There are two times you want to do this. The first one is just for testing your changes locally. If this is the case use these commands to upgrade your actual database.

This will create a new migration script:

python manage.py db migrate --message 'revision message'

After this script is done you can view it to check if nothing weird is going to happen when you execute it. After that, just run the server with docker-compose and it will automatically execute the migration, or run it manually:

python manage.py db upgrade

If this causes errors, something is wrong. Quite possibly the state of the database, if you can't fix it yourself ask for help. If not, you now have an up to date database.

Once you want to push your changes to develop, this is a bit harder to do cleanly. Ask for help here, because it differs from time to time what to do.

All code shall be written in English, translations should be added through Babel. After writing code with English strings, add their Dutch translations.

Creating strings in python is done using the (lazy_)gettext functions.

from flask_babel import _  # in views
from flask_babel import lazy_gettext as _   # in models and forms

For updating translation files after creating new pages, first extract the new translatable strings from the code. Then merge the new extractions with the existing translations:

python venv/bin/pybabel extract -F babel.cfg --sort-output -k lazy_gettext \
    -o messages.pot .
python venv/bin/pybabel update -i messages.pot -d app/translations

Edit the file app/translations/nl/LC_MESSAGES/message.po and add the Dutch translations for the English strings. Especially look for lines marked "fuzzy", since they won't be compiled. If the translation is correct, remove the line marking "fuzzy" and continue.

After that compile the strings to be used in the website:

python venv/bin/pybabel compile -d app/translations

For compiling the strings we have also created a Makefile, that will run these commands in sequence. Just run make to run them.

Documentation according to Python's [Docstring Conventions] (http://www.python.org/dev/peps/pep-0257/).

Idententation is done using 4 spaces. For vim:

set expandtab
set sw=4
set ts=4
set sts=0

Fork project, document nicely. Create pull request with database changes. Use PEP8!

• error: command 'x86_64-linux-gnu-gcc' failed with exit status 1

  Install python-dev.

• IOError: [Errno 13] Permission denied: '/home/username/.pip/pip.log'

  sudo chown username:username /home/username/.pip/pip.log

• ImportError: No module named config

  Make sure you have a config file (see config.py.sample)