Entwickler Dokumentation

Development

Voraussetzungen

Folgende Umgebung wird zum Entwickeln vorausgesetzt:

• Entwicklungsumgebung: VS Code
• Node.JS min. in Version 16.x
• Prisma wird als ORM genutzt und sollte global installiert werden, damit dessen Befehle direkt über npx prisma ... aufgerufen werden können: npm install -g prisma
• Docker: Zum Ausführen einer Test-Datenbank während der Entwicklung und zum Bau des ausgelieferten Docker Images. Bitte beachten: An einige Stellen wird der Befehle docker compose ... verwendet. Bei älteren Installationen wird dieser noch wie folgt geschrieben (es handelt sich aber um dieselbe Funktionalität): docker-compose ....

Initialisierung

Derzeit muss das Projekt "rekursive" geklont werden, um die Skill‐Lib, welche als Submodule in einem separaten Repository verwaltet wird, ebenfalls mit auszuchecken. Nachdem das Projekt geklont und VS Code geöffnet wurde, sollten dann die folgenden Schritte durchgeführt werden:

1. Im Projekt sind Empfehlungen für genutzte VS Code Erweiterungen hinterlegt. Bei der erstmaligen Ausführung schlägt VS Code vor diese zu installieren, dem sollte zugestimmt werden.
2. npm install: Installiert die verwendeten Bibliotheken und zwar in der gleichen Version wie sie bisher genutzt wurden (führt kein Upgrade durch, auch wenn inzwischen neuere Versionen verfügbar sind).
3. npx prisma db generate: Generiert den Code um auf die Datenbank über den ORM zugreifen zu können.
4. Dem Projekt liegt eine .env-Datei bei. Diese beinhaltet Default Werte für das spätere Release und sollte ggf. für die Entwicklung lokal angepasst (aber dann nicht commitet) werden.
5. Damit die Version aus der package.json auch in der Swagger-Seite angezeigt wird, wird während des Erstellen des Releases eine Datei erzeugt, die die Version beinhaltet. Diese ist nicht mit eingecheckt und führt daher lokal zu Kompilierfehlern. Diese kann lokal über folgenden Befehl erzeugt werden: npm run versioning oder auch npm run build. Letzter kompiliert das Projekt lokal und kann genutzt werden um Typ-Fehler zu identifizieren.

Entwicklung

1. Eine Datenbank-Test-Instanz sollte gestartet werden. Hierzu wurde bereits ein Befehle der package.json hinzugefügt: npm run db:start
2. Ggf. Sollte ein das Datenbank-Schema angeewendet werden und der Seed (siehe Konfiguration in der .env angewendet werden: npm run db:redeploy
3. Entwicklung
4. Ausführen der Anwendung: npm run start:dev
5. Ausführung der Tests (löscht die lokale Datenbank): npm run test oder npm run test:cov um auch einen Coverage-Report zu erzeugen. Dazu bietet die Seite Architektur einen Überblick über den Aufbau und die verwendeten Frameworks.

Migration

Wenn sich das Datenbank-Schema ändert muss eine Migration erzeugt werden, damit bei den bereits ausgespielten Releases die Datenbank automatisiert angepasst wird. Empfehlenswert ist nicht bei jeder Schemata-Änderung direkt auch eine neue Migration zu erzeugen. Stattdessen sollte die Migration erst zum Release erzeugt werden, so spart man sich unnötige Zwischenschritte, die jeweils potentielle Fehlerquellen bergen. Die wichtigsten Befehle dazu sind:

• npx prisma migrate dev --name <name> Ist der Standardbefehl zum Erzeugen einer neuen Migration mit einem sprechenden Namen. Dabei wird jeweils ein Timestamp vorangestellt, so dass die Migrationen automatisch in der richtigen Reihenfolge sortiert und angewendet werden. Auch wenn dies der Standardbefehl ist, raten wir von der Verwendung ab, da dieser Befehl die Migration erzeugt und direkt ausführt und somit keine Gelegenehit für manuelle Modifikationen lässt.
• npx prisma migrate dev --name <name> --create-only erzeugt nur eine Migration ohne diese lokal einzuspielen. Nun hat man Gelegenheit diese zu reviewen und ggf. anzupassen. Insbesondere bei Umbenennungen sollte man Vorsicht walten lassen, da Spalten/Tabellen mit dem alten Namen gelöscht und mit dem neuen Namen wieder angelegt werden (lässt sich vermutlich basierend auf der Schemata-Spezifikation nicht besser automatisiert bestimmen. Hier sollte man bei einem Review die entsprechenden DROP und CEATE Statements durch Umbenennungen ersetzen.
• npx prisma migrate deploy wendet die Migrationen an. Dieses kann sowohl dafür verwendet werden um eine Migration lokal zu testen (siehe vorheriger Spiegelstrich) als auch die Migrationen im Produktivsystem einzuspielen. Im Hintergrund wird eine Shadow Database angelegt, welche protokolliert welche Migrationen bereits eingespielt wurden. So werden weder Migrationen übersprungen, noch doppelt angewendet. Bei fehlerhaften Migrationen muss die Datenbank aber unter Umständen editiert werden.
• prisma migrate resolve --applied "<name>" kann genutzt werden um manuell eine bereits vorhandene Migration als eingespielt zu markieren.

Erzeugen eines Releases

1. Version in der package.json anpassen.
2. Wir haben die Revision des Releases immer mit einem Tag (Versionsnummer des Releases + Changelog im Kommentar) versehen, um so die Reproduzierbarkeit der Releases zu gewährleisten. Zudem haben wir die Releases (Tag, Changelog und Docker Image) auf der Release-Seite verlinkt, so wird eine Übersichtsseite zu den verschiedenen Releases geboten.
3. Ggf. Tests (Kompilierung für Typ-Fehler, Unit-Tests, ...) durchführen
4. Mit Hilfe Dockerfile das Docker Image erstellen: docker build -t e-learning-by-sse/nm-skill-service:<version>