#68 : Jenkins-Build mit -Drevision-Übergabe und robuster Shade-JAR-Archivierung

- Neues Jenkinsfile mit pipeline-Struktur (Checkout, Version bestimmen, Maven Build, Archive JAR, Berichte, Artefakt ablegen, Aufräumen) - Maven-Build übergibt -Drevision=MAJOR.MINOR.BUILD_NUMBER - Archive-Stage: Bash explizit via #!/usr/bin/env bash + set -euo pipefail, mapfile-Prüfung bricht bei 0 oder mehr als 1 Shade-JAR mit Fehlermeldung ab - MSI-Build als bewusst manuell dokumentiert (Kommentar im Jenkinsfile) - MAJOR/MINOR via Jenkins-Parameter, EFFECTIVE_MAJOR/MINOR-Stub für State-Datei - docs/betrieb.md: CI-Hinweis zum manuellen MSI-Build ergänzt Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
#67 : Konsistente Versionierung via Maven CI-friendly revision
2026-04-30 10:43:48 +02:00 · 2026-04-30 10:36:55 +02:00
14 changed files with 293 additions and 14 deletions
@@ -3,6 +3,8 @@
 # =========================================================
 **/target/
 dependency-reduced-pom.xml
+# Generierte Flat-POM-Dateien des flatten-maven-plugin (CI-friendly Versioning)
+**/.flattened-pom.xml

 # =========================================================
 # Eclipse / IDE
@@ -0,0 +1,151 @@
+// Jenkins-Pipeline für den PDF KI Renamer
+// Läuft auf einem Linux-Container (Synology NAS).
+// Der MSI-Build ist Windows-only (jpackage + WiX Toolset 3.x). Jenkins läuft im
+// Linux-Container auf Synology NAS und kann kein MSI erzeugen. Der MSI-Build
+// wird bewusst manuell auf der Windows-Entwicklungsmaschine ausgeführt:
+//   .\mvnw.cmd clean package -P release -pl pdf-umbenenner-packaging --also-make -DskipTests
+
+pipeline {
+    agent any
+
+    // MAJOR und MINOR werden manuell als Jenkins-Parameter gepflegt.
+    // BUILD_NUMBER wird automatisch durch Jenkins vergeben.
+    // Die resultierende Versionsnummer lautet: MAJOR.MINOR.BUILD_NUMBER
+    parameters {
+        string(
+            name: 'MAJOR',
+            defaultValue: '3',
+            description: 'Hauptversionsnummer (manuell pflegen)'
+        )
+        string(
+            name: 'MINOR',
+            defaultValue: '0',
+            description: 'Nebenversionsnummer (manuell pflegen)'
+        )
+    }
+
+    environment {
+        // Effektive Versionsteile – übernommen aus Parametern oder State-Datei.
+        // Hinweis: Wenn MAJOR/MINOR aus einer persistierten State-Datei gelesen
+        // werden sollen (z. B. /builds/version.state), muss die Logik unten in
+        // der Stage 'Version bestimmen' entsprechend ergänzt werden.
+        // Im Minimalbetrieb werden die Parameter direkt übernommen.
+        EFFECTIVE_MAJOR = "${params.MAJOR}"
+        EFFECTIVE_MINOR = "${params.MINOR}"
+    }
+
+    stages {
+
+        stage('Checkout') {
+            steps {
+                checkout scm
+            }
+        }
+
+        // Optionaler Stub: MAJOR/MINOR aus persistierter State-Datei laden.
+        // Wenn das bestehende Jenkins-Setup die Versionsnummern in einer
+        // State-Datei unter /builds/version.state persistiert, kann diese
+        // Stage die Umgebungsvariablen EFFECTIVE_MAJOR und EFFECTIVE_MINOR
+        // vor dem Build überschreiben. Ansonsten gelten die Parameter-Werte.
+        stage('Version bestimmen') {
+            steps {
+                script {
+                    // Platzhalter: hier bei Bedarf State-Datei einlesen,
+                    // z. B.:
+                    //   def state = readFile('/builds/version.state').trim()
+                    //   env.EFFECTIVE_MAJOR = state.split('\\.')[0]
+                    //   env.EFFECTIVE_MINOR = state.split('\\.')[1]
+                    //
+                    // Im Minimalbetrieb werden die Parameter-Werte verwendet:
+                    echo "Buildversion: ${env.EFFECTIVE_MAJOR}.${env.EFFECTIVE_MINOR}.${env.BUILD_NUMBER}"
+                }
+            }
+        }
+
+        stage('Maven Build') {
+            steps {
+                // -Drevision übergibt die vollständige Versionsnummer an Maven.
+                // Das flatten-maven-plugin im Parent-POM löst ${revision} in
+                // allen installierten POMs auf, sodass kein unaufgelöstes
+                // ${revision} in ~/.m2 verbleibt.
+                sh "mvn clean verify -Drevision=${env.EFFECTIVE_MAJOR}.${env.EFFECTIVE_MINOR}.${env.BUILD_NUMBER}"
+            }
+        }
+
+        stage('Archive JAR') {
+            steps {
+                // Bash wird explizit erzwungen (#!/usr/bin/env bash, set -euo pipefail),
+                // weil Jenkins-Agenten standardmäßig sh (dash) verwenden, das kein
+                // mapfile kennt. mapfile zählt exakt die gefundenen Shade-JARs und
+                // bricht den Build ab, wenn nicht genau eines vorhanden ist.
+                sh '''#!/usr/bin/env bash
+set -euo pipefail
+
+mapfile -t JARS < <(find pdf-umbenenner-bootstrap/target \
+    -maxdepth 1 -name "pdf-umbenenner-bootstrap-*.jar" \
+    ! -name "*-sources.jar" ! -name "*-javadoc.jar")
+
+test "${#JARS[@]}" -eq 1 \
+    || { echo "FEHLER: Erwartet genau 1 Shade-JAR, gefunden: ${#JARS[@]}"; exit 1; }
+
+JAR_NAME="pdf-ki-renamer-${EFFECTIVE_MAJOR}.${EFFECTIVE_MINOR}.${BUILD_NUMBER}.jar"
+cp "${JARS[0]}" "$JAR_NAME"
+echo "Shade-JAR archiviert als: $JAR_NAME"
+'''
+                archiveArtifacts artifacts: 'pdf-ki-renamer-*.jar', fingerprint: true
+            }
+        }
+
+        stage('Berichte') {
+            steps {
+                // JUnit-Testergebnisse einlesen
+                junit testResults: '**/target/surefire-reports/*.xml', allowEmptyResults: true
+
+                // JaCoCo-Coverage (falls im Build erzeugt)
+                // jacoco execPattern: '**/target/jacoco.exec'
+
+                // PIT-Mutationstest-Bericht (falls im Build erzeugt)
+                // publishHTML(target: [reportDir: 'target/pit-reports', ...])
+            }
+        }
+
+        stage('Artefakt ablegen') {
+            steps {
+                // JAR-Kopie in zentrales Build-Verzeichnis ablegen.
+                // Pfad /builds/ muss auf dem Jenkins-Agent gemountet sein.
+                sh '''#!/usr/bin/env bash
+set -euo pipefail
+
+BUILD_DIR="/builds/${EFFECTIVE_MAJOR}.${EFFECTIVE_MINOR}.${BUILD_NUMBER}"
+mkdir -p "$BUILD_DIR"
+cp pdf-ki-renamer-*.jar "$BUILD_DIR/"
+echo "Artefakt abgelegt unter: $BUILD_DIR"
+'''
+            }
+        }
+
+        stage('Aufräumen') {
+            steps {
+                // Lokale JAR-Kopie im Workspace entfernen (Artefakt ist archiviert)
+                sh '''#!/usr/bin/env bash
+set -euo pipefail
+rm -f pdf-ki-renamer-*.jar
+echo "Aufräumen abgeschlossen."
+'''
+            }
+        }
+    }
+
+    post {
+        success {
+            echo "Build ${env.EFFECTIVE_MAJOR}.${env.EFFECTIVE_MINOR}.${env.BUILD_NUMBER} erfolgreich abgeschlossen."
+        }
+        failure {
+            echo "Build ${env.EFFECTIVE_MAJOR}.${env.EFFECTIVE_MINOR}.${env.BUILD_NUMBER} fehlgeschlagen."
+        }
+        always {
+            // Workspace nach Abschluss bereinigen
+            cleanWs()
+        }
+    }
+}
@@ -451,6 +451,10 @@ benötigt keine separate Java-Installation auf dem Zielsystem. Das Shade-JAR ble
 primäre Distributionsartefakt; der MSI ist eine zusätzliche Option für Systeme ohne
 Java-Installation und für den Standard-Installationspfad nach `C:\Program Files\`.

+> **Hinweis zur CI-Umgebung:** Der MSI-Build ist Windows-only (`jpackage` + WiX Toolset 3.x).
+> Jenkins läuft im Linux-Container auf dem Synology NAS und kann kein MSI erzeugen.
+> Der MSI-Build wird bewusst manuell auf der Windows-Entwicklungsmaschine ausgeführt.
+
 **Voraussetzungen für den Installer-Build (nur auf der Entwicklungsmaschine):**
 - Windows x64
 - JDK 21 im PATH
@@ -4,7 +4,7 @@
  <parent>
    <groupId>de.gecheckt</groupId>
    <artifactId>pdf-umbenenner-parent</artifactId>
-    <version>0.0.1-SNAPSHOT</version>
+    <version>${revision}</version>
  </parent>
  <artifactId>pdf-umbenenner-adapter-in-cli</artifactId>
  <packaging>jar</packaging>
@@ -5,7 +5,7 @@
  <parent>
    <groupId>de.gecheckt</groupId>
    <artifactId>pdf-umbenenner-parent</artifactId>
-    <version>0.0.1-SNAPSHOT</version>
+    <version>${revision}</version>
  </parent>
  <artifactId>pdf-umbenenner-adapter-in-gui</artifactId>
  <packaging>jar</packaging>
@@ -4,7 +4,7 @@
  <parent>
    <groupId>de.gecheckt</groupId>
    <artifactId>pdf-umbenenner-parent</artifactId>
-    <version>0.0.1-SNAPSHOT</version>
+    <version>${revision}</version>
  </parent>
  <artifactId>pdf-umbenenner-adapter-out</artifactId>
  <packaging>jar</packaging>
@@ -6,7 +6,7 @@
 	<parent>
 		<groupId>de.gecheckt</groupId>
 		<artifactId>pdf-umbenenner-parent</artifactId>
-		<version>0.0.1-SNAPSHOT</version>
+		<version>${revision}</version>
 	</parent>
 	<artifactId>pdf-umbenenner-application</artifactId>
 	<packaging>jar</packaging>
@@ -4,7 +4,7 @@
  <parent>
    <groupId>de.gecheckt</groupId>
    <artifactId>pdf-umbenenner-parent</artifactId>
-    <version>0.0.1-SNAPSHOT</version>
+    <version>${revision}</version>
  </parent>
  <artifactId>pdf-umbenenner-bootstrap</artifactId>
  <packaging>jar</packaging>
@@ -105,6 +105,11 @@
              <transformers>
                <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
                  <mainClass>de.gecheckt.pdf.umbenenner.bootstrap.PdfUmbenennerApplication</mainClass>
+                  <manifestEntries>
+                    <!-- Versionseintrag wird zur Laufzeit via getImplementationVersion() ausgelesen -->
+                    <Implementation-Version>${revision}</Implementation-Version>
+                    <Implementation-Title>PDF KI Renamer</Implementation-Title>
+                  </manifestEntries>
                </transformer>
                <!-- Merge META-INF/services entries from all JARs instead of overwriting -->
                <transformer implementation="org.apache.maven.plugins.shade.resource.ServicesResourceTransformer"/>
@@ -0,0 +1,45 @@
+package de.gecheckt.pdf.umbenenner.bootstrap;
+
+/**
+ * Liest die Anwendungsversion aus dem MANIFEST.MF des ausführbaren Fat-JARs.
+ * <p>
+ * Im gepackten Betrieb wird der Eintrag {@code Implementation-Version} aus dem
+ * JAR-Manifest gelesen, der beim Build durch das Shade-Plugin befüllt wird.
+ * Im IDE-Betrieb und in Testumgebungen ohne gepacktes JAR steht kein Manifest
+ * zur Verfügung; in diesem Fall wird der Fallback {@code "dev"} zurückgegeben.
+ * <p>
+ * Diese Klasse ist eine reine Hilfsklasse ohne Zustand; alle Methoden sind statisch.
+ * Die Verdrahtung mit der GUI-Statuszeile erfolgt in einer späteren Ausbaustufe.
+ */
+public final class ApplicationVersionProvider {
+
+    /** Fallback-Version, wenn kein Manifest-Eintrag verfügbar ist. */
+    private static final String FALLBACK_VERSION = "dev";
+
+    /** Utility-Klasse – kein öffentlicher Konstruktor. */
+    private ApplicationVersionProvider() {
+        // nicht instanziierbar
+    }
+
+    /**
+     * Gibt die Anwendungsversion zurück.
+     * <p>
+     * Die Version wird aus dem {@code Implementation-Version}-Eintrag des Pakets
+     * {@code de.gecheckt.pdf.umbenenner.bootstrap} gelesen. Dieser Eintrag wird
+     * beim Build durch das Shade-Plugin mit dem Wert der Property {@code ${revision}}
+     * befüllt.
+     * <p>
+     * Ist der Eintrag nicht vorhanden (IDE-Start, Tests, ungepackter Betrieb),
+     * wird der Wert {@code "dev"} zurückgegeben.
+     *
+     * @return die aufgelöste Versionsnummer, niemals {@code null}
+     */
+    public static String resolveVersion() {
+        String version = ApplicationVersionProvider.class.getPackage().getImplementationVersion();
+        if (version == null) {
+            // Fallback für IDE-Start und ungepackten Betrieb
+            return FALLBACK_VERSION;
+        }
+        return version;
+    }
+}
@@ -0,0 +1,36 @@
+package de.gecheckt.pdf.umbenenner.bootstrap;
+
+import org.junit.jupiter.api.Test;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+/**
+ * Unit-Tests für {@link ApplicationVersionProvider}.
+ * <p>
+ * Im Testlauf ist kein gepacktes JAR mit Manifest vorhanden; der Test prüft deshalb
+ * ausschließlich das Fallback-Verhalten und stellt sicher, dass die Methode niemals
+ * {@code null} zurückgibt.
+ */
+class ApplicationVersionProviderTest {
+
+    /**
+     * Im Testlauf (kein Fat-JAR, kein Manifest-Eintrag) muss der Fallback-Wert
+     * {@code "dev"} zurückgegeben werden.
+     */
+    @Test
+    void resolveVersion_ohneGepacktesJar_gibtDevZurueck() {
+        // Wenn kein MANIFEST.MF mit Implementation-Version vorhanden ist (IDE / Test),
+        // wird der Fallback-Wert geliefert.
+        String version = ApplicationVersionProvider.resolveVersion();
+        assertThat(version).isEqualTo("dev");
+    }
+
+    /**
+     * Das Ergebnis von {@link ApplicationVersionProvider#resolveVersion()} darf
+     * niemals {@code null} sein – weder im IDE-Betrieb noch im gepackten Betrieb.
+     */
+    @Test
+    void resolveVersion_gibtNiemalsNull() {
+        assertThat(ApplicationVersionProvider.resolveVersion()).isNotNull();
+    }
+}
@@ -5,7 +5,7 @@
 	<parent>
 		<groupId>de.gecheckt</groupId>
 		<artifactId>pdf-umbenenner-parent</artifactId>
-		<version>0.0.1-SNAPSHOT</version>
+		<version>${revision}</version>
 	</parent>
 	<artifactId>pdf-umbenenner-coverage</artifactId>
 	<packaging>pom</packaging>
@@ -4,7 +4,7 @@
  <parent>
    <groupId>de.gecheckt</groupId>
    <artifactId>pdf-umbenenner-parent</artifactId>
-    <version>0.0.1-SNAPSHOT</version>
+    <version>${revision}</version>
  </parent>
  <artifactId>pdf-umbenenner-domain</artifactId>
  <packaging>jar</packaging>
@@ -6,7 +6,7 @@
 	<parent>
 		<groupId>de.gecheckt</groupId>
 		<artifactId>pdf-umbenenner-parent</artifactId>
-		<version>0.0.1-SNAPSHOT</version>
+		<version>${revision}</version>
 	</parent>
 	<artifactId>pdf-umbenenner-packaging</artifactId>
 	<packaging>pom</packaging>
@@ -21,12 +21,11 @@

 	<properties>
 		<!--
-			Anwendungsversion des erzeugten Windows-Installers. Bewusst entkoppelt von
-			${project.version}, damit die ausgelieferte Installer-Version unabhaengig
-			vom Maven-Snapshot-Zyklus gepflegt werden kann. Wird ausschliesslich
-			vom Profil "release" in der jpackage-Konfiguration ausgewertet.
+			Anwendungsversion des erzeugten Windows-Installers. Wird direkt aus ${revision}
+			abgeleitet, damit Installer-Version und JAR-Version konsistent sind.
+			Beim Release-Build: -Drevision=MAJOR.MINOR.BUILD_NUMBER
 		-->
-		<app.version>2.5.0</app.version>
+		<app.version>${revision}</app.version>
 	</properties>

 	<dependencies>
@@ -5,7 +5,7 @@
 	<modelVersion>4.0.0</modelVersion>
 	<groupId>de.gecheckt</groupId>
 	<artifactId>pdf-umbenenner-parent</artifactId>
-	<version>0.0.1-SNAPSHOT</version>
+	<version>${revision}</version>
 	<packaging>pom</packaging>
 	<modules>
 		<module>pdf-umbenenner-domain</module>
@@ -18,6 +18,10 @@
 		<module>pdf-umbenenner-packaging</module>
 	</modules>
 	<properties>
+		<!-- Zentrale Versionsproperty für Maven CI-friendly Versioning.
+			 Kann per -Drevision=MAJOR.MINOR.BUILD überschrieben werden (z. B. im CI). -->
+		<revision>0.0.1-SNAPSHOT</revision>
+
 		<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
 		<maven.compiler.release>21</maven.compiler.release>

@@ -230,6 +234,39 @@
 		</pluginManagement>

 		<plugins>
+			<!--
+				flatten-maven-plugin: löst ${revision} in installierten POMs auf, sodass
+				keine unaufgelösten Property-Referenzen in ~/.m2 erscheinen.
+				flattenMode=resolveCiFriendliesOnly beschränkt die Auflösung auf CI-friendly
+				Properties (${revision}, ${sha1}, ${changelist}) und lässt alle anderen
+				Properties unverändert.
+			-->
+			<plugin>
+				<groupId>org.codehaus.mojo</groupId>
+				<artifactId>flatten-maven-plugin</artifactId>
+				<version>1.6.0</version>
+				<configuration>
+					<updatePomFile>true</updatePomFile>
+					<flattenMode>resolveCiFriendliesOnly</flattenMode>
+				</configuration>
+				<executions>
+					<execution>
+						<id>flatten</id>
+						<phase>process-resources</phase>
+						<goals>
+							<goal>flatten</goal>
+						</goals>
+					</execution>
+					<execution>
+						<id>flatten.clean</id>
+						<phase>clean</phase>
+						<goals>
+							<goal>clean</goal>
+						</goals>
+					</execution>
+				</executions>
+			</plugin>
+
 			<plugin>
 				<groupId>org.jacoco</groupId>
 				<artifactId>jacoco-maven-plugin</artifactId>