<?xml version="1.0" encoding="utf-8"?>
<page xmlns="http://projectmallard.org/1.0/" xmlns:its="http://www.w3.org/2005/11/its" type="topic" id="versioning" xml:lang="de">

  <info>
    <link type="guide" xref="index#maintainer-guidelines"/>

    <credit type="author copyright">
      <name>Philip Withnall</name>
      <email its:translate="no">philip.withnall@collabora.co.uk</email>
      <years>2015</years>
    </credit>

    <include xmlns="http://www.w3.org/2001/XInclude" href="cc-by-sa-3-0.xml"/>

    <desc>Versionierung und Veröffentlichung von Bibliotheken und Anwendungen</desc>
  
    <mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">
      <mal:name>Mario Blättermann</mal:name>
      <mal:email>mario.blaettermann@gmail.com</mal:email>
      <mal:years>2016, 2018</mal:years>
    </mal:credit>
  
    <mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">
      <mal:name>Christian Kirbach</mal:name>
      <mal:email>christian.kirbach@gmail.com</mal:email>
      <mal:years>2016, 2020</mal:years>
    </mal:credit>
  
    <mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">
      <mal:name>Stefan Melmuk</mal:name>
      <mal:email>stefan.melmuk@gmail.com</mal:email>
      <mal:years>2018</mal:years>
    </mal:credit>
  
    <mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">
      <mal:name>Tim Sabsch</mal:name>
      <mal:email>tim@sabsch.com</mal:email>
      <mal:years>2021</mal:years>
    </mal:credit>
  </info>

  <title>Versionierung</title>

  <synopsis>
    <title>Zusammenfassung</title>

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

    <list>
      <item><p>Bibliotheken und Anwendungen besitzen eine Paketversion der Form <em>major.minor.micro</em>. (<link xref="#package-versioning"/>)</p></item>
      <item><p>Bibliotheken besitzen zusätzlich eine libtool-Version der Form <em>current:revision:age</em>. (<link xref="#libtool-versioning"/>)</p></item>
      <item><p>Versionsnummern müssen für jede Veröffentlichung aktualisiert werden (mittels Release- und Post-Release-Erhöhung). (<link xref="#release-process"/>)</p></item>
      <item><p>Paketversionen sollten für Änderungen an bestehenden Funktionen oder neue Funktionsmerkmale erhöht werden. (<link xref="#package-versioning"/>)</p></item>
      <item><p>Libtool-Versionen sollten bei Änderungen an der API aktualisiert werden. (<link xref="#libtool-versioning"/>)</p></item>
      <item><p>Gerade/ungerade <em>Minor</em>-Paketversionen weisen auf stabile/instabile Veröffentlichungen hin. (<link xref="#stable-unstable-versions"/>)</p></item>
    </list>
  </synopsis>

  <section id="package-versioning">
    <title>Paket-Versionierung</title>

    <p>Sowohl Bibliotheken als auch Anwendungen haben eine Paketversion der Form <em>major.minor.micro</em>.</p>

    <p>Bei der Paketversionsnummer handelt es sich um die Nummer, die an <code>AC_INIT()</code> ü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 <link xref="parallel-installability">parallele Installierbarkeit</link> zum ermöglichen). Paketversionen werden unter Berücksichtigung der folgenden Regeln aktualisiert:</p>
    <steps>
      <item><p>Wenn Sie in einer Bibliothek <link xref="api-stability">inkompatible API-Änderungen</link> 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.</p></item>
      <item><p>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.</p></item>
      <item><p>Anderenfalls (wenn Ihre Veröffentlichung nur Fehlerbehebungen und aktualisierte Übersetzungen enthält), dann erhöhen Sie die Micro-Version.</p></item>
    </steps>

    <p>Beachten Sie, dass die Minor-Versionsnummer aktualisiert werden sollte, sobald eine API hinzugefügt wird.</p>
  </section>

  <section id="libtool-versioning">
    <title>Libtool-Versionierung</title>

    <p>Bibliotheken besitzen zwei Versionsnummern: eine libtool-Version, die die ABI-Abwärtskompatibilität verfolgt (siehe <link xref="api-stability"/>), 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.</p>

    <p>Eine gute Übersicht zur Versionierung von libtools und die Unterschiede zur Paketversionierung finden Sie in den <link href="https://autotools.io/libtool/version.html">Autotools Mythbuster</link>; eine andere ist im <link href="http://www.gnu.org/s/libtool/manual/html_node/Updating-version-info.html">libtool-Handbuch</link> zu finden.</p>

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

    <code>
# 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])</code>

    <p>Der folgende Code kann in <file>Makefile.am</file> verwendet werden, um die Versionsnummer an libtool zu übergeben:</p>
    <code>my_library_la_LDFLAGS = -version-info $(LT_VERSION)</code>
  </section>

  <section id="stable-unstable-versions">
    <title>Stabile und instabile Paketversionen</title>

    <p>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.</p>

    <p>Eine neue <em>stabile</em> Micro-Version (z.B. 3.20.0 → 3.20.1) fügt keine neuen Funktionsmerkmale hinzu, sondern enthält nur Fehlerbehebungen und aktualisierte Übersetzungen. <em>Instabile</em> 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.</p>

    <p>Die libtool-Version sollte nur bei stabilen Paketversionen aktualisiert werden.</p>
  </section>

  <section id="release-process">
    <title>Veröffentlichungsprozess</title>

    <p>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).</p>

    <p>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).</p>

    <p>Der Release-Prozess (basierend auf dem <link href="https://wiki.gnome.org/MaintainersCorner/Releasing">GNOME Release-Prozess</link>):</p>
    <steps>
      <item><p>Stellen Sie sicher, dass der Code aktuell ist: <cmd>git pull</cmd></p></item>

      <item><p>Stellen Sie sicher, dass es keine lokalen Änderungen gibt: <cmd>git status</cmd></p></item>
      <item><p>Falls es sich um ein Release einer stabilen Paketversion handelt, erhöhen Sie die libtool-Versionsnummer in <file>configure.ac</file> (falls vorhanden)</p></item>
      <item><p>Fügen Sie einen Eintrag zur <file>NEWS</file>-Datei hinzu</p></item>
      <item>
        <p>Führen Sie <cmd>./autogen.sh &amp;&amp; make &amp;&amp; make install &amp;&amp; make distcheck</cmd> aus und prüfen Sie, ob es erfolgreich durchläuft</p>
        <list>
          <item><p>Lösen Sie gegebenenfalls auftretende Probleme, committen Sie die Änderungen und wiederholen Sie ab Schritt 3</p></item>
        </list>
      </item>
      <item><p>Wenn <cmd>make distcheck</cmd> mit »[archive] is ready for distribution« beendet, führen Sie <cmd>git commit -a -m "Release version x.y.z"</cmd> aus (wobei »x.y.z« die Versionsnummer des Pakets ist)</p></item>
      <item>
        <p>Führen Sie <cmd>git push</cmd> aus</p>
        <list>
          <item><p>Falls dies fehlschlägt, weil in der Zwischenzeit andere Commits hochgeladen wurden, führen Sie <cmd>git pull</cmd> aus, mergen Sie die Änderungen und laden diese per <cmd>git push</cmd> hoch. Hierbei handelt es sich um eine Ausnahme von den GNOME-Richtlinien für einen linearen Git-Verlauf (<link xref="version-control#use-of-git"/>). Wenn Sie einen linearen Verlauf bevorzugen, müssen Sie wieder bei Schritt 1 anfangen.</p></item>
        </list>
      </item>
      <item><p>Markieren Sie die Veröffentlichung: <cmd>git tag -s x.y.z</cmd> (wobei »x.y.z« die Versionsnummer des Pakets ist)</p></item>
      <item><p>Führen Sie <cmd>git push origin x.y.z</cmd> aus (wobei »x.y.z« die Versionsnummer des Pakets ist)</p></item>
    </steps>

    <p>Damit haben Sie den Release beendet und die nachfolgende Versionserhöhung kann erfolgen:</p>
    <steps>
      <item><p>Erhöhen Sie die Paketversionsnummer in <file>configure.ac</file></p></item>
      <item><p>Führen Sie <cmd>git commit -a -m "Post-release version increment"</cmd> aus</p></item>
      <item><p>Führen Sie <cmd>git push</cmd> aus</p></item>
    </steps>

    <p>Das von <cmd>make distcheck</cmd> erzeugte Paketarchiv kann nun zu download.gnome.org hochgeladen oder auf andere Weise verteilt werden.</p>
  </section>
</page>
