4 Miscellaneous #

The AppStream specification requires the presence of version numbers in various locations, and AppStream-using clients will occasionally need to compare version numbers in order to determine the latest version. This document describes how version comparisons should be performed.

AppStream's version comparison algorithm is identical to the one used by the Fedora and Debian Linux distributions (after RPM's algorithm was extended to handle the tilde character like Debian). The algorithm is described for Debian here (https://manpages.debian.org/unstable/dpkg-dev/deb-version.5.en.html#Sorting_algorithm), the description is also reproduced below:

The version strings are compared from left to right.

First the initial part of each string consisting entirely of non-digit characters is determined. These two parts (one of which may be empty) are compared lexically. If a difference is found it is returned. The lexical comparison is a comparison of ASCII values modified so that all the letters sort earlier than all the non-letters and so that a tilde sorts before anything, even the end of a part. For example, the following parts are in sorted order: ~~, ~~a, ~, the empty part, a.

Then the initial part of the remainder of each string which consists entirely of digit characters is determined. The numerical values of these two parts are compared, and any difference found is returned as the result of the comparison. For these purposes an empty string (which can only occur at the end of one or both version strings being compared) counts as zero.

These two steps (comparing and removing initial non-digit strings and initial digit strings) are repeated until a difference is found or both strings are exhausted.

For meaningful version numbers, consider following semantic versioning (https://semver.org/).

A version number should always start with a number. Do not start version numbers with a letter or make them consist entirely of letters, e.g. BETA is not a version number.

If you want to denote a prerelease, consider appending the prerelease identifier string after a tidle. For example use 1.0~alpha1 for an alpha release of the upcoming 1.0 release. The alpha release will then considered lower than the final release.

Avoid using any epochs (colons) in your upstream version numbers. Versions like 1:2.4 will cause problems with downstreams.

You can read AppStream's code for version comparisons here (https://github.com/ximion/appstream/blob/master/src/as-vercmp.c).

If you want to quickly test version comparisons for your software and arbitrary versions, consider using the vercmp subcommand of the appstreamcli utility.

Examples:

$ appstreamcli vercmp 1.0 2.0
1.0 << 2.0
$ appstreamcli vercmp 2.0 2.0~a1
2.0 >> 2.0~a1
$ appstreamcli vercmp 2.4 lt 2.1
false: 2.4 >> 2.1
$ appstreamcli vercmp 1.2.4 gt 1.2.3
true: 1.2.4 >> 1.2.3