Debian Version

Basics

The Debian environment supports a version scheme which is standardized (at least in the Debian environment.) The following is a description of the version supported by wpkg which is based on the Debian version scheme.1

A version is composed of three parts as follow:

• epoch — a decimal number followed by a colon
• version — the package version composed of numbers and letters and a few others characters; it is also called the upstream version as it generally uses the version of the orginal project
• revision — most often a decimal number after a dash, although letters and a few other characters are also allowed

Example: 3:1.4.7b-12a, 0:1.0.0-3, 1:2:3:4-pre

Epoch

By default the epoch is zero. The canonicalization removes "0:" if it is defined in a version string unless the version includes colons.

The epoch is rarely necessary in a Debian package version. It is used if the source of a package uses a version scheme that is not compatible with the Debian scheme and a newer version would otherwise appear older in Debian.

For example, some packages use versions, in sequence, such as: 1.1, 1.11, 1.12, 1.13, 1.14..., 1.19, 1.2, 1.21, etc. In Debian, version 1.2 will look as being smaller than 1.11 to 1.19. In that case, the epoch can be used to properly place 1.2 after all 1.1x versions.

IMPORTANT NOTE

The Epoch uses uses a colon character (:) which is not valid in a filename on a MS-Windows system. Although we support the semi-colon (;) as a one to one replacement of that character, this does not work well if you attempt to work with Unices and MS-Windows in the same environment using network drives because one system will attempt to save files with the colon and the other with semi-colon rendering the filenames incompatible. At this point, the workaround will be for you to make use of avoiding epochs in versions.

Version (upstream version)

The version can be composed of decimal numbers and letters and a few other characters which can be mixed. It must start with a digit, including zero (0).

The following table lists all the possible characters in the order they are sorted, except for digits that form numbers and are sorted as decimal numbers (i.e. leading zeroes are ignored and 0x or h do not transform numbers to hexadecimal.)

So 3a5 or 1b91 are acceptable. For comparison purposes though, these are considered separate parts. There are a few examples:

The empty cells represent the empty string. Note that after the last part of a version, everything is considered to be an empty string. Also ".0" at the end of a version is viewed as an empty string as well. The period is the only character that gets ignored at the end of a version (this is not debian compatible: 1.0. is not equal to 1 or even 1.0 in Debian.)

Note that the version first part is always a string. In case of a version (opposed to a release), that first string is always empty because the version must start with a digit.

There is no default version number. If not specified, then it is considered invalid.

All letters in versions are all compared in lowercase which means a and A are viewed as the same, which is not Debian compatible. The order of the special characters is otherwise shown in the table. The special characters are viewed as larger than all letters, except the tilde which is viewed as smaller than anything including the empty string. Because parts are generated as a sequence of string, number, string, number, ... always starting with a string, you never end up comparing a string with a number.

When comparing two versions, if one has more parts but all the parts up to that point were equal, then the side with more parts is considered larger unless the first part after the common parts starts with a tilde. For example, the following three versions are in order:

• 1.48~svn8096
• 1.48
• 1.48a

However, zero parts are ignored when comparing, so the following three versions are all equal even though some have additional parts:

• 1.48
• 1.48.
• 1.48.0.0

Note 1: a version can include colons only if an epoch is defined. You may prepend 0: for that purpose.

Note 2: a version can include dashes only if a release is defined. You may append -0 for that purpose.

Note 3: the tilde is supported because different source control systems make use of that character in their auto-versioning scheme and that way such a version can directly be imported to the packager.

Release (Debian release)

A release is expected to be a decimal number. The default is zero as in "-0".

However, the fact is that a release accept all the characters a version accepts except the dash (-) and colon (:) characters and contrary to a version, it can start with any chacracter.

On canonicalization, a "-0" is added only if the version includes a dash.

The release version is used when the source code of a package does not change, but the package is tweaked and a higher version number is required (i.e. 1.3-1 is smaller than 1.3-2 and thus you can upgrade from one to the other even though the content of the package is very similar, maybe a PDF document was added to the newer version.)

Although the epoch and release are optional if specified they cannot be empty. So the following versions are invalid:

:1.3
1.3-

The release clearly starts with the last dash found in the version, no matter what appears after the dash. So a version as follow is not valid because release numbers cannot include a colon character:

3:1.2.3-7:3

If your version includes a dash, then you must add "-0" at the end to render it valid. The version we saw can be made valid like this:

3:1.2.3-7:3-0

Empty Versions

Debian understands the empty string as a valid version. The wpkg --compare-versions also understands the empty string as an acceptable version. However, the library version API returns an error if it is passed an empty string as a version number. So the version in a package cannot be empty. Also at this point the different version comparator abilities (--validate-fields, control file expressions) do not accept the empty string as a valid version. Instead, you may use a single zero (0).

Note that the wpkg --compare-versions understands the empty string to support the different comparators that the dpkg --compare-versions command supports. It is otherwise not advised to support the empty string in your own code.

Debian Compatibility

Debian considers the period as a full character that cannot just be optimized and thus 1.0.0 is not equal to 1.0 nor just 1 or even 1.0. or 1., all of those are distinct in Debian. It does seem logical, though, to do such an optimization. Our process considers a period (.) at the end of a version as representing nothing, so we optimize it and 1 or 1. are the exact same thing. Similarly, we optimize a zero (0) because that's the default value of a release version. So in effect any .0 gets optimized out. Where we are Debian compatible is with numbers with additional leading zeros so 1.0 and 1.00 are equal in our environment and in the Debian environment.

This should very rarely be a problem since you pretty much never had a package version 1, then 1., then 1.0. In most cases it will start as 1.0 and then grow as 1.1, 1.2, etc.

The best way to know whether you are creating a larger version is to compare your current and new verions with the --compare-versions command as in:

wpkg --verbose --compare-versions 1.0.3 lt 1.0.4

This command prints "true" in stdout.

Fortuitous Coincidence

Note that the sorting of strings is done against the characters without any knowledge of what the characters means (in case they were to formed a word.) This means a word is not interpreted in any way or form as such. It is simply taken as a plain old string.

This being said, the release parameter could be used with the following words successfully as they will ultimately be sorted as expected:

This works nicely, although when you create the full version, you will need to either bump the version or use a release that appears after "rc" (anything larger than "rc" starting from "rd", maybe "-stable"?)

Canonicalization

The wpkg tool has a command line option called --canonicalize-version which can be used to canonicalize a version. The output is the shortest possible version.

Example:

wpkg --canonicalize-version 0:1.0.0-0

outputs:

1

Note that the internal comparison algorithm automatically does a canonicalization. This allows wpkg to see 0:1.0.0-0 as being equal to 1.

Example:

wpkg --compare-versions 0:1.0.0-0 eq 1.0

Grammar

A Debian version defined in a very simplified lexx/yacc like grammar:

   debian_version: epoch version release

   epoch: /* empty */
        | [0-9]+ ':'

   version: [0-9] [-+:~.0-9a-zA-Z]*

   release: /* empty */
          | '-' [+~.0-9a-zA-Z]+

Note that this grammar would accept a version such as 3.5:7 which is not compatible with a true Debian version because a colon can appear in a version only if an epoch was defined.

Compliance / Source

This documentation follows the Debian Version definition with only a few minor differences.

• 1. The wpkg version scheme is very close to the Debian scheme, although it has a few differences such as forcing all letters to lowercase and ignoring periods and zeroes at the end of versions.
• 2. Dashes are possible only if you declare a revision. You may append "-0" if your version includes a dash but no revision.
• 3. Colons are possible only if you declare an epoch. You may prepend "0:" if the colon is required.