Erstellen eines Releases

Vorbereitung

Um ein Release zu erstellen, müssen einige Vorbereitungen getroffen werden. Diese Vorbereitungen sind notwendig, um sicherzustellen, dass das Release erfolgreich erstellt werden kann und alle notwendigen Informationen vorhanden sind.

Vorbereiten des Maven Passwortspeichers

Damit Maven die Releases in das zentrale Repository hochladen kann, muss es über die Zugangsdaten für das Repository verfügen. Diese Zugangsdaten sollten nicht im Klartext in der Datei settings.xml gespeichert werden. Um die Zugangsdaten sicher zu speichern, sollte eine Master-Passphrase erstellt werden, die dann für die Verschlüsselung der Zugangsdaten verwendet wird. Dazu wird das Kommando mvn --encrypt-master-password ausgeführt. Das Ergebnis dieses Kommandos wird in der Datei ~/.m2/settings-security.xml gespeichert. Diese Datei sollte nicht im Quellcode-Repository abgelegt werden.

1
2
3

<settingsSecurity>
  <master>{jSMOWnoPFgsHVpMvz5VrIt5kRbzGpI8u+9EF1iFQyJQ=}</master>
</settingsSecurity>

Die Passwörter können nun über das Kommando mvn --encrypt-password verschlüsselt werden. Siehe dazu auch die Maven-Dokumentation.

Erstellen eines GPG Schlüssels

Releases von MyCoRe werden signiert. Dazu wird ein GPG-Schlüssel benötigt.

Dieser Schlüssel sollte auf dem lokalen Rechner erstellt werden, auf dem auch die Releases erstellt werden.

Die Erstellung des Schlüssels erfolgt mit dem Kommando gpg --gen-key. Nach der Eingabe des Kommandos wird man durch den Prozess der Erstellung des Schlüssels geführt. Dabei muss man seinen Namen, eine E-Mail-Adresse und ein Passwort für den Schlüssel angeben. Nach der Erstellung des Schlüssels kann man diesen mit dem Kommando gpg --list-keys anzeigen lassen.

(Optional) Der Schlüssel kann jetzt auf einen Keyserver hochgeladen werden, damit er von anderen Personen gefunden werden kann. Dazu wird das Kommando gpg --send-keys <key-id> verwendet. Ein Keyserver kann z.B. https://keys.openpgp.org sein. Nach dem Hochladen des Schlüssels wird eine E-Mail versendet, in der die Verknüpfung des Schlüssels mit der E-Mail-Adresse bestätigt werden muss.

Damit Maven den Schlüssel für die Signierung von Releases verwenden kann, muss die Datei ~/.m2/settings.xml um den folgenden Abschnitt ergänzt werden:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

<servers>
  <server>
    <id>E4C544BE49C40BD4DB2CF54B3B0CDD6464CBA588</id>
    <passphrase>{verschlüsseltes_password}</passphrase>
  </server>
</servers>

<profiles>
  <profile>
    <id>gpg_key_activation</id>
    <activation>
<activeByDefault>true</activeByDefault>
    </activation>
    <properties>
<gpg.keyname>E4C544BE49C40BD4DB2CF54B3B0CDD6464CBA588</gpg.keyname>
    </properties>
  </profile>
</profiles>

Der gpg.keyname ist die ID des GPG-Schlüssels, der für die Signierung der Releases verwendet werden soll. Diese ID muss jeweils in das Property gpg.keyname und als id in den <server>-Abschnitt eingetragen werden.

Die Passphrase wird durch das Kommando mvn --encrypt-password verschlüsselt und in den Abschnitt <passphrase> eingetragen. Diese Passphrase wird dann von Maven verwendet, um den GPG-Schlüssel zu entsperren.

Durch das Profil gpg_key_activation wird sichergestellt, dass der GPG-Schlüssel immer aktiviert ist, wenn Maven ausgeführt wird.

Diese Änderung kann mit dem Kommando mvn clean install getestet werden. Wenn alles korrekt eingerichtet ist, sollte das Kommando ohne Fehler durchlaufen und folgende Ausgabe erzeugen:

[INFO] --- gpg:3.2.7:sign (sign-artifacts) @ mycore-bom ---
[INFO] Signer 'gpg' is signing 1 file with key E4C544BE49C40BD4DB2CF54B3B0CDD6464CBA588

Sonatype Zugangsdaten

Um die Releases in das zentrale Repository hochzuladen, werden Zugangsdaten für Sonatype benötigt. Für die Erstellung dieser Zugangsdaten wird ein Account auf der Seite https://central.sonatype.com/ benötigt. Nach der Erstellung des Accounts muss dieser Account von einem MyCoRe-Entwickler freigeschaltet werden. Anfragen zur Freischaltung können an die MyCoRe-Entwicklerliste gerichtet werden.

Nach der Freischaltung des Accounts müssen die Zugangsdaten über die Oberfläche von Sonatype erstellt werden. Dazu wird die Account-Seite aufgerufen und dort unter dem Punkt "Generate user Token" ein Token erstellt. Dieses Token wird dann mit dem Kommando mvn --encrypt-password verschlüsselt und in der Datei ~/.m2/settings.xml im Abschnitt <servers> unter dem Punkt <password> eingetragen. Der Abschnitt sollte dann wie folgt aussehen:

1
2
3
4
5

<server>
  <id>central</id>
  <username>your.username</username>
  <password>{your.encrypted.password}</password>
</server>

Die Zugangsdaten werden dann von Maven verwendet, um die Releases in das zentrale Repository hochzuladen.

Um die Zugangsdaten zu testen, kann das Kommando mvn clean deploy in einem kleinen Projekt ausgeführt werden. Sollte alles korrekt eingerichtet sein, sollte das Kommando ohne Fehler durchlaufen.

Vorbereitung Git

Bei der Erstellung eines Releases wird der Quellcode von Maven mit einem Git-Tag markiert und es werden Commit-Messages erstellt, die den Stand des Quellcodes zum Zeitpunkt des Releases dokumentieren. Um dies zu ermöglichen, muss der lokale Git-Client so konfiguriert werden, dass er die grundsätzlichen Informationen für die Commits kennt. Dazu werden die folgenden Kommandos ausgeführt:

git config --global user.name "Max Mustermann"
git config --global user.email "max.mustermann@mycore.de"

Diese Informationen werden dann in den Commits verwendet, die bei der Erstellung des Releases erstellt werden. In der Regel sollten diese Informationen bereits gesetzt sein, da sie auch für die normalen Commits verwendet werden.

Es sollte sichergestellt werden, dass die Rechte vorhanden sind, um auf das zentrale Git-Repository zuzugreifen, besonders, weil die Branches für die LTS-Releases normalerweise schreibgeschützt sind.

Da beim Release auch Commits mit Änderungen an der pom.xml erstellt werden, sollten im Git vorher alle Branches, die regelmäßig aktualisiert werden, auf den aktuellen Stand gebracht werden.

Release

Damit ein Release erstellt werden kann, müssen folgende Bedingungen erfüllt sein:

• Es dürfen keine lokalen Änderungen im Quellcode vorhanden sein.
• Die Tests müssen erfolgreich durchlaufen.
• In der Datei pom.xml dürfen keine SNAPSHOT-Versionen mehr enthalten sein.
• Die oben genannten Schritte zur Vorbereitung des Maven Passwortspeichers, GPG-Schlüssels und Sonatype Zugangsdaten müssen durchgeführt worden sein.

Die Version des Projekts bleibt eine SNAPSHOT-Version und wird im Release-Prozess von Maven auf eine Release-Version geändert. Wenn in der Datei pom.xml noch SNAPSHOT-Versionen enthalten sind, dann muss die Version auf eine Release-Version geändert werden, dabei assistiert später ein Maven-Kommando. Wenn es sich um ein MyCoRe-Projekt handelt, dann muss davon zuerst ein Release erstellt werden, falls es noch nicht existiert.

Der Release-Prozess ist in mehrere Abschnitte unterteilt: im ersten Schritt mvn release:prepare werden die oben genannten Bedingungen geprüft. Falls es noch SNAPSHOT-Versionen gibt, dann wird der Benutzer gefragt, ob die SNAPSHOT-Versionen auf eine Release-Version geändert werden sollen. Dann wird der Nutzer nach einer Versionsnummer gefragt, die für das Release verwendet werden soll und anschließend wird diese Version in der Datei pom.xml eingetragen. Die SCM-Angaben in der Datei pom.xml werden aktualisiert, damit auf den Tag des Releases verwiesen wird. Diese Änderungen werden dann in einem Commit festgehalten. Anschließend wird ein Tag im Git-Repository erstellt, der den Stand des Quellcodes zum Zeitpunkt des Releases dokumentiert.

Abfrage der Versionsangaben:

[INFO] 5/17 prepare:map-release-versions
What is the release version for "MyCoRe Parent POM"? (mycore-parent) 57:
[INFO] 6/17 prepare:input-variables
What is the SCM release tag or label for "MyCoRe Parent POM"? (mycore-parent) v57:
[INFO] 7/17 prepare:map-development-versions
What is the new development version for "MyCoRe Parent POM"? (mycore-parent) 58-SNAPSHOT:

Nach dem erfolgreichen Abschluss des mvn release:prepare Kommandos sollte der Quellcode in das zentrale Quellcode-Repository hochgeladen werden. Dazu wird das Kommando git push ausgeführt, um die Änderungen im Quellcode in das zentrale Quellcode-Repository zu übertragen. Anschließend wird das Kommando git push --tags ausgeführt, um den Tag des Releases in das zentrale Quellcode-Repository zu übertragen.

Nachdem der Quellcode in das zentrale Quellcode-Repository hochgeladen wurde, kann der zweite Schritt des Release-Prozesses durchgeführt werden. Dazu wird das Kommando mvn release:perform ausgeführt. In diesem Schritt wird das Release erstellt und in das zentrale Maven-Repository hochgeladen. Wenn das Kommando erfolgreich durchläuft, dann ist das Release fertig und es dauert einige Minuten, bis das Release im zentralen Maven-Repository verfügbar ist.

Wenn es sich um ein Projekt handelt, welches in einem LTS-Branch liegt, dann sollte noch ein entsprechender Merge in die neueren Branches erfolgen. Dabei kommt es zwangsweise zu Konflikten, da die Versionsnummern in den pom.xml von beiden Branches geändert wurden. Da das Release aber die einzige Änderung ist, die seit dem letzten Merge in den Branch vorgenommen wurde, kann der Merge einfach durchgeführt werden, indem die POMs der neueren Branches übernommen werden. Dazu wird genauso vorgegangen wie bei einem normalen Merge, außer dass der Parameter -X ours in das git merge Kommando eingefügt wird, um die POMs der neueren Branches zu übernehmen.