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

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

Das Repository ist folgt aufgebaut:

1. Generelle Konfigurationsdateien wie package.json oder tsconfig.json liegen im Root des Repos.

2. In public befinden sich unter anderem die vordefinierten Daten wie Trips, Fahrzeuge oder Benutzer.

   public
   └── data
       ├── risk
       ├── trips.json
       ...
       └── vehicles.json
   

3. Unter src befinden sich alle Quelldateien der Anwendung. Diese sind in folgende Ordner aufgeteilt: Hier sind besonders backend sowie components und views interessant. Alle Ornder die nicht unter backend liegen, sind Frontend-bezogen. components enthält alle wiederverwendbaren Vue-Komponenten, die in den Views eingesetzt werden. views enthält die einzelnen Views wie z.B. DefaultView.vue, die vom Vue-Router angesteuert werden können.

   In locales werden die Übersetzungen in JSON-Dateien gespeichert.

    src
    ├── animation
    ├── backend
    │   ├── __tests__
    │   ├── dataFields
    │   ├── dataModules
    │   ├── riskManager
    │   ├── utils
    │   ├── DataLoader.ts
    │   ├── DataManager.ts
    │   ...
    │   └── TripAnimator.ts
    ├── components
    │   ├── MainComponent.vue
    │   ...
    │   └── MapComponent.vue
    ├── locales
    ├── router
    ├── utils
    ├── views
    │   ├── dataViewer
    │   │   ├── DefaultView.vue
    │   │   ├── VehicleDataView.vue
    │   │   ...
    │   │   └── WelcomeView.vue
    │   └── DataView.vue
    ├── App.vue
    ├── i18n.ts
    ...
    └── main.ts
   

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.