Developer Guidelines

1. Aufsetzen der Projektumgebung
2. Definition of Done
3. Verwendete Werkzeuge und Bibliotheken
4. Code Konventionen
5. Struktur des Repos
6. NPM Scripts
7. Github Workflows

Aufsetzen der Projektumgebung

Hier wird beschrieben wie eine Projektumgebung aufgesetzt werden kann. Das Setzen des Mapbox API-Tokens ist erforderlich für das Starten der Anwendung, da ansonsten die Karte nicht angezeigt werden kann.

Empfohlene Projektumgebung

VSCode + Volar + TypeScript Vue Plugin (Volar).

Empfohlene VSCode Plugins sollten automatisch installiert werden, da diese in .vscode/settings.json geteilt werden.

Setzen des Mapbox API Keys

Wichtig: Führe folgende Schritte durch:

1. Erstelle einen neuen Mapbox Token für dieses Projekt. Dabei fallen keine Kosten an, da das kostenlose Kontingent von Mapbox sehr großzügig ist. Es ist besser nicht den Default Token deines Accounts zu benutzen, um den Überblick zu behalten.
2. Im Project Root (d.h. auf oberster Ebene, wo auch die ganzen anderen Konfigurationsdateien liegen), erstelle eine neue Datei .env.local
3. Platziere VITE_MAPBOX_API_KEY=YOUR_API_KEY in dieser Datei, wobei YOUR_API_KEY dein in Schritt 1 erstellter Mapbox API Key ist.

.env.local wird von Git ignoriert, sodass dein API Key nicht öffentlich auf das GitHub Repository hochgeladen wird.

Definition of Done

1. Die angebenen Anforderungen an die Funktionalität ist erreicht.
2. Der Code ist ausreichend dokumentiert.
3. Clean Code Kriterien sind eingehalten.
4. Falls eine kritische Funktion für die Anwendung implementiert wird, muss diese ebenfalls ausreichend durch Unit Tests abgedeckt sein.

Verwendete Werkzeuge und Bibliotheken

Die wichtigsten verwendeten Werkzeuge sind:

• Husky ist zuständig für das Ausführen der Pre-Commit Hooks und ist daher unerlässlich für die lokale Entwicklung. Es wird automatisch initialisiert, wenn die Projektumgebung aufgesetzt wird.
• ESLint wird für das Linten vom Code verwendet.
• Prettier wird für die automatische Formatierung des Codes verwendet.
• commit-lint wird für die automatische Überprüfung der Commit Messages verwendet.

Die wichtigsten verwendeten Bibliotheken sind:

• Vue 3 ist das Framework, welches für die Entwicklung der Anwendung verwendet wird.
• Leaflet ist für die Kartenfunktionalität zuständig und stellt viel Funktionalität für die Interaktion mit Markern bereit.
• Mapbox stellt die Directions und Geocoding API bereit. Die Directions API wird dazu verwendet, indiviuelle Routen (z.B. eines E-Scooters) zur Laufzeit anzufragen und zu cachen. Die Geocoding API wird benutzt, um den Start- und Zielort von Trips von LatLngs in eine Straße umzuwandeln (Reverse Geocoding).

Code Konventionen

Nachfolgend werden die wichtigsten Code Conventions aufgelistet, auf die wir uns im Team geinigt haben und deshalb die für die Entwicklung der Anwendung gelten.

Commit Konventionen

Die Commit-Messages müssen den commit Konventionen folgen. Dies wird automatisch von Commitlint geprüft und bei Fehlern blockiert.

Benennung von Variablen, Konstanten und Weiterem

Die Benennung von Variablen folgt den generellen Typescript-Empfehlungen. Variablen und Funktionen werden in camelCase geschrieben. Dabei unterscheiden wir noch zwischen wirklichen Konstanten, die einmal definiert und nicht mehr geändert werden. Diese werden in UPPER_CASE definiert. Hierbei kann es etwas zu Verwirrung kommen, da in Typescript Variablen mit let und const initialisiert werden können, ESLint jedoch const preferiert. Daher soll laut ESLint auch ein Array, dessen Elemente sich ändern dürfen, mit const initialisiert werden.

Klassen, Interfaces, Enums und Types werden in PascalCase geschrieben. Die Elemente von Enums werden ebenfalls in PascalCase geschrieben.

Formatierung

Die Formatierung des Codes wird von Prettier übernommen und bei jedem Commit automatisch ausgeführt.

Struktur des Repositories

TODO

NPM Scripts

Die folgenden NPM Scripts sind verfügbar: Installiere die Dependencies vorab mittels npm install bzw. npm i.

Compile and Hot-Reload for Development

Dieser Modus aktualisiert Änderungen automatisch, sodass dieser Befehl nicht nach jeder Änderung neu ausgeführt werden muss.

npm run dev

Building for Production

npm run build

Man kann den Produktions-Build per

npm run preview

lokal testen.

Hinweis: Im Gegensatz zu npm run dev muss nach jeder Änderung wieder

npm run build && npm run preview

ausgeführt werden, um diese im Browser zu sehen.

Code Quality

Lint

npm run check-lint
npm run lint

Letztes behebt die (behebaren) Fehler direkt in der Datei.

Format

npm run check-format
npm run format

Typecheck

npm run typecheck

Testing

npm run test:unit
# or
npm run coverage

Pre-Commit Hooks

Die Pre-Commit Hooks werden direkt mit npm i installiert. Manuell können diese mittels npm run prepare aktualisiert werden.

Die Pre-Commits Hooks sind:

• lint (staged-only)
• format (staged-only)
• typecheck (auf allen Files)
• commit-lint: Überprüft die Commit-Messages auf die commit Konventionen.

Github Workflows

Push eines Commits auf den Main Branch

Es werden alle Workflows gestartet, wenn ein Push auf den Main Branch erfolgt.

• Linting und Check auf Formatierung
• Build und Tests durchführen
• Deployment auf Github Pages

Push eines Commits auf einen Feature-Branch

Wenn der Push nicht auf den Main Branch erfolgt, sondern ein auf Feature-Branch, werden nicht immer alle Workflows gestartet.

1. Hat der Branch keine offene Pull-Request, wird nur der Code nur gelintet und auf Formatierung überprüft.

2. Wenn der Branch bereits eine Pull Request geöffnet hat, dann wird zusätzlich bei jedem Push der Build und die Tests durchgeführt.