Difference between revisions of "Guidelines/Versioning"

From Apertis
Jump to: navigation, search
(Create page)
 
(Update for IRC discussion on 2016-02-02)
Line 7: Line 7:
 
* Libraries have a libtool version of the form ''current:revision:age''. ([[#Library versioning]])
 
* Libraries have a libtool version of the form ''current:revision:age''. ([[#Library versioning]])
 
* Libraries have a package version of the form ''major.minor.micro''. ([[#Library versioning]])
 
* Libraries have a package version of the form ''major.minor.micro''. ([[#Library versioning]])
* Applications have a package version of the form ''major.minor''. ([[#Application versioning]])
+
* Applications have a package version of the form ''major.minor.micro''. ([[#Application versioning]])
 
* Version numbers should be updated for each release (using pre- and post-release increments). ([[#Release process]])
 
* Version numbers should be updated for each release (using pre- and post-release increments). ([[#Release process]])
 
* Package versions should be incremented for feature changes or additions. ([[#Library versioning]])
 
* Package versions should be incremented for feature changes or additions. ([[#Library versioning]])
Line 44: Line 44:
 
== Application versioning ==
 
== Application versioning ==
  
Application versioning is simpler than library versioning: applications only have a package number, and it follows the scheme ‘major.minor’.
+
Application versioning is the same as library versioning: applications only have a package number, and it follows the scheme ‘major.minor.micro’.
  
The application package number is updated similarly to the library package number, except the micro version is omitted:
+
The application package number is updated similarly to the library package number:
# If making a large change to the application which affects everything (such as a UI redesign), increment major and set minor to 0.
+
# If making a large change to the application which affects everything (such as a UI redesign), increment major and set minor and micro to 0.
# Otherwise, increment minor.
+
# Otherwise, if adding a large feature or other big change, increment minor and set micro to 0.
 +
# Otherwise (e.g. if making a release containing only bug fixes or translation updates), increment micro.
  
 
== Release process ==
 
== Release process ==
Line 75: Line 76:
  
 
The package archive generated by <code>make distcheck</code> can now be uploaded to a website or distributed in other ways.
 
The package archive generated by <code>make distcheck</code> can now be uploaded to a website or distributed in other ways.
 +
 +
If the <code>AX_IS_RELEASE</code> macro is used (which is [[Guidelines/Tooling|recommended]]), versions with an odd micro version number are considered to be unstable; versions with an even micro version number are stable.
  
 
== External links ==
 
== External links ==

Revision as of 10:20, 18 February 2016

Versioning

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.

Summary

Library versioning

Libraries have two version numbers: a libtool version which tracks ABI backwards compatibility, and a package version which tracks feature changes. These are normally incremented in synchronisation, 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 Autotools Mythbuster.

To update the libtool version, follow the algorithm given in the comments below. This is a typical configure.ac 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])

The following snippet can be used in a Makefile.am to pass that version info to libtool:

my_library_la_LDFLAGS = -version-info $(LT_VERSION)

The package version number for a library 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. Package versions have the form ‘major.minor.micro’, and are updated by the following rules:

  1. If breaking API compatibility, increment major and set minor and micro to 0.
  2. Otherwise, if adding a large feature or other big change, or adding any API, increment minor and set micro to 0.
  3. Otherwise (e.g. if making a release containing only bug fixes or translation updates), increment micro.

Note that the minor version number should be updated if any API is added.

Application versioning

Application versioning is the same as library versioning: applications only have a package number, and it follows the scheme ‘major.minor.micro’.

The application package number is updated similarly to the library package number:

  1. If making a large change to the application which affects everything (such as a UI redesign), increment major and set minor and micro to 0.
  2. Otherwise, if adding a large feature or other big change, increment minor and set micro to 0.
  3. Otherwise (e.g. if making a release containing only bug fixes or translation updates), increment micro.

Release process

The standard process for making a release of a module increments the libtool version (if the module is a library) immediately before release, does the release, then increments the package version number immediately afterwards. This is called pre-release increment for libtool versioning and post-release increment for package versioning.

The use of pre-release increment for libtool versions 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 (i.e. still equal to the previous release) during the development cycle.

The release process (based on the GNOME release process):

  1. Make sure code is up to date: git pull
  2. Make sure you have no local changes: git status
  3. Increment the libtool version number in configure.ac (if it exists)
  4. Add an entry to the NEWS file
  5. Run ./autogen.sh && make && make install && make distcheck and ensure it succeeds
    • Fix any issues which come up, commit those changes, and restart at step 3
  6. If make distcheck finishes with “[archive] is ready for distribution”, run git commit -a -m "Release version x.y.z" (where ‘x.y.z’ is the package version number)
  7. Run git push
    • If that fails due to other commits having been pushed in the meantime, restart at step 1
  8. Tag the release: git tag -s x.y.z (where ‘x.y.z’ is the package version number)
  9. Run git push origin x.y.z (where ‘x.y.z’ is the package version number)

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

  1. Increment the package version number in configure.ac
  2. Run git commit -a -m "Post-release version increment"
  3. Run git push

The package archive generated by make distcheck can now be uploaded to a website or distributed in other ways.

If the AX_IS_RELEASE macro is used (which is recommended), versions with an odd micro version number are considered to be unstable; versions with an even micro version number are stable.

External links