docs: releases version comparison is not explained

[kparal]

In <releases/>, each release has a version and these versions are then compared to figure out which one is the last one. However, the documentation doesn't speak about the comparison algorithm at all. This allows people to assume different behavior and make needless mistakes. It's also very hard to find out the intricacies of the implemented algorithm, for example the difference between 2.0-rc1 and 2.0~rc1.

For example, one such discussion is here:
Beep6581/RawTherapee#5303
and another is here:
flathub/com.corsixth.corsixth#2

Can you please document the version comparison algorithm? At least in broad strokes, i.e. whether it is literal or numeric, what are the special characters, and how to deal with the most common use cases (like the beta/rc versions, etc).

Thank you.

[ximion]

With libappstream being used almost everywhere now, it may actually make sense to formally document the version comparison algorithm...
To answer the question immediately though, the version comparison algorithm is nearly identical to the one of Debian (and has been tested against RPM versions too), as described here: https://manpages.debian.org/testing/dpkg-dev/deb-version.5.en.html#Sorting_algorithm
It's implemented in AppStream here: https://github.com/ximion/appstream/blob/master/src/as-vercmp.c

This version comparison algorithm is used by GNOME Software, KDE Discover, Elementary AppCenter & Co via libappstream, as well as by appstreamcli, but not by appstream-util which belongs to the appstream-glib project, which makes this situation a bit confusing at the moment.

As for how to denote alpha/beta/rc versions: Letters will be sorted earlier than numbers, so if a letter is replaced by a number, this will work. A much better and safer version is to use the tilde sign though, so the alpha version to a 1.0 release would be 1.0~alpha1.

EDIT: The tests may also be a useful reference, until I find the time to amend the specification: https://github.com/ximion/appstream/blob/master/tests/test-basics.c#L545