attic/text_formats/version-spec.txt

   1
   2                         HOW TOR VERSION NUMBERS WORK
   3
   4 Table of Contents
   5
   6     1. The Old Way
   7     2. The New Way
   8     3. Version status.
   9
  10 1. The Old Way
  11
  12  Before 0.1.0, versions were of the format:
  13
  14      MAJOR.MINOR.MICRO(status(PATCHLEVEL))?(-cvs)?
  15
  16  where MAJOR, MINOR, MICRO, and PATCHLEVEL are numbers, status is one
  17  of "pre" (for an alpha release), "rc" (for a release candidate), or
  18  "." for a release.  As a special case, "a.b.c" was equivalent to
  19  "a.b.c.0".  We compare the elements in order (major, minor, micro,
  20  status, patchlevel, cvs), with "cvs" preceding non-cvs.
  21
  22  We would start each development branch with a final version in mind:
  23  say, "0.0.8".  Our first pre-release would be "0.0.8pre1", followed by
  24  (for example) "0.0.8pre2-cvs", "0.0.8pre2", "0.0.8pre3-cvs",
  25  "0.0.8rc1", "0.0.8rc2-cvs", and "0.0.8rc2".  Finally, we'd release
  26  0.0.8.  The stable CVS branch would then be versioned "0.0.8.1-cvs",
  27  and any eventual bugfix release would be "0.0.8.1".
  28
  29 2. The New Way
  30
  31  Starting at 0.1.0.1-rc, versions are of the format:
  32
  33     MAJOR.MINOR.MICRO[.PATCHLEVEL][-STATUS_TAG][ (EXTRA_INFO)]*
  34
  35  The stuff in parentheses is optional.  As before, MAJOR, MINOR, MICRO,
  36  and PATCHLEVEL are numbers, with an absent number equivalent to 0.
  37  All versions should be distinguishable purely by those four
  38  numbers.
  39
  40  The STATUS_TAG is purely informational, and lets you know how
  41  stable we think the release is: "alpha" is pretty unstable; "rc" is a
  42  release candidate; and no tag at all means that we have a final
  43  release. If the tag ends with "-cvs" or "-dev", you're looking at a
  44  development snapshot that came after a given release.  If we *do*
  45  encounter two versions that differ only by status tag, we compare them
  46  lexically. The STATUS_TAG can't contain whitespace.
  47
  48  The EXTRA_INFO is also purely informational, often containing information
  49  about the SCM commit this version came from. It is surrounded by parentheses
  50  and can't contain whitespace. Unlike the STATUS_TAG this never impacts the way
  51  that versions should be compared. EXTRA_INFO may appear any number of
  52  times. Tools should generally not parse EXTRA_INFO entries.
  53
  54  Now, we start each development branch with (say) 0.1.1.1-alpha.  The
  55  patchlevel increments consistently as the status tag changes, for
  56  example, as in: 0.1.1.2-alpha, 0.1.1.3-alpha, 0.1.1.4-rc, 0.1.1.5-rc.
  57  Eventually, we release 0.1.1.6.  The next patch release is 0.1.1.7.
  58
  59  Between these releases, CVS is versioned with a -cvs tag: after
  60  0.1.1.1-alpha comes 0.1.1.1-alpha-cvs, and so on. But starting with
  61  0.1.2.1-alpha-dev, we switched to SVN and started using the "-dev"
  62  suffix instead of the "-cvs" suffix.
  63
  64 3. Version status.
  65
  66   Sometimes we need to determine whether a Tor version is obsolete,
  67   experimental, or neither, based on a list of recommended versions.  The
  68   logic is as follows:
  69
  70    * If a version is listed on the recommended list, then it is
  71      "recommended".
  72
  73    * If a version is newer than every recommended version, that version
  74      is "experimental" or "new".
  75
  76    * If a version is older than every recommended version, it is
  77      "obsolete" or "old".
  78
  79    * The first three components (major,minor,micro) of a version number
  80      are its "release series".  If a version has other recommended
  81      versions with the same release series, and the version is newer
  82      than all such recommended versions, but it is not newer than
  83      _every_ recommended version, then the version is "new in series".
  84
  85    * Finally, if none of the above conditions hold, then the version is
  86      "un-recommended."