+------------------------------------------------------------------------------+
|                   Rosetta Package Manager Documentation                      |
|                   .....................................                      |
|                   Package Version Format and Comparison                      |
+------------------------------------------------------------------------------+

   This document describes the format of Rosetta package version indicators, and
   the way in which they are compared.


1 Permitted Characters
======================

   The following characters can be used in a package version identifier:
   -  lowercase letters [a-z]
   -  digits [0-9]
   -  the following punctuation: - . ~


2 Version String Format
=======================

   The package version identifier should have the following layout:

   [release-phase]<upstream-version>[~version-version-phase[version-release-phase-revision]][-package-revision]

   Components surrounded by [square brackets] is optional, while components
   surrounded by <triangular brackets> are required. If a component name
   is preceded by a punctuation mark, the value of that component in a package
   version identifier must also be preceded by that punctuation mark.

   The different version identifier components are defined as follows:
   -  release-phase (optional) indicates the release stage of the upstream
      software. allowable values are: alpha, beta

   -  upstream-version (required) indicates the version number of the upstream
      release. this is made up of one to five integers >= 0 separated by full
      stops.

   -  version-release-phase (optional) indicates the release stage of this
      particular version of the upstream software. allowable values are:
      alpha, beta, rc.

   -  version-release-phase-revision (optional) indicates the revision of the
      upstream package version within a given pre-release-version. must be
      a positive non-zero integer.

   -  package-revision (optional) indicates different versions of a particular
      package that contain the same version of the upstream software.

   Some examples of package versions include:
   -  1.0.0
      First revision of package for upstream release 1.0.0

   -  beta1.7
      First revision of package for upstream beta pre-release 1.7

   -  0.6-2
      Second revision of package for upstream release 0.6

   -  1.2~beta2
      First revision of package for the second beta pre-release of upstream
      version 1.2

   -  5.15~rc1-2
      Second revision of package for the first release-candidate pre-release of
      upstream version 5.15


3 Version Comparison
====================

   There are a number of rules that govern how package version identifiers are
   compared.


   3.1 Comparison Procedure
   ------------------------

   When comparing two version numbers, the five components are compared left to
   right using the following procedure:
   1. release-phase is compared according to Release Phase Precedence. If the
      two packages have different release-phase values, the one with higher
      precedence is considered the newer package. If one package does not have
      a release-phase, a release-phase of 'release' is assumed, which has the
      highest precedence.

   2. Each digit in upstream-version is compared left-to-right. If one package
      version has fewer digits than the other, the missing digits are assumed to
      be zero. If one package has a version digit greater than the other when
      read left-to-right, it is considered the newer package.

   3. version-release-phase is compared according to Release Phase Precedence.
      If the two packages have different version-release-phase values, the
      one with higher precedence is considered the newer package. If a package
      does not have a version-release-phase, a value of 'release' (with the
      highest precedence) is assumed, and step 4 is skipped.

   4. The package with the greater version-release-phase-revision is considered
      the newer package. If a package does not have a
      version-release-phase-revision, a value of one is assumed.

   5. The package with the greater package-revision is considered the newer
      package. If a package does not have a package-revision, a value of one is
      assumed.

   If each of the five components of two package versions is determined to be
   equal according to the above procedure, the two packages are considered to
   be equal in version.


   3.2 Release Phase Precedence
   --------------------------

   Release phases have a defined order of precedence which is used during
   comparisons. This order, in decending level of precedence, is:
   1. release (cannot be specified directly, but is used implicitly if no
      release phase is specified).
   2. rc
   3. beta
   4. alpha


vim: shiftwidth=3 expandtab