doc: add lots of sample files

doc/package-versions.txt

@@ -0,0 +1,124 @@
++------------------------------------------------------------------------------+
+|                   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