version-number-comparison algorithm dox confusion in Debian Packaging Manual 3.1.1.0
I quote Debian Packaging Manual 3.1.1.0, chapter 5 (i.e.,
http://www.debian.org/doc/packaging-manuals/packaging.html/ch-versions.html):
upstream-version
...
The upstream-version may contain only alphanumerics and the
characters . + - : (full stop, plus, hyphen, colon) and should
start with a digit. If there is no debian-revision then
hyphens are not allowed; if there is no epoch then colons are
not allowed.
debian-revision
...
It is in the same format as the upstream-version and dpkg compares
it in the same way.
...
The debian-revision may contain only alphanumerics and the
characters + and . (plus and full stop).
The upstream-version and debian-revision parts are compared by dpkg
using the same algorithm:
The 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.
There are a number of problems with this documentation:
1) The second quoted sentence under `debian-revision' contradicts the
first: they are *not* the same format, since the upstream-version
may contain - and : under certain circumstances, whereas
debian-revision may not. There is considerable intervening text
between the two quotes sentences, making this point unclear.
2) "one of which may be empty" in the final quoted paragraph is
unclear. I understand that you refer to the case where one
version string ended while the other continues. But consider the
fact that most of the time, *both* parts are going to be empty on
the first invocation of this step, since most (if not all)
upstream-versions start with a digit.
3) The meaning of "should start with a digit" is probably unclear.
If the truth is that an upstream-revision *must* start with a
digit, then the first step of the algorithm is obviated.
(`dpkg --compare-versions' accepts an initial non-digit.)
If the truth is that the manual recommends an initial digit,
then the nature or rationale of the recommendation remains
unclear. (Perhaps this latter is made clear elsewhere in the
Manual -- see Background below.) You may also wish to consider
whether this recommendation applies to debian-revision, in light
of the claim that is has the 'same format' as upstream-version.
Background:
I am a not a developer, but a user. I turned to this section of the
Packaging manual to try to find out how to choose a version number
such that I could supersede the currently-available version of a
package with a locally-created version, but which would most likely be
superseded by the next official version. (The combination of bugs
#49324 and #50223 is annoying me.) I thought the section of the
manual was unclear, so I am sending this critique.
Reply to: