211 TODO

   211 The version number of a package.  The format is::

   212 

   213   [<epoch>`:']<upstream_version>[`-'<debian_revision>]

   214 

   215 The three components here are:

   216 

   217 ``epoch``

   218      This is a single (generally small) unsigned integer.  It may be

   219      omitted, in which case zero is assumed.  If it is omitted then

   220      the <upstream_version> may not contain any colons.

   221 

   222      It is provided to allow mistakes in the version numbers of older

   223      versions of a package, and also a package's previous version

   224      numbering schemes, to be left behind.

   225 

   226 ``upstream_version``

   227      This is the main part of the version number.  It is usually the

   228      version number of the original ("upstream") package from which

   229      the ``.deb`` file has been made, if this is applicable.  Usually

   230      this will be in the same format as that specified by the upstream

   231      author(s); however, it may need to be reformatted to fit into the

   232      package management system's format and comparison scheme.

   233 

   234      The comparison behavior of the package management system with

   235      respect to the <upstream_version> is described below.  The

   236      <upstream_version> portion of the version number is mandatory.

   237 

   238      The <upstream_version> may contain only alphanumerics[1] and the characters

   239      ``.`` ``+`` ``-`` ``:`` ``~`` (full stop, plus, hyphen, colon, tilde) and

   240      should start with a digit. If there is no <debian_revision> then hyphens

   241      are not allowed; if there is no <epoch> then colons are not allowed.

   242 

   243   <debian_revision>

   244      This part of the version number specifies the version of the

   245      Debian package based on the upstream version.  It may contain

   246      only alphanumerics and the characters ``+`` ``.`` ``~`` (plus, full

   247      stop, tilde) and is compared in the same way as the

   248      <upstream_version> is.

   249 

   250      It is optional; if it isn't present then the <upstream_version>

   251      may not contain a hyphen.  This format represents the case where

   252      a piece of software was written specifically to be turned into a

   253      Debian package, and so there is only one "debianisation" of it

   254      and therefore no revision indication is required.

   255 

   256      It is conventional to restart the <debian_revision> at ``1`` each

   257      time the <upstream_version> is increased.

   258 

   259      The package management system will break the version number apart

   260      at the last hyphen in the string (if there is one) to determine

   261      the <upstream_version> and <debian_revision>.  The absence of a

   262      <debian_revision> compares earlier than the presence of one (but

   263      note that the <debian_revision> is the least significant part of

   264      the version number).

   265 

   266 The <upstream_version> and <debian_revision> parts are compared by the

   267 package management system using the same algorithm:

   268 

   269 The strings are compared from left to right.

   270 

   271 First the initial part of each string consisting entirely of non-digit

   272 characters is determined.  These two parts (one of which may be empty)

   273 are compared lexically.  If a difference is found it is returned.  The

   274 lexical comparison is a comparison of ASCII values modified so that

   275 all the letters sort earlier than all the non-letters and so that a

   276 tilde sorts before anything, even the end of a part.  For example, the

   277 following parts are in sorted order from earliest to latest: ``~~``,

   278 ``~~a``, ``~``, the empty part, ``a``.[2]

   279 

   280 Then the initial part of the remainder of each string which consists

   281 entirely of digit characters is determined.  The numerical values of

   282 these two parts are compared, and any difference found is returned as

   283 the result of the comparison.  For these purposes an empty string

   284 (which can only occur at the end of one or both version strings being

   285 compared) counts as zero.

   286 

   287 These two steps (comparing and removing initial non-digit strings and

   288 initial digit strings) are repeated until a difference is found or

   289 both strings are exhausted.

   290 

   291 Note that the purpose of epochs is to allow us to leave behind

   292 mistakes in version numbering, and to cope with situations where the

   293 version numbering scheme changes.  It is _not_ intended to cope with

   294 version numbers containing strings of letters which the package

   295 management system cannot interpret (such as ``ALPHA`` or ``pre-``), or

   296 with silly orderings (the author of this manual has heard of a package

   297 whose versions went ``1.1``, ``1.2``, ``1.3``, ``1``, ``2.1``, ``2.2``,

   298 ``2`` and so forth).

   299 

   300 [1]  Alphanumerics are ``A-Za-z0-9`` only.

   301 

   302 [2]  One common use of ``~`` is for upstream pre-releases.  For example,

   303      ``1.0~beta1~svn1245`` sorts earlier than ``1.0~beta1``, which sorts

   304      earlier than ``1.0``.