comparing-risks/doc/04_development.md

Build Tool Chain

In diesem Abschnitt werden die technischen Voraussetzungen für die Erstellung von im Browser lauffähigem Code und und die Installation und Verwendung der Entwicklungsumgebung erläutert.

Voraussetzungen

Dieses Projekt wurde entwickelt auf Basis von nodejs unter Verwendung von npm als Paket-Manager. Mit den folgenden Versionen wurde zuletzt getestet:

nodejs: v14.4.0
   npm:  6.14.4

Alle Abhängigkeiten sind definiert in der npm Konfigurations-Datei package.json. Wie üblich werden diese installiert mit dem Befehl npm install. Als Task-Manager dieses Projekts wird gulp dabei global installiert.

Für das Erstellen der Dokumentation aus den einzelnen Markdown-Dateien, die im Verzeichnis doc/ liegen, wird pandoc verwendet. Dieses ist für viele Betriebssysteme und Distributionen verfügbar, muss aber gesondert installiert werden.

Konfiguration

Die Build Konfiguration ist in config.js im Wurzelverzeichnis definiert. Außerdem sind in der Datei package.json die zu unterstützenden Browser-Versionen für autoprefixer angegeben.

Konfigurationen für Babel, Editoren und Linter sind ebenfalls im Wurzelverzeichnis zu finden:

       babel: .babelrc
editorconfig: .editorconfig
        html: .htmlhintrc
  javascript: .eslintrc.yml
        sass: .sass-lint.yml

Erstellen von Builds

Alle Schritte zum Erstellen von Builds sind in den Javascript-Dateien unter tasks/ definiert und werden von der gulp Konfigurationsdatei gulpfile.babel.js importiert. Dort sind die Teilschritte in Tasks zusammengefasst, die man am häufigsten benötigt.

$ gulp        # Default task, Kurzform für 'gulp watch'
$ gulp build  # Erstellt einen Development Build
$ gulp watch  # Erstellt einen Development Build und startet den Entwicklungsserver

Build Target

Die Unterscheidung zwischen Development und Production Build wird anhand der nodejs Umgebungsvariable NODE_ENV vorgenommen. Ohne diese Angabe wird immer ein Development Build erstellt (siehe config.js). Für das Development Target werden Javascript und CSS zusätzlich mit Sourcemaps versehen, für die Produktiv-Version dagegen werden die Dateien von unnötigem Ballast befreit (terser für Javascript, cssnano für CSS).

# Erstellen eines Production Build
$ NODE_ENV=production gulp build

Build Mode

Zusätzlich gibt es für dieses Projekt die Unterscheidung zwischen 'online' und 'offline' Versionen. Im Fall der 'online' Version wird auf eine API zugegriffen, um die benötigten Inhalte zu laden, und um die Antworten der Benutzer zu speichern, um ihnen einen Vergleich mit Anderen zu ermöglichen. Diese Unterscheidung kann beim Aufruf von gulp auf der Kommandozeile mit einem Parameter getroffen werden. Soweit verfügbar, wird standardmäßig der 'online' Modus verwendet, (siehe config.js).

# Erstellen eines Development Build für den 'offline' Modus
$ gulp --api-mode=offline

npm Shortcuts

Da die Handhabung mit dem Setzen der Umgebungsvariable und das Übergeben des Parameters etwas umständlich ist, sind in package.json npm ein paar Shortcuts definiert, z.B.:

# Erstellen eines Production Build für den 'offline' Modus per gulp Script
$ NODE_ENV=production gulp build --api-mode=offline

# Erstellen eines Production Build für den 'offline' Modus per npm Script
$ npm run build:prod:offline

Erstellen der Dokumentation

Die Dokumentation in einzelne Markdown-Dateien aufgeteilt, die im Verzeichnis doc/ liegen. Zum Erstellen einer zusammenhängender Dokumentation sind folgende npm Scripts definiert, die auf pandoc basieren:

npm build:doc       // Kurzform für das Erstellen der Dokumentation im bevorzugten Ausgabeformat (Standard: Markdown)
npm build:doc:html  // Erstellt eine HTML Dokumentation als `index.html` in `doc/html`
npm build:doc:md    // Erstellt eine zusammenhängende Dokumentation als `readme.md` im Wurzelverzeichnis

Konventionen

Der Javascript Code ist in ES6 (bzw. ES2015) verfasst. Als CSS-Preprocessor wird Sass mit der scss Syntax verwendet. Die Code Style Konventionen wurden von den ursprünglichen Entwicklern übernommen und nur an wenigen Stellen leicht angepasst.

Das Projekt verwendet editorconfig für die Integration dieser Konventionen in Editoren, die entsprechende Datei heißt .editorconfig.

Für die statische Überprüfung des Quellcodes werden folgende Linter verwendet:

• Javascript: eslint
• Sass: sass-lint
• HTML: HTMLHint

Die zugehörigen Konfigurationsdateien befinden sich im Root-Verzeichnis, wie oben in der Auflistung angegeben.