Ein selbstprüfendes Ersttags-Setup-Skript: Bootstrap, Doctor, Smoke-Test

Ziel

Eine neu einsteigende Person oder ein Agent führt nach dem Klonen einen Befehl aus und erhält entweder eine funktionierende Umgebung oder eine präzise Liste dessen, was fehlt und wie es behoben wird; bei erneutem Ausführen meldet der Befehl, dass nichts zu tun ist.

Voraussetzungen

Eine Liste dessen, was das Projekt braucht: Laufzeitumgebungen und ihre Versionen, Paketmanager, Systembibliotheken, Dienste (Datenbank, Cache), Zugangsdaten und ihre Herkunft, sowie für jeden Punkt eine Prüfung, die dessen Vorhandensein belegt. GitHubs Muster «Scripts To Rule Them All» liefert die Aufteilung, der diese Methodik folgt: script/bootstrap dient ausschliesslich dazu, die Abhängigkeiten des Projekts zu erfüllen, script/setup versetzt das Projekt nach einem Klon in seinen Ausgangszustand, script/update läuft nach einem Pull, und script/test führt die Testsuite aus. Homebrews Befehl doctor, dessen Manpage ihn als Prüfung des Systems auf mögliche Probleme mit einem Exit-Status ungleich null bei Funden beschreibt, ist das Vorbild für die Prüfhälfte.

Schritte

1. Zuerst das Doctor-Skript schreiben: eine nur lesende Prüfung, die pro Voraussetzung eine Zeile mit PASS, FAIL oder WARN ausgibt, dazu den gefundenen Wert, den erwarteten Wert und den Korrekturbefehl. Es ändert nichts und beendet sich bei jedem FAIL mit einem Status ungleich null.
2. Bootstrap als Abfolge idempotenter Schritte schreiben, jeder abgesichert durch die passende Doctor-Prüfung: nur installieren, was fehlt, Versionen aus dem Versions-Manifest des Repositorys übernehmen, überspringen, was bereits korrekt ist.
3. Bootstrap damit abschliessen, doctor und dann einen Smoke-Test auszuführen: das schnellste Testziel, --help der gebauten Binärdatei oder eine Anfrage an den lokalen Health-Endpunkt. Der Exit-Status des Skripts ist der des Smoke-Tests.
4. Jeden Schritt nicht interaktiv gestalten; Eingabeaufforderungen blockieren Agenten und CI. Zugangsdaten aus Umgebungsvariablen oder einer dokumentierten Datei lesen und ihr Fehlen als FAIL mit einem Link melden, nicht mit einer Eingabeaufforderung.
5. Ausgeben, was getan wurde und wie lange es dauerte, und dasselbe in eine Log-Datei schreiben, die ein fehlgeschlagener Lauf einem Bug-Report beifügen kann.
6. Bootstrap regelmässig auf einer sauberen Maschine oder in einem Container in der CI ausführen; ein Setup-Skript, das nur Neueinsteigende ausführen, veraltet zwischen den Neueinsteigenden.
7. Jeden Fehlschlag einer neu einsteigenden Person als Bug in doctor behandeln: Hat keine Prüfung ihn erfasst, die Prüfung hinzufügen, bevor die Umgebung korrigiert wird.

Erwartetes Ergebnis

Setup-Fehlschläge werden konkret («PostgreSQL 16 erwartet, 14 gefunden; den angegebenen Upgrade-Befehl ausführen») statt eines Stack Trace vom ersten Befehl, der das fehlende Teil benötigte.

Grenzen und Prüfbasis

Die Kosten liegen in der Plattformabdeckung: Für jedes unterstützte Betriebssystem müssen eigene Prüfungen und Korrekturen gepflegt werden. Das Skript kann nicht verifizieren, was es nicht beobachten kann (ein VPN, eine anderswo erteilte Berechtigung), sondern nur, dass eine Prüfung fehlgeschlagen ist. Dies ist ein vorgeschlagenes Protokoll; es werden keine Ergebnisse zu Verbreitung oder Zeitersparnis behauptet.