Ontwikkelen met DSMR-reader

Notitie

In dit document zijn er vele referenties naar:

source ~/.virtualenvs/dsmrreader/bin/activate

Je hoeft dit slechts eenmaal per terminal sessie uit te voeren, om er zeker van te zijn dat je in de betreffende virtual env werkt voor DSMR-reader.

Ontwikkelomgeving inrichten voor Ubuntu 18.04

Systeempackages:

sudo apt-get install -y postgresql postgresql-server-dev-all git python3 python3-pip python3-virtualenv virtualenvwrapper libmysqlclient-dev mariadb-server poedit

Kloon DSMR-reader repository van Github:

git clone ... (your fork)
cd dsmr-reader/

Maak virtualenv aan en installeer alle packages:

mkdir ~/.virtualenvs
virtualenv ~/.virtualenvs/dsmrreader --no-site-packages --python python3
source ~/.virtualenvs/dsmrreader/bin/activate
pip3 install -r dsmrreader/provisioning/requirements/base.txt -r dsmrreader/provisioning/requirements/dev.txt

Kopieer de ontwikkel config:

cp dsmrreader/provisioning/django/settings.py.template dsmrreader/settings.py

Open dsmrreader/settings.py en vervang:

from dsmrreader.config.production import *

Met:

from dsmrreader.config.development import *

Kopieer env vars template en genereer een unieke secret key:

cp .env.template .env
./tools/generate-secret-key.sh

Probeer het volgende, de output moet iets zijn in de trend van System check identified no issues (0 silenced).:

./manage.py check

Draai de snelle tests (via in-memory database):

./tools/quick-test.sh

Stel PostgreSQL testdatabase in:

sudo -u postgres createuser -DSR dsmrreader
sudo -u postgres psql -c "alter user dsmrreader with password 'dsmrreader';"
sudo -u postgres psql -c "alter user dsmrreader CREATEDB;"

Stel MySQL (of MariaDB) testdatabase in:

mysql_tzinfo_to_sql /usr/share/zoneinfo | sudo mysql --defaults-file=/etc/mysql/debian.cnf mysql
sudo mysql --defaults-file=/etc/mysql/debian.cnf

# Execute these queries:
GRANT ALL PRIVILEGES ON *.* TO 'dsmrreader'@'localhost' IDENTIFIED BY 'dsmrreader';
FLUSH PRIVILEGES;

Controleer nu of de tests goed draaien met alle drie de database-backends (dit kan even duren):

./tools/test-all.sh

Initiele gegevens om mee te ontwikkelen

De beste gegevens om mee te ontwikkelen zijn eerlijk gezegd simpelweg gegevens uit je eigen productieomgeving.

Importeer deze zoals je dat ook zou doen op je RaspberryPi. Kopieer een database-backup naar /var/lib/postgresql op je PC en importeer deze met:

# Create empty database if it does not exist yet.
sudo -u postgres createdb -O dsmrreader dsmrreader

# For .SQL
sudo -u postgres psql dsmrreader -f <PATH-TO-POSTGRESQL-BACKUP.sql>

# For .SQL.GZ
zcat <PATH-TO-POSTGRESQL-BACKUP.sql.gz> | sudo -u postgres psql dsmrreader

Waarschuwing

N.B.: Voorkom dat je (achtergrond)processen draait in je lokale DSMR-reader ontwikkelomgeving, totdat je alle externe diensten hebt ontkoppeld.

Voer simpelweg het volgende uit, na het importeren van een backup uit je eigen productieomgeving:

source ~/.virtualenvs/dsmrreader/bin/activate
./manage.py development_reset

Dit verwijdert alle API-keys en andere koppelingen naar externe systemen. Tevens wordt de admin-gebruiker gereset naar admin / admin (gebruiker / wachtwoord).

Nep datalogger

Er is een ingebouwd command voor een soort van datalogger die nepdata genereert:

source ~/.virtualenvs/dsmrreader/bin/activate
./manage.py dsmr_fake_datasource --with-gas --with-electricity-returned

Deze genereert elke seconde willekeurige gegevens in een bepaald patroon en is vaak meer dan afdoende voor simpele testdoeleinden.

N.B.: Hiermee worden alleen onverwerkte metingen aangemaakt. Je zult ze nog steeds moeten verwerken door ./manage.py dsmr_backend --run-once uit te voeren.

DSMR-reader lokaal draaien

Je kunt de Django-ontwikkelserver draaien met:

source ~/.virtualenvs/dsmrreader/bin/activate
./manage.py runserver

De applicatie is nu bereikbaar op: http://localhost:8000/. Elke codewijziging die je doet, wordt automatisch doorgevoerd en herlaadt de applicatie.

Tests en dekking

DSMR-reader’s test dekking zou zo hoog mogelijk moeten blijven. Het draaien van tests zorgt er ook voor dat de test dekking in detail geanalyseerd wordt.

De makkelijkste manier om tests te draaien is via de in-memory tests:

source ~/.virtualenvs/dsmrreader/bin/activate
./tools/quick-test.sh

Om een enkele app binnen DSMR-reader te testen, geef je deze simpelweg als extra argument op:

source ~/.virtualenvs/dsmrreader/bin/activate
./tools/quick-test.sh dsmr_frontend

Om alle database-backends te testen voer je het volgende uit:

source ~/.virtualenvs/dsmrreader/bin/activate
./tools/test-all.sh

De test dekking zou na het draaien van tests zichtbaar moeten zijn in de terminal. Er zijn tevens gedetaileerde HTML-pagina’s beschikbaar in coverage_report/html/index.html, na het draaien van tests. Je kunt deze openen met je browser om de test dekking in detail te zien per bestand en per regel code.

Notitie

Een mogelijk bijeffect van het draaien van tests is dat hiermee ook .PO-bestanden in de docs/ map bijgewerkt worden. Als je daar geen wijzigingen in hebt gedaan, kun je die door de tests gewijzigde bestanden negeren.

Vertalingen

Je kunt de vertalingen (.PO-bestanden) voor de hoofdapplicatie vinden in dsmrreader/locales/. Om ze te hergenereren voer het ./tools/quick-test.sh script uit, zodat een van de tests de vertalingen opnieuw checkt.

Documentatie bijwerken

De documentatie is onderdeel van de repository en kan (automatisch) gegenereerd worden via Sphinx:

source ~/.virtualenvs/dsmrreader/bin/activate
cd docs/
sphinx-autobuild . _build/html --port 10000

Je kunt nu de documentatie bekijken in je browser op de volgende link: http://127.0.0.1:10000. Wijzigingen die je doorvoert worden direct automatisch bijgewerkt en getoond in je browser, waar Sphinx voor zorgt.

Documentatie vertalen

Vertalingen verlopen via .PO-bestanden met gettext. Hergenereer de .PO-bestanden met:

source ~/.virtualenvs/dsmrreader/bin/activate
cd docs/
make gettext && sphinx-intl update -p _build/locale -l nl

De .PO-bestanden in docs/locale zouden nu opnieuw gegenereerd moeten worden. Je kunt het programma poedit gebruiken om de bestanden te bekijken en te vertalen.

Nadat je de .PO-bestanden hebt bijgewerkt, kun je de resultaten bekijken door de Nederlandse variant van de documentatie lokaal te genereren:

make -e SPHINXOPTS="-D language='nl'" html

Bekijk nu de gegenereerde HTML in je browser door het volgende bestand te openen: docs/_build/html/index.html

Pull requests

Zorg ervoor dat je pull requests altijd laat wijzen naar de development branch van DSMR-reader, gezien master alleen gebruikt wordt voor release-merges.