isy-angular-widgets – Widget-Bibliothek für Angular-Anwendungen der öffentlichen Verwaltung

Contributing Guidelines

Zielgruppe

Diese Datei richtet sich an Entwicklerinnen und Entwickler, die den Baustein selbst weiterentwickeln. Sie beschreibt den Einstieg in das Repository: Aufbau, lokales Setup, Skripte und Qualitätssicherung.

Du möchtest die Bibliothek in einer eigenen Anwendung verwenden? Dann ist die README der Bibliothek der richtige Einstieg. Dort stehen Installation, Konfiguration und die Dokumentation der einzelnen Widgets. Hinweise zu Breaking Changes zwischen zwei Versionen enthält die MIGRATION.md.

Repository-Struktur

Das Repository ist ein Angular-Workspace mit zwei Projekten:

Ergänzend relevant:

├── .github/workflows/   CI-Pipelines (Build, Test, Pages-Deploy, npm-Publish)
├── docs/                Antora-Konzeptdokumentation
├── tools/               Hilfsskripte für Build und Pages-Deployment
├── CHANGELOG.md         Änderungen je Version
└── CONTRIBUTING.md      Branch-Modell, Commit-Konventionen, Pull Requests

Die Demo-Anwendung wird für beide unterstützten Versionslinien veröffentlicht:

Erste Schritte

Voraussetzungen

Das Projekt setzt die in der package.json unter engines definierte Node.js-Version voraus. Die CI baut und testet mit Node.js 24.

Repository klonen und Abhängigkeiten installieren

git clone https://github.com/IsyFact/isy-angular-widgets.git
cd isy-angular-widgets
npm install

Die Abhängigkeiten müssen auch nach dem Ergänzen neuer Pakete erneut installiert werden.

Demo-Anwendung starten

Die Demo-Anwendung ist der schnellste Weg, Änderungen an der Bibliothek sichtbar zu machen:

npm run start

npm-Skripte

Hinweis: compodoc:build legt die erzeugte API-Dokumentation im Verzeichnis docs/ ab, in dem auch die Antora-Konzeptdokumentation liegt. Die generierten Dateien sind nicht in der .gitignore enthalten und sollten vor einem Commit wieder entfernt werden:

Example :

git clean -fd docs/

Qualitätssicherung

Die folgenden Prüfungen entsprechen den zentralen Schritten der CI-Pipeline und sollten vor jedem Pull Request lokal fehlerfrei durchlaufen:

npm run prettier:check
npm run lint
npm test
npm run build:widgets_lib
npm run build:widgets_demo

Zusätzlich führt die CI einen Compodoc-Build, eine SBOM-Erzeugung und einen SonarCloud-Scan aus.

Pull Requests, welche die CI-Checks nicht erfüllen, werden ungesichtet abgelehnt. Details dazu stehen in der CONTRIBUTING.md.

E2E-Tests

Für die Demo-Anwendung sind exemplarisch einige E2E-Tests mit TestCafe umgesetzt. TestCafe ist keine Abhängigkeit des Repositorys und wird beim Aufruf über npx nachgeladen.

Vor der Ausführung muss die Demo-Anwendung unter http://localhost:4200 laufen (npm run start). Das Skript startet Chrome im Headless-Modus; alternativ kann im e2e-Skript ein anderer Browser eingetragen werden.

npm run e2e

Hinweis für macOS: TestCafe benötigt die Berechtigung zur Bildschirmaufnahme. Ohne diese bricht der Lauf mit UnableToAccessScreenRecordingAPIError ab. Die Berechtigung wird unter Systemeinstellungen → Datenschutz & Sicherheit → Bildschirmaufnahme für TestCafe Browser Tools erteilt.

Bibliothek lokal in einem anderen Projekt testen

Um einen Entwicklungsstand vor dem Release in einer echten Anwendung zu prüfen, wird die Bibliothek gebaut und als TGZ-Paket verpackt:

npm run build-and-pack:widgets_lib

Das Paket liegt anschließend unter dist/isy-angular-widgets, zum Beispiel:

dist/isy-angular-widgets/isyfact-isy-angular-widgets-0.0.0.tgz

Im Zielprojekt wird das Paket über den Pfad zur TGZ-Datei installiert:

npm install "file:[WIDGETS_LIB_PATH].tgz"

Unter Angular 22 ist wegen der Peer-Dependencies von PrimeNG 21 zusätzlich --legacy-peer-deps erforderlich:

npm install "file:[WIDGETS_LIB_PATH].tgz" --legacy-peer-deps

Anschließend kann die Schematic der Bibliothek ausgeführt werden:

npx ng generate @isyfact/isy-angular-widgets:ng-add
npm install --legacy-peer-deps

Hinweis: ng add sollte nicht direkt auf die lokale TGZ-Datei angewendet werden, da die Angular CLI die Paketinformationen lokaler Dateien unter Umständen nicht korrekt ausliest.

Der Schematic-Lauf endet in Angular-22-Projekten mit der Meldung The Schematic workflow failed.; die Konfiguration ist zu diesem Zeitpunkt bereits vollständig geschrieben. Details dazu stehen in der README der Bibliothek.

Hintergründe zur Versionskombination aus Angular 22 und PrimeNG 21 stehen in der MIGRATION.md.

Wartungsaufgaben

Browser-Support-Konfiguration generieren

Die unterstützten Mindest-Browser-Versionen sind statisch in der Bibliothek hinterlegt:

projects/isy-angular-widgets/src/lib/browser-support/browser-support.config.json

Die Datei wird über folgendes Skript erzeugt:

npm run generate-browser-support

Das Skript ermittelt die Browser-Versionen anhand der Browser-Support-Regeln des aktuellen Angular-Major-Releases. Die generierte Datei ist Bestandteil der Bibliothek und muss eingecheckt werden. Nach einem Update auf ein neues Angular-Major-Release ist das Skript erneut auszuführen.

Die HauptfensterComponent wertet diese Konfiguration beim Laden der Anwendung aus und zeigt bei einer nicht unterstützten Browser-Version eine Warnmeldung an. Die Prüfung ist standardmäßig aktiviert und lässt sich über das Input-Property checkBrowserVersion deaktivieren:

<isy-hauptfenster [checkBrowserVersion]="false">
  <!-- Anwendungscode -->
</isy-hauptfenster>

Releases erstellen

Releases werden über eine GitHub Action erzeugt, die ausgeführt wird, sobald ein Tag mit einer gültigen Versionsnummer nach SemVer erstellt wird. Die Versionsnummer wird dabei automatisch in die package.json der gebauten Bibliothek eingetragen.

Die Versionsnummer muss deshalb nicht manuell in der package.json gepflegt werden – dort steht dauerhaft 0.0.0.

Die Vorbereitung eines Releases erfolgt über einen Branch nach dem Schema release/<planned-version>. Details dazu stehen in der CONTRIBUTING.md.

Weiterführende Dokumentation

Lizenz

Veröffentlicht unter der Apache-2.0-Lizenz.