Small OEP Developer Guide

Allgemeine Erklärung

Die OEP läuft mit dem Webframework Django (https://de.wikipedia.org/wiki/Django_(Framework)). Django unterscheidet zwischen Modellen, Views und Templates.

Modelle (model.py) sind sowas wie sql-alchemy-Strukturen, also Datenbankrepräsentationen. Die OEP benutzt immer zwei verschiedene Datenbanken. Es gibt die OEDB und eine eigene Datenbank. In der eigenen Datenbank wird die Nutzerverwaltung gemacht. Django verwaltet seine Datenbanken allein. Wenn wir irgendetwas ändern wird eine 'migration' ausgeführt. Wenn das passiert, überführt Django von allein die Änderungen in die Datenbank. Modelle dienen im großen und ganzen der Datenkommunikation.

Views sind soetwas wie eine Mittelsperson zwischen dem was ein Nutzer abfragt und dem was zurückgeliefert wird. Wenn eine bestimmte URL angesprochen wird, muss diese auf einen View verweisen. Es laufen eine GET- und eine POST-Methode. Der View definiert, was mit der Anfrage geschehen soll. Zum Beispiel können über die Modelle Daten abgerufen werden. Es wird eine Request-Variable übergeben, in der Informationen stehen über den Nutzer und dessen Kennung stehen. Schließlich hat jeder View eine Render-Methode. Diese gibt an, was für eine Antwort (welche html-Seite) der nutzer auf seine Anfrage bekommt. Die Methode verlinkt auf ein Template.

Templates sind nur zu teilen html. Wir wollen das die seiten alle gleich gestylt aussehen. Es gibt daher ein 'base.html' das eine Standardansicht für die oep definiert. Wir müssen uns nur über inhalt der seite gedanken machen. Das schreibe wir in den content-block. Im template-Ordner ist ein name der app nochmal drin.

Feinheit: Für die einzelnen Apps gibt es eigene Base-Dateien. Wir sollten nicht von der Base-Base erben sondern von der Dataedit-Base.

Workflow Issue in der OEP bearbeiten

(Zum Beispiel bei einem Tippfehler auf der Seite)

Falls noch nicht geschehen, das OEP-Repository clonen:

git clone https://github.com/OpenEnergyPlatform/oeplatform.git

und in das Verzeichnis wechseln:

cd oeplatform

Unmittelbar, nachdem man sich ein Issue aussucht, sollte im Issue angekündigt werden, dass es jetzt in Bearbeitung ist, damit Arbeit nicht doppelt gemacht wird und es auch zu keinen Konflikten kommt.

Für das nachschlagen einer URL schauen wir in die Datei oeplatform/oeplatform/urls.py.

Die URL im Web hat folgende Form https://openenergy-platform.org/ * (z.B. https://openenergy-platform.org/dataedit/) um den Text des Sterns zu finden muss zwischen ^ und / geschaut werden, ist es die Startseite haben wir nur ^. In der selben Zeile steht eine Methode. Diese Methode findet sich nun in dem Ordner des Namensdes Sterns (bei der Startseite, in dem Ordner "base"). In diesem Ordner liegt wiederum eine Datei urls.py. Der Pfad für die URL (bzw. der Teil nach https://openenergy-platform.org/dataedit/) beginnt mit ^ und endet mit $. Dach heißt, hier fängt der Pfad an, Dollar, hier hört er auf. z.B. ^$ zeigt beispielsweise auf https://openenergy-platform.org/ selbst. In der selben Zeile steht eine View-Methode. In diesem Beispiel: views.overview."

In views.py sucht man nach der Methode und findet die Render-Methode mit dem html-template dataedit/dataedit_choices.html. Diese Datei muss verändert werden, um die Seite hinter der entsprechenden URL zu ändern.

In git wird ein neuer feature-branch geöffnet und dorthin gewechselt:

git checkout -b feature/newfeaturebranchname

Der Fehler in der Datei wird behoben. Dann zum Anzeigen, welche Datei wir geändert haben:

git status

Datei für den Commit hinzufügen:

git add dateipfad

und schließlich committen:

git commit

Ein Texteditor öffnet sich. In die Commitnachricht wird in der ersten Zeile (nach Konvention) im imperativ formuliert, was getan wurde. Danach folgt eine Referenz auf das Issue, das hiermit bearbeitet wurde. Dafür reicht eine Raute und die nummer des Issue. Also zum Beispiel:

fix typo #123

Bei umfangreicheren Änderungen folgt eine ausführliche Beschreibung, was genau getan wurde, nach einer Leerzeile darunter. Mit speichern und schließen der Commitnachricht ist der commit gültig. Danach kann hochgeladen werden:

git push

Wirft einen Fehler, weil der Branch beim ersten Upload noch nicht als Upstream gesetzt wurde. Daher:

git push -u origin feature/newfeaturebranchname

Der Commit wird auf gitHub im entsprechenden neuen Branch sichtbar und im Issue wird bei korrekter #Nummer automatisch der Commit referenziert. Bevor man einen pull-request losschickt, überprüft man lokal nochmal, ob es Änderungen gab

git pull

und ob ein merge mit develop Konflikte wirft:

git checkout develop

git merge feature/newfeaturebranchname

Wenn keine Konflikte entstanden sind, kann der Pull-Request in GitHub gestellt werden. In der Dropdownliste der Branches eigenen Branch auswählen und mit einer netten Botschaft und Beschreibung, um einen Pull nach develop bitten. Pull requests sollten am besten thematisch gruppiert, in kleinen Paketen gestellt werden, damit der Hauptentwickler nicht ständig beschäftigt ist, Pull-Requests zu bearbeiten. Riesige Pakete zu schnüren ist aber auch nicht hilfreich. Wenn ein Pull-request akzeptiert wurde, kann der Feature-Branch gelöscht und das Issue geschlossen werden.