govoplan/docs/operations/WEBUI_RELEASE_DEPENDENCY_RETRIES.md

# WebUI release dependency installer retries

## English

This operational note covers
[`install-webui-release-dependencies.sh`](../../tools/release/install-webui-release-dependencies.sh)
and the exit-status repair tracked in
[Meta #54](https://git.add-ideas.de/GovOPlaN/govoplan/issues/54).
It applies to release administrators using the legacy runtime WebUI installer;
there are no new application settings, permissions, or end-user workflows.

Each retried npm install or Git clone has at most three attempts. The installer
waits 10 seconds after the first failure and 20 seconds after the second, and
continues immediately after success. If all attempts fail, it exits with the
last command's nonzero status. Its `set -e` execution stops before subsequent
installation stages; callers using `set -e` also stop before subsequent work.
Previously, the retry helper could report success after three failures because
it captured the status of a completed `if` statement instead of the command.

On exhaustion, inspect the npm or Git error and correct the reported cause
before rerunning the installation. The temporary dependency workspace is
removed on exit. Earlier changes to `package.json`, removal of `package-lock.json`,
cache cleaning, and completed dependency installations are not rolled back;
prepare a fresh disposable release workspace when a clean retry is required.

The repair preserves the existing retry count, backoff, cache behavior, and
peer-resolution flags. It does not lift the runtime publication hold tracked in
[Meta #52](https://git.add-ideas.de/GovOPlaN/govoplan/issues/52).
Review the historical `--legacy-peer-deps` workaround separately before lifting
that hold. Strict disposable Git-release and signed catalog verification do not
use this installer; strict release verification must not bypass peer checks.
See [Package Registry Releases](PACKAGE_REGISTRY_RELEASES.md) for release context.

Run the isolated regression suite from the meta repository:

```sh
python3 -m unittest -v tests.test_webui_release_dependency_retries
```

The suite executes the actual Bash installer and a caller using `set -e`, with
local npm, Git, Node, and sleep stubs. It covers success on attempts one, two, and
three, final failure status, backoff, and termination at each retry call site.
It performs no network access, real waiting, or changes to the real npm cache.
It checks shell control flow, not package resolution or runtime publication.

## Deutsch

Dieser Betriebshinweis beschreibt
[`install-webui-release-dependencies.sh`](../../tools/release/install-webui-release-dependencies.sh)
und die unter [Meta #54](https://git.add-ideas.de/GovOPlaN/govoplan/issues/54)
erfasste Korrektur des Rückgabestatus. Er richtet sich an Release-Administratoren,
die den bisherigen WebUI-Installer für Laufzeit-Releases verwenden. Neue
Anwendungseinstellungen, Berechtigungen oder Endanwenderabläufe entstehen nicht.

Jede wiederholte npm-Installation und jeder Git-Klon erhält höchstens drei
Versuche. Nach dem ersten Fehlschlag wartet der Installer 10 Sekunden, nach dem
zweiten 20 Sekunden; nach einem Erfolg fährt er sofort fort. Scheitern alle
Versuche, endet er mit dem letzten von null verschiedenen Rückgabestatus.
Durch `set -e` werden nachfolgende Installationsschritte nicht ausgeführt;
auch aufrufende Skripte mit `set -e` brechen vor ihren nächsten Schritten ab.
Bisher konnte die Hilfsfunktion nach drei Fehlschlägen Erfolg melden, weil sie
den Status der abgeschlossenen `if`-Anweisung statt des Befehls übernahm.

Prüfen Sie nach dem Abbruch die npm- oder Git-Fehlermeldung und beheben Sie deren
Ursache vor einem erneuten Installationslauf. Das temporäre Verzeichnis für
Abhängigkeiten wird beim Beenden entfernt. Vorherige Änderungen an `package.json`,
das Entfernen von `package-lock.json`, die Cache-Bereinigung und abgeschlossene
Installationen werden nicht zurückgerollt. Bereiten Sie bei Bedarf einen neuen
temporären Release-Arbeitsbereich für einen sauberen Wiederholungslauf vor.

Die Korrektur erhält Anzahl und Wartezeiten der Versuche, Cache-Verhalten und
Optionen zur Peer-Auflösung. Die Sperre für Laufzeitveröffentlichungen aus
[Meta #52](https://git.add-ideas.de/GovOPlaN/govoplan/issues/52) bleibt bestehen.
Der bisherige Einsatz von `--legacy-peer-deps` muss vor ihrer Aufhebung gesondert
geprüft werden. Die strenge Git-Release-Prüfung in einem temporären Arbeitsbereich
und die Prüfung signierter Kataloge verwenden diesen Installer nicht; die strenge
Release-Prüfung darf Peer-Prüfungen nicht umgehen. Weitere Zusammenhänge erläutert
[Package Registry Releases](PACKAGE_REGISTRY_RELEASES.md).

Führen Sie die isolierten Regressionstests im Meta-Repository aus:

```sh
python3 -m unittest -v tests.test_webui_release_dependency_retries
```

Die Tests führen den tatsächlichen Bash-Installer und ein aufrufendes Skript mit
`set -e` aus. Lokale Testprogramme ersetzen npm, Git, Node und sleep. Geprüft werden
Erfolge im ersten, zweiten und dritten Versuch, der letzte Fehlerstatus,
Warteintervalle und der Abbruch an jeder Aufrufstelle. Es gibt keine
Netzwerkzugriffe, echten Wartezeiten oder Änderungen am tatsächlichen npm-Cache.
Die Tests prüfen den Shell-Ablauf, nicht die Paketauflösung oder Veröffentlichung.