commit 8b4a12a25b4d069fd09e6a7444f33e33d50d43f8
Author: Damian Johnson <atagar(a)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