major
#29707
Verkürzung der PR-CI-Build-Zeit: paralleler Reaktor-Build, auf Shards verteilte skriptgesteuerte Tests, Builds der betroffenen Module
Problem
Ein PR-Build in Jenkins Build_Git (saubere Installation von spotbugs:spotbugs, Tests auf H2) dauert tagsüber 98–108 Minuten und 77–79 Minuten, wenn er alleine ausgeführt wird. Laufzeiten pro Modul (Builds #16353, #16350):
| = Teil = | = Dauer = | = Anteil = |
| tl-demo: test.com.top_logic.layout.scripting.ScriptedTest (600 skriptgesteuerte Tests, eine JVM) | 33 min (Modul 34,5 min) | ~35 % |
| tl-core | 9,6 Min. | ~10 % |
| tl-element | 3,2 min | ~3 % |
| ~125 verbleibende Module à ca. 20–30 s (Bereinigung, Kompilierung, Konformitätstest mit TestAll ~10 s, Doclet, SpotBugs, Installation) | ~45 min | ~50 % |
Der Build verläuft streng sequenziell: Der Job ist ein Jenkins-„Maven-Projekt“ ohne -T; die Modulzeiten summieren sich auf 94 Min. Die längste Abhängigkeitskette im Reaktor beträgt nur 58 Min., davon entfallen 36 Min. auf tl-demo sowie das danach erstellte Modul test-app-7-4-0.
Von den 259 nicht-renovate-PRs, die seit dem 01.04.2026 zusammengeführt wurden, hatten 179 „tl-demo“ als nachgelagertes Modul eines geänderten Moduls; 82 betrafen ausschließlich die React-UI-Module, von denen „tl-demo“ nicht abhängt.
Lösung
PR-Builds aller TopLogic-Projekte laufen in gemeinsamen Jenkins-Pipelines, die im Repository „tl-ci“ (https://git.top-logic.com/TopLogic/tl-ci) verwaltet werden: Job „tl-ci-pr“ (pr/Jenkinsfile) für Pull-Anfragen, Job „tl-ci-deploy“ (deploy/Jenkinsfile) für die Release-Jobs, die derzeit „Build_Git“ aufrufen. Die Engine stellt die Test-Harness- und Build-Funktionen bereit, auf die sich die PR-Pipeline stützt; ein Projekt wechselt zu „tl-ci-pr“, sobald es eine Engine-Version mit dieser Änderung verwendet.
1. Aufgeteilte skriptgesteuerte Tests
- Das Test-Harness (AbstractBasicTestAll, test.com.top_logic.basic.util.ShardSelection) akzeptiert die Systemeigenschaft „TestAll.scripted“: „all“ (Standard, alle Tests), „none“ (alle Tests außer den skriptbasierten) oder „<i>/<n>“ (nur die skriptbasierten Tests von Shard i von n). „none“ und alle Shards zusammen führen genau die Tests von „all“ aus.
- Skriptbasierte Tests werden in Einheiten verteilt: die direkt in einem Skriptverzeichnis enthaltenen Skripte oder alle skriptbasierten Tests einer Testklasse. Eine Einheit wird niemals aufgeteilt, da ihre Skripte von ihrer Reihenfolge und vom gemeinsamen Anwendungszustand abhängen. Jedes Modul ordnet seine Einheiten nach absteigender Größe dem Shard mit der geringsten Auslastung zu; bei Gleichstand werden die Shards beginnend mit dem Index des Moduls in der Liste „TestAll.shardModules“ (die Module, die sich die Shards teilen) bevorzugt, sodass sich die Einheiten kleiner Module auf die Shards verteilen. Jede Shard-JVM führt dieselbe Zuordnung durch.
- Die Systemeigenschaft „TestAll.scratchDir“ (Standard: „tmp“, „test.com.top_logic.basic.ScratchDirectory“) legt das Verzeichnis für temporäre Testdateien fest. Bei einem vom Standard abweichenden Scratch-Verzeichnis erhält die zu testende Anwendung ihren Speicherpfad (tl_storage_path) und ein beschreibbares Webanwendungs-Overlay vor ihrem Ressourcenpfad innerhalb des temporären Verzeichnisses, sodass mehrere Testläufe im selben Modulverzeichnis weder die Quellen des Moduls (generierte Stylesheets und Skripte, exportierte Layouts und Modelle) beeinträchtigen noch verändern. IDEResources löst ein relatives„missing-keys-file“ bzw. „all-keys-file“ relativ zum Modulverzeichnis der Webanwendung auf oberster Ebene auf.
- „TestModelReporting.script.xml“ ist nicht mehr von Objekten abhängig, die durch Skripte aus anderen Verzeichnissen erstellt wurden.
- Befehl für einen Shard: mvn surefire:test -pl <modules> -DskipTests=false -DTestAll.scripted=<i>/<n> -DTestAll.shardModules=<modules> -DTestAll.scratchDir=tmp/shard-<i> -Dsurefire.reportNameSuffix=shard-<i>.
2. Paralleler Reactor-Build
- -Dtl.javadoc.aggregate=false aktiviert das Profil „javadoc-module-local“ (in tl-parent-build und tl-parent-engine): Das TLDoclet der Framework-Module schreibt in das Build-Verzeichnis des Moduls statt in den gemeinsamen Baum „tl-doc/javadoc“, und der JavaDoc-Index wird übersprungen. Das Doclet wird weiterhin in jedem Modul ausgeführt (Meldungsressourcen, Warnungen). Ohne diesen Schalter bleibt der Build unverändert (der Job „Create_JavaDoc“ stützt sich auf den gemeinsamen Baum).
- gwt.localWorkers (Standardwert 1) begrenzt die Anzahl der Worker bei jeder GWT-Kompilierung.
- Die Ziele „translate“, „check-resources“, „touch“ und „normalize“ des tl-maven-plugin sind als threadsicher gekennzeichnet.
- Ein vollständig paralleler Reactor-Build (mvn -T 1C clean install -Dtl.javadoc.aggregate=false, keine Tests) dauert auf einem Entwicklerrechner 2:39 Minuten statt ~8 Minuten im sequenziellen Ablauf.
- Im Reactor wird ein Modul erst gestartet, nachdem seine Abhängigkeiten ihre Tests ausgeführt haben. Die PR-Pipeline führt daher den Build ohne Tests durch und führt die Tests anschließend aus, sodass z. B. die 7 Minuten dauernden tl-core-Tests nicht mehr alle von tl-core abhängigen Module verzögern.
3. PR-Pipeline (tl-ci: pr/Jenkinsfile, Job tl-ci-pr)
- Phasen: Checkout (neuer Arbeitsbereich, tl-ci plus der Zweig BRANCH des Repositorys REPO), Auswahl (scripts/affected-modules.sh), Build (mvn -T <MAVEN_THREADS> clean install ohne Ausführung von Tests), Test (parallel: die Modultests unter Ausschluss der skriptgesteuerten Tests, SpotBugs: SpotBugs sowie SHARDS-Shards über die betroffenen Module mit skriptgesteuerten Tests), Quellcode prüfen (schlägt fehl, wenn der Build oder die Tests versionierte Quelldateien verändert haben), anschließend werden die Testergebnisse, SpotBugs-Probleme (ohne Git-Blame) und die Protokollregeln ausgewertet (Build-Warnungen → UNSTABLE, JVM-Abstürze bei Tests → FAILED).
- scripts/affected-modules.sh ermittelt anhand eines Git-Diffs gegen die Merge-Basis mit TARGET_BRANCH (Standard : master): MODE (vollständig, wenn sich das Stamm-POM des Reaktors oder .mvn/ geändert hat oder ein vollständiger Build erzwungen wird; „none“, wenn sich kein Reaktor-Modul geändert hat; andernfalls „partial“ ), die geänderten Module, die betroffenen Module (geänderte Module und deren Abhängigkeiten, einschließlich Module, die von einem geänderten übergeordneten POM erben), die betroffenen Module, deren Paketierung Tests ausführt, sowie diejenigen mit skriptgesteuerten Tests. Ein Reaktor in einem Unterverzeichnis (BUILD_MODULE) sowie Ein-Modul-Projekte werden unterstützt. Erfordert Maven >= 3.9.
- teilweise: (1) reine Kompilierung der geänderten Module und ihrer Abhängigkeiten, (2) „clean install -pl <changed> -amd“ ohne Ausführung von Tests, (3) Tests und „spotbugs:spotbugs“ über die Module aus (2). SpotBugs deckt dabei nur die betroffenen Module ab.
- Auswertung der letzten 30 zusammengeführten Engine-PRs: 17 benötigten 2–27 Module, 13 davon hatten überhaupt keine skriptgesteuerten Tests; einer benötigte einen vollständigen Build.
4. Deployment-Pipeline (tl-ci: deploy/Jenkinsfile, Job tl-ci-deploy)
- Übernimmt die Parameter von Build_Git (BUILD_NAME, REPO, BRANCH, BUILD_MODULE, GOAL, SKIP_TESTS, SKIP_JAVADOC, TAG, additionalOptions, ...), führt einen sequenziellen Maven-Aufruf von GOAL durch, setzt und pusht das TAG nach einem erfolgreichen Build und versendet das Ergebnis per E-Mail wie Build_Git. Keine Anforderungen an die Engine-Version. Im Gegensatz zu Build_Git führt ein Testfehler zum Abbruch des Builds, anstatt ihn instabil zu machen.
5. Standortkonfiguration
- Kein Repository enthält standortspezifische Einstellungen. Alles, was spezifisch für den Build-Server ist (Datenbank- und Mailserver der Tests, Anmeldedaten, Maven-Einstellungen), wird in der Jenkins-Anmeldeinformation „tl-ci-env“ (Typ „Secret file“, eine Shell-Umgebungsdatei) gespeichert. Die Pipelines lesen diese vor jedem Maven-Aufruf ein, ohne sie auszugeben; TopLogic löst seine ${env:...}-Aliase aus diesen Umgebungsvariablen auf, sodass kein Wert in der Befehlszeile, in den Build-Parametern oder im Build-Protokoll erscheint. Maven-Optionen werden in MAVEN_ARGS hinterlegt. Projektspezifische Einstellungen werden im Parameter additionalOptions hinterlegt.
- Die Build-Dauer hängt stark von der Auslastung des Build-Knotens ab: Ein vollständiger Engine-Build mit der ersten Version der Pipeline (bei der die Tests noch innerhalb des Reactor-Builds ausgeführt wurden) dauerte 67 Minuten, während auf demselben Knoten mit 8 CPUs fünf Build_Git-Builds liefen, die ihrerseits 1 Stunde 41 Minuten dauerten – 2 Std. 04 Min. statt 77–108 Min. dauerten; der Build ohne Tests dauerte 30 Min.
6. Testläufe mit vollständiger Datenbank (ein Worker pro Datenbank)
Ein PR-Build testet nur mit der Standarddatenbank (H2). Ein vollständiger Testlauf (ONLY_DEFAULT_DB deaktiviert, wie im Nightly-Build) führt jeden Multi-Datenbank-Test einmal pro Datenbank durch (MySQL, MSSQL, H2, Oracle, Oracle 12, Oracle 19, PostgreSQL). Alle Module nutzen pro Datenbank einen gemeinsamen Satz externer Schemata, daher dürfen die Tests einer Datenbank niemals gleichzeitig laufen, während dies bei verschiedenen Datenbanken möglich ist.
- Der Test-Harness (AbstractBasicTestAll, test.com.top_logic.basic.util.DBSelection) verwendet die Systemeigenschaft TestAll.db: „all“ (Standard, unverändertes Verhalten), „none“ (alle Tests außer denen, die an eine Worker-Datenbank gebunden sind) oder den Namen einer Datenbank (nur die daran gebundenen Tests: keine modulunabhängigen, ungebundenen oder skriptgesteuerten Tests). TestAll.dbWorkers listet die Datenbanken auf, die in eigenen Workern laufen (Standard: alle Datenbanken der Multi-Datenbank-Tests mit Ausnahme der Standarddatenbank). Ein anderer Wert als „all“ impliziert die vollständige Multi-Datenbank-Aufzählung (tl_test_onlyDefaultDB=false). „none“ und „one run per worker database“ führen zusammen jeden Test eines vollständigen Durchlaufs genau einmal aus; die Auswahl wird mit TestAll.scripted kombiniert.
- Ein Test ist an eine Datenbank gebunden, wenn er unterhalb eines DatabaseTestSetup oder KBSetup für diese liegt (Schnittstelle DBBoundTest); eine verschachtelte Bindung an eine andere Datenbank wird als Fehler gemeldet. Die Datenbanken der Multi-Datenbank-Tests werden einmal aufgeführt (DatabaseTestSetup.MULTI_DB). Das In-Place-Pruning des Testbaums (TestPruner) wird gemeinsam mit ShardSelection genutzt.
- Eine Testsuite, die nicht erstellt werden kann (z. B. aufgrund eines ungültigen Werts für „TestAll.scripted“ oder „TestAll.db“ ), führt nun zum Fehlschlagen des Testlaufs, anstatt einen leeren, erfolgreichen Lauf zu erzeugen.
- tl-ci pr/Jenkinsfile: Wenn ONLY_DEFAULT_DB deaktiviert ist, werden die Modultests und die Shards mit TestAll.db=none ausgeführt, und die Testphase erhält einen Zweig pro Datenbank des Parameters TEST_DBS (Standard: mysql, mssql, oracle, oracle12, oracle19,postgresql): „surefire:test“ von „test.TestAll“ wird nacheinander über die Module mit Tests ausgeführt, mit eigenem temporären Verzeichnis, eigenen Testports und eigenem Berichts-Suffix.
- Verifiziert mit tl-ci-pr #3 (vollständiger Build, alle Datenbanken, Zweig CWS/CWS_29707_db_workers von tl-ci): 73 Minuten statt 3 Stunden 44 Minuten – 4 Stunden 37 Minuten des nächtlichen Builds TL7 (#789). In tl-core wurden 4194 (keine) + 1207 (MySQL) + 1063 (MSSQL) + 1067 + 1066 + 1066 (Oracle) + 919 (PostgreSQL) = 10.582 Testfälle ausgewählt, d. h. genau die vollständige Testsuite. Dabei gefundene lastabhängige Tests: #29710, #29711.
Außerhalb des Umfangs
- Einmalige Ausführung der modulbezogenen Konformitätstests für den gesamten Arbeitsbereich: Nur die reinen Dateiscan-Prüfungen konnten verschoben werden, und unter -T liegen ihre Kosten größtenteils außerhalb des kritischen Pfads.
- Langsame Einzeltests: #29706.
- test.com.top_logic.kafka.demo speichert seine Anwendungs- und Kafka-Daten im festen Verzeichnis tmp/ (Speicherpfad aus der Variablen storage_path, Kafka-/ZooKeeper-Datenverzeichnisse in der Kafka-Konfiguration), nicht im Scratch-Verzeichnis. Da es nur eine skriptgesteuerte Einheit gibt, wird es nur von einem Shard ausgeführt.
- Aufteilung der skriptbasierten Einheit „scripted.TestDemo“ (76 geordnete Skripte, ~15 Min.), die die Dauer der Skript-Test-Shards nach unten begrenzt.
- Verlagerung des nächtlichen TL7-Builds selbst in die tl-ci-Pipelines: Neben den Tests versieht es den Build mit einem Tag, erstellt die aggregierte JavaDoc, stellt den Snapshot bereit und löst die abhängigen Builds und Demo-Bereitstellungen aus; außerdem verwendet er seine eigenen Datenbankschemata (tltrunktest*), während tl-ci-env die der CWS-Builds (cwstest*) enthält.