Philip Withnall
philip.withnall@collabora.co.uk 2015

This work is licensed under a Creative Commons Attribution-Share Alike 3.0 United States License.

Als besondere Ausnahme gewähren die Inhaber des Urheberrechts die Erlaubnis, den Beispiel-Code in diesem Dokument ohne Einschränkungen unter den Bedingungen Ihrer Wahl zu kopieren, zu verändern und weiterzugeben.

Versionierung und Veröffentlichung von Bibliotheken und Anwendungen
Mario Blättermann
mario.blaettermann@gmail.com 2016, 2018
Christian Kirbach
christian.kirbach@gmail.com 2016, 2020
Stefan Melmuk
stefan.melmuk@gmail.com 2018
Tim Sabsch
tim@sabsch.com 2021

# Versionierung

#

        Zusammenfassung

        Die Versionierung von Modulen unterscheidet sich zwischen Bibliotheken und Anwendungen: Anwendungen benötigen eine Paketversion, Bibliotheken zusätzlich dazu eine libtool-Version.

          Bibliotheken und Anwendungen besitzen eine Paketversion der Form major.minor.micro. ()
          Bibliotheken besitzen zusätzlich eine libtool-Version der Form current:revision:age. ()
          Versionsnummern müssen für jede Veröffentlichung aktualisiert werden (mittels Release- und Post-Release-Erhöhung). ()
          Paketversionen sollten für Änderungen an bestehenden Funktionen oder neue Funktionsmerkmale erhöht werden. ()
          Libtool-Versionen sollten bei Änderungen an der API aktualisiert werden. ()
          Gerade/ungerade Minor-Paketversionen weisen auf stabile/instabile Veröffentlichungen hin. ()

# Paket-Versionierung

Sowohl Bibliotheken als auch Anwendungen haben eine Paketversion der Form major.minor.micro.

Bei der Paketversionsnummer handelt es sich um die Nummer, die an `AC_INIT()` übergeben wird und typischerweise als die Projektversionsnummer bekannt ist. Das Debian-Paket einer Bibliothek verwendet beispielsweise die Paketversion der Bibliothek (sie könnte allerdings auch die Major-Versionsnummer im Paketnamen verwenden, um parallele Installierbarkeit zum ermöglichen). Paketversionen werden unter Berücksichtigung der folgenden Regeln aktualisiert:

Wenn Sie in einer Bibliothek inkompatible API-Änderungen vornehmen oder Ihre Anwendung weitreichende Änderungen erhält (z.B. eine komplett neue Benutzeroberfläche), dann erhöhen Sie die Major-Version und setzen Minor und Micro auf 0.

Anderenfalls, wenn Sie Funktionsmerkmale ändern oder hinzufügen, oder eine neue API hinzufügen, dann erhöhen Sie die Minor-Version und setzen Micro auf 0.

Anderenfalls (wenn Ihre Veröffentlichung nur Fehlerbehebungen und aktualisierte Übersetzungen enthält), dann erhöhen Sie die Micro-Version.

Beachten Sie, dass die Minor-Versionsnummer aktualisiert werden sollte, sobald eine API hinzugefügt wird.

# Libtool-Versionierung

Bibliotheken besitzen zwei Versionsnummern: eine libtool-Version, die die ABI-Abwärtskompatibilität verfolgt (siehe ), und eine Paketversion, die Funktionsänderungen verfolgt. Für gewöhnlich werden beide Versionen gemeinsam erhöht, sollten aber separat gespeichert werden, da die ABI-Abwärtskompatibilität nicht zwangsläufig mit Funktionsänderungen oder Fehlerbehebungen zusammenhängt. Außerdem haben die beiden Versionsnummern unterschiedliche inhaltliche Bedeutungen und können nicht automatisch aus der jeweils anderen generiert werden.

Eine gute Übersicht zur Versionierung von libtools und die Unterschiede zur Paketversionierung finden Sie in den Autotools Mythbuster; eine andere ist im libtool-Handbuch zu finden.

Um die libtool-Version zu aktualisieren, befolgen Sie den nachfolgenden Algorithmus. Dies ist ein typischer Ausschnitt aus einer configure.ac-Datei, um die libtool-Versionierung festzulegen:

# Before making a release, the LT_VERSION string should be modified. The # string is of the form c:r:a. Follow these instructions sequentially: # 1. If the library source code has changed at all since the last update, then # increment revision (‘c:r:a’ becomes ‘c:r+1:a’). # 2. If any interfaces have been added, removed, or changed since the last # update, increment current, and set revision to 0. # 3. If any interfaces have been added since the last public release, then # increment age. # 4. If any interfaces have been removed or changed since the last public # release, then set age to 0. AC_SUBST([LT_VERSION],[0:0:0])

Der folgende Code kann in Makefile.am verwendet werden, um die Versionsnummer an libtool zu übergeben:

my_library_la_LDFLAGS = -version-info $(LT_VERSION)

# Stabile und instabile Paketversionen

Die meisten GNOME-Module folgen einer Konvention für stabile und instabile Veröffentlichungen. Die Minor-Version ist bei stabilen Veröffentlichungen gerade und bei instabilen Veröffentlichungen ungerade. Ein Beispiel: die 3.20.*-Versionen sind stabil, die 3.19.*-Versionen hingegen nicht. Die 3.19.*-Versionen können als Alpha- und Beta-Veröffentlichungen der 3.20-Version betrachtet werden.

Eine neue stabile Micro-Version (z.B. 3.20.0 → 3.20.1) fügt keine neuen Funktionsmerkmale hinzu, sondern enthält nur Fehlerbehebungen und aktualisierte Übersetzungen. Instabile Micro-Versionen (z.B. 3.19.1 → 3.19.2) dürfen andererseits eine neue API hinzufügen oder bestehende APIs ändern oder entfernen, die in einer vorhergehenden Micro-Version der gleichen Minor-Serie hinzugefügt wurden.

Die libtool-Version sollte nur bei stabilen Paketversionen aktualisiert werden.

# Veröffentlichungsprozess

Der Standardprozess zur Erstellung einer Veröffentlichung eines Modus beinhaltet die Erhöhung der libtool-Version (wenn es sich um eine Bibliothek handelt) zum Veröffentlichungszeitpunkt, und erhöht unmittelbar anschließend die Paketversionsnummer (dies wird »post-release increment« genannt).

Die libtool-Version zum Zeitpunkt der Veröffentlichung zu aktualisieren, bedeutet, dass alle ABI-Änderungen in der Veröffentlichung durch nur eine Erhöhung abgedeckt sind. Die Paketversion unmittelbar nach Veröffentlichung zu aktualisieren bedeutet, dass die Paketversionsnummer im Entwicklungszyklus nicht veraltet ist (sie ist immer noch gleich mit der vorgehenden Veröffentlichung).

Der Release-Prozess (basierend auf dem GNOME Release-Prozess):

Stellen Sie sicher, dass der Code aktuell ist: git pull

Stellen Sie sicher, dass es keine lokalen Änderungen gibt: git status

Falls es sich um ein Release einer stabilen Paketversion handelt, erhöhen Sie die libtool-Versionsnummer in configure.ac (falls vorhanden)

Fügen Sie einen Eintrag zur NEWS-Datei hinzu

Führen Sie ./autogen.sh && make && make install && make distcheck aus und prüfen Sie, ob es erfolgreich durchläuft

Lösen Sie gegebenenfalls auftretende Probleme, committen Sie die Änderungen und wiederholen Sie ab Schritt 3

Wenn make distcheck mit »[archive] is ready for distribution« beendet, führen Sie git commit -a -m "Release version x.y.z" aus (wobei »x.y.z« die Versionsnummer des Pakets ist)

Führen Sie git push aus

Falls dies fehlschlägt, weil in der Zwischenzeit andere Commits hochgeladen wurden, führen Sie git pull aus, mergen Sie die Änderungen und laden diese per git push hoch. Hierbei handelt es sich um eine Ausnahme von den GNOME-Richtlinien für einen linearen Git-Verlauf (). Wenn Sie einen linearen Verlauf bevorzugen, müssen Sie wieder bei Schritt 1 anfangen.

Markieren Sie die Veröffentlichung: git tag -s x.y.z (wobei »x.y.z« die Versionsnummer des Pakets ist)

Führen Sie git push origin x.y.z aus (wobei »x.y.z« die Versionsnummer des Pakets ist)

Damit haben Sie den Release beendet und die nachfolgende Versionserhöhung kann erfolgen:

Erhöhen Sie die Paketversionsnummer in configure.ac

Führen Sie git commit -a -m "Post-release version increment" aus

Führen Sie git push aus

Das von make distcheck erzeugte Paketarchiv kann nun zu download.gnome.org hochgeladen oder auf andere Weise verteilt werden.