<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>Versioning and releasing libraries and applications</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</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</mal:years>

    </mal:credit>

  </info>

  <title>Versionierung</title>

  <synopsis>

    <title>Zusammenfassung</title>

      Module versioning differs for libraries and applications: libraries need a

      libtool version specified in addition to their package version.

      Applications just have a package version.

    <list>

      <item>

        Libraries and applications have a package version of the form

        major.minor.micro. (<link xref="#package-versioning"/>)

      
</item>

      <item>

        Libraries additionally have a libtool version of the form

        current:revision:age. (<link xref="#libtool-versioning"/>)

      
</item>

      <item>

        Version numbers should be updated for each release (using release and

        post-release increments). (<link xref="#release-process"/>)

      
</item>

      <item>

        Package versions should be incremented for feature changes or additions.

        (<link xref="#package-versioning"/>)

      
</item>

      <item>

        Libtool versions should be updated for API changes or additions.

        (<link xref="#libtool-versioning"/>)

      
</item>

      <item>

        Even/odd minor package versions can be used respectively for

        stable/unstable releases. (<link xref="#stable-unstable-versions"/>)

      
</item>

    </list>

  </synopsis>

  <section id="package-versioning">

    <title>Paket-Versionierung</title>

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

      The package version number is that passed to

      AC_INIT(), and the one which is typically known as the

      project’s version number. For example, the Debian package for a library

      will use the library’s package version (though may also include the major

      version number in the package name to allow for

      <link xref="parallel-installability">parallel installability</link>).

      Package versions are updated by the following rules:

    <steps>

      <item>

        If breaking <link xref="api-stability">API compatibility</link> in a

        library, or making a large change to an application which affects

        everything (such as a UI redesign), increment major and set minor and

        micro to 0.

      
</item>

      <item>

        Otherwise, if changing or adding a feature, or adding any API,

        increment minor and set micro to 0.

      
</item>

      <item>

        Otherwise (if making a release containing only bug fixes and

        translation updates), increment micro.

      
</item>

    </steps>

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

  </section>

  <section id="libtool-versioning">

    <title>Libtool-Versionierung</title>

      Libraries have two version numbers: a libtool version which tracks ABI

      backwards compatibility (see <link xref="api-stability"/>), and a package

      version which tracks feature

      changes. These are normally incremented in synchronization, but should be

      kept separate because ABI backwards compatibility is not necessarily

      related to feature changes or bug fixes. Furthermore, the two version

      numbers have different semantics, and cannot be automatically generated

      from each other.

      A good overview of libtool versioning, and the differences from package

      versioning, is given in the

      <link href="https://autotools.io/libtool/version.html">Autotools

      Mythbuster</link>; another is in the

      <link href="http://www.gnu.org/s/libtool/manual/html_node/Updating-version-info.html">libtool

      manual</link>.

      To update the libtool version, follow the algorithm given in the comments

      below. This is a typical <file>configure.ac</file> snippet for setting up

      libtool versioning:

# 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 <file>Makefile.am</file> verwendet werden, um die Versionsnummer an libtool zu übergeben:

    my_library_la_LDFLAGS = -version-info $(LT_VERSION)

  </section>

  <section id="stable-unstable-versions">

    <title>Stabile und instabile Paketversionen</title>

      Most GNOME modules follow a convention for stable and unstable releases.

      The minor version is even for stable releases and is odd for unstable

      releases.  For example, the 3.20.* versions are stable, but the 3.19.*

      versions are unstable.  The 3.19.* versions can be seen as alpha and beta

      releases of the 3.20 version.

      A new micro stable version (e.g. 3.20.0 → 3.20.1) doesn’t add

      new features, only translation updates and bug fixes.  On the other hand,

      unstable micro releases (e.g. 3.19.1 → 3.19.2) can add API, or

      change or remove API which was added in a previous micro release in that

      minor series.

    
Die libtool-Version sollte nur die stabile Paketversionen aktualisiert werden.

  </section>

  <section id="release-process">

    <title>Veröffentlichungsprozess</title>

      The standard process for making a release of a module increments the

      libtool version (if the module is a library) at the time of release, then

      increments the package version number immediately afterwards (this is

      called a post-release increment).

      Updating the libtool versions at the time of release means that they are

      only incremented once for all ABI changes in a release. The use of

      post-release increment for package versions means the package version

      number is not outdated (still equal to the previous release) during

      the development cycle.

    
Der Release-Prozess (basierend auf dem <link href="https://wiki.gnome.org/MaintainersCorner/Releasing">GNOME Release-Prozess</link>):

    <steps>

      <item>
Stellen Sie sicher, dass der Code aktuell ist: <cmd>git pull</cmd>
</item>

      <item>
Stellen Sie sicher, dass es keine lokalen Änderungen gibt: <cmd>git status</cmd>
</item>

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

      <item>
Fügen Sie einen Eintrag zur <file>NEWS</file>-Datei hinzu
</item>

      <item>

          Run

          <cmd>./autogen.sh && make && make install && make distcheck</cmd>

          and ensure it succeeds

        <list>

          <item>

            Fix any issues which come up, commit those changes, and restart at

            step 3

          
</item>

        </list>

      </item>

      <item>

        If <cmd>make distcheck</cmd> finishes with “[archive] is ready for

        distribution”, run <cmd>git commit -a -m "Release version x.y.z"</cmd>

        (where ‘x.y.z’ is the package version number)

      
</item>

      <item>

        
Führen Sie <cmd>git push</cmd> aus

        <list>

          <item>

            If that fails due to other commits having been pushed in the

            meantime, run <cmd>git pull</cmd> to merge your commit on the

            branch followed by a second <cmd>git push</cmd>.  This is an

            exception to the GNOME guideline to have a linear Git history

            (<link xref="version-control#use-of-git"/>).  If you prefer to have

            a linear history, you need to restart at step 1.

          
</item>

        </list>

      </item>

      <item>

        Tag the release: <cmd>git tag -s x.y.z</cmd> (where ‘x.y.z’ is the

        package version number)

      
</item>

      <item>

        Run <cmd>git push origin x.y.z</cmd> (where ‘x.y.z’ is the package

        version number)

      
</item>

    </steps>

      The release is now complete, and the post-release version increment can be

      done:

    <steps>

      <item>
Erhöhen Sie die Paketversionsnummer in <file>configure.ac</file>
</item>

      <item>
Führen Sie <cmd>git commit -a -m "Post-release version increment"</cmd> aus
</item>

      <item>
Führen Sie <cmd>git push</cmd> aus
</item>

    </steps>

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

  </section>

</page>