commit 8b4a12a25b4d069fd09e6a7444f33e33d50d43f8 Author: Damian Johnson <atagar@torproject.org> Date: Sat Jul 21 20:23:54 2012 -0700 Adding an EXTRA_INFO attribute to tor versions Tor versions often contain information about the SCM commit they came from, for instance... 0.2.3.16-alpha-dev (git-8be6058d8f31e578) This isn't part of the spec, which in turn choked stem when I tried to parse those versions. Adding this in and better defining a couple other points... - The STATUS_TAG should only contain non-whitespace. Otherwise... well, just about *anything* could be a 'valid' status tag. - The spec says that status tags should be "compared lexically". The ASCII value of 'Z' is greater than 'A' so I guess this means that they're sorted in a reverse alphabetical order. This seems weird, but clarifying it. --- version-spec.txt | 14 +++++++++++--- 1 files changed, 11 insertions(+), 3 deletions(-) diff --git a/version-spec.txt b/version-spec.txt index b017335..54a2ac0 100644 --- a/version-spec.txt +++ b/version-spec.txt @@ -21,17 +21,25 @@ 2. The New Way After 0.1.0, versions are of the format: - MAJOR.MINOR.MICRO(.PATCHLEVEL)(-status_tag) + MAJOR.MINOR.MICRO[.PATCHLEVEL][-STATUS_TAG][ (EXTRA_INFO)] The stuff in parentheses is optional. As before, MAJOR, MINOR, MICRO, and PATCHLEVEL are numbers, with an absent number equivalent to 0. All versions should be distinguishable purely by those four - numbers. The status tag is purely informational, and lets you know how + numbers. + + The STATUS_TAG is purely informational, and lets you know how stable we think the release is: "alpha" is pretty unstable; "rc" is a release candidate; and no tag at all means that we have a final release. If the tag ends with "-cvs" or "-dev", you're looking at a development snapshot that came after a given release. If we *do* encounter two versions that differ only by status tag, we compare them - lexically as ASCII byte strings. + lexically as ASCII byte strings (ie, reverse-alphabetically so 'b' comes + before 'a'). The STATUS_TAG can't contain whitespace. + + The EXTRA_INFO is also purely informational, often containing information + about the SCM commit this version came from. It is surrounded by parentheses + and can't contain whitespace. Unlike the STATUS_TAG this never impacts the way + that versions should be compared. Now, we start each development branch with (say) 0.1.1.1-alpha. The patchlevel increments consistently as the status tag changes, for