wiki:OnVersionNumbers
Last modified 7 years ago Last modified on 03/16/2012 10:07:40 AM

LSST Version Numbers

Revised 27 Aug 2010
Revised 2 Mar 2011

Motivation

LSST has a policy on everything, and that includes version numbers. In this case, the rules are designed to allow us to define an ordering on software packages, so we can unambiguously say, "Use a version later than 1.2.3.4".

What's the motivation of these complicated rules? The primary sort should be intuitive. People often name pre-release candidates things like 1.2-rc2, hence the rule for 1.2 being later than 1.2-rc2. After a version is released, you sometimes need a fixed version, so its name should sort later --- hence 1.2+bugfix.

See wikipedia for a discussion of version numbering schemes.

Sorting Rules

Version names are taken to be of the form AAA.BBB.CCC.DDD-LLL.MMM.NNN+XXX.YYY.ZZZ where -LLL.MMM.NNN and +XXX.YYY.ZZZ are optional. Let's call AAA.BBB.CCC.DDD the primary part, LLL.MMM.NNN the secondary part, and XXX.YYY.ZZZ the tertiary part. The components (AAA etc.) of the primary part must be integers, but there is no such restriction on the secondary or tertiary parts. Any number of components are permitted. If you wish, you may use _ instead of . as separators (this makes cvs happier). Examples of valid versions are:

  1.22.333.444
  1.2.3.4-rc1
  1.2.3.4-a.b
  1.2.3.4+fix1
  1.2.3.4-rc1+fix1

The sorting rules are:

The primary part is then split on . (or _), and each pair of components in the two names is compared (numerically or lexicographically as appropriate). If they differ, the version name with the smaller component is taken to sort to the left, and the comparison stops.

If one of the two versions is longer, and matches the shorter to its end, the longer version sorts to the right. This only applies to the primary part; any secondary part is ignored in this comparison.

If the two primary parts are identical, then the secondary part is examined; the same rules on sorting are applied. If only one version has a secondary part, it sorts to the left -- so 1.2-rc2 sorts to the left of 1.2.

If the primary and secondary parts are identical, then the tertiary part is examined, applying the same rules as the secondary, except that if only one version has a tertiary part it sorts to the right, so 1.2+hack sorts to the right of 1.2.

Examples

Here are some examples:

v1 v2 compar notes
1 1 0
1.2 1.1 +1 Sort components numerically
1.2.1 1.2 +1
1.2.1 1.2.2 -1
1.2.1 1.3 -1
1_0_2 1.0.0 +1 You can mix . and _
1.2-a 1.2 -1 primary parts are identical, so secondary is examined
1.2-a 1.2-b -1
1.2-0 1.2.3 -1 primary parts differ, so secondary parts are ignored
1.2-4 1.2.3 -1
1.2+h1 1.2 +1 tertiary part is used
1.2-rc1+h1 1.2-rc1 +1

(Here compar is the value that C's qsort would use; -1 if v1 is less than v2; 0 if they're equal; +1 if v1 > v2).

Meaning of primary components

The following describes the convention for version numbers assigned to LSST packages.

  • Most package versions will consist of 4 dot-delimited integer fields
    • <Major release> - indicates a major release of the LSST stack as a whole, reflecting a major milestone in the LSST software development schedule. Currently, this changes with each major data challenge increment. Each Winter/Summer? release will have a new major release number.
    • <Branch> - indicates the sequence number of the branch within the <major release>. Odd numbers represent latest development releases that have been tagged from trunk; even numbers represent incremental (e.g. bug fix) releases from a "frozen" set of releases used in data challenge production runs. These intermediate releases are expected to occur at approximately monthly intervals. Note that packages unchanged from a previous release will not receive new version numbers.
    • <API change> - incremented in the event of a backward- incompatible API and/or ABI change from the previous tag. A change in this field indicates that other packages that depend on this may need to be either rebuilt or updated to adapt to this change. A tag on a new branch will always start with 0 in this field.
    • <Minor Release> - incremented in the event of a backward- compatible API and/or ABI change from the previous tag. A tag on a new branch will always start with 0 in this field.
  • Deviations from this pattern typically represent
    • releases tagged prior to the acceptance of the policy
    • releases intended specifically for non-LSST purposes
  • Release branches were captured in svn under the package's tags directory. The name of the release is the version string--e.g. 4.8.3.2. It does not include a "v" or "version" in the name. They are captured in git as {Summer,Winter}year/releasename.
  • Pre-release candidates of third party software often append strings such as `-rc2'. These version names may be used in LSST dependencies, but we don't currently plan to use such a scheme for our own software.
  • A repackaging of a release may append a "+tag" field, as in 4.8.3.2+1, which can be an integer or a string. Since none of the underlying code is different from the corresponding release (e.g. "4.8.3.2"), this extra tag does not appear in a directory name under tags. You may see it though as part of the version registered with ups. That is, to load such a version, you might type setup pkg 4.8.3.2+1.
  • In the case of external packages, we may need to make code changes. In this case, the tag name will correspond to a tag in svn.

Version Numbers and Eups

Eups supports a superset of these rules for sorting version numbers as of v0_7_34 (and yes, that is a version name that it understands).

In particular, table files may include statements such as

productRequired(scons >= 1.16 || == svn)