[tor-commits] [torspec/master] Adding an EXTRA_INFO attribute to tor versions

[nickm at torproject.org]

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