1 files changed, 86 insertions, 0 deletions
diff --git a/attic/text_formats/version-spec.txt b/attic/text_formats/version-spec.txt
new file mode 100644
index 0000000..615f6f2
--- /dev/null
+++ b/attic/text_formats/version-spec.txt
@@ -0,0 +1,86 @@
+
+                        HOW TOR VERSION NUMBERS WORK
+
+Table of Contents
+
+    1. The Old Way
+    2. The New Way
+    3. Version status.
+
+1. The Old Way
+
+ Before 0.1.0, versions were of the format:
+
+     MAJOR.MINOR.MICRO(status(PATCHLEVEL))?(-cvs)?
+
+ where MAJOR, MINOR, MICRO, and PATCHLEVEL are numbers, status is one
+ of "pre" (for an alpha release), "rc" (for a release candidate), or
+ "." for a release.  As a special case, "a.b.c" was equivalent to
+ "a.b.c.0".  We compare the elements in order (major, minor, micro,
+ status, patchlevel, cvs), with "cvs" preceding non-cvs.
+
+ We would start each development branch with a final version in mind:
+ say, "0.0.8".  Our first pre-release would be "0.0.8pre1", followed by
+ (for example) "0.0.8pre2-cvs", "0.0.8pre2", "0.0.8pre3-cvs",
+ "0.0.8rc1", "0.0.8rc2-cvs", and "0.0.8rc2".  Finally, we'd release
+ 0.0.8.  The stable CVS branch would then be versioned "0.0.8.1-cvs",
+ and any eventual bugfix release would be "0.0.8.1".
+
+2. The New Way
+
+ Starting at 0.1.0.1-rc, versions are of the format:
+
+    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
+ 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. 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. EXTRA_INFO may appear any number of
+ times. Tools should generally not parse EXTRA_INFO entries.
+
+ Now, we start each development branch with (say) 0.1.1.1-alpha.  The
+ patchlevel increments consistently as the status tag changes, for
+ example, as in: 0.1.1.2-alpha, 0.1.1.3-alpha, 0.1.1.4-rc, 0.1.1.5-rc.
+ Eventually, we release 0.1.1.6.  The next patch release is 0.1.1.7.
+
+ Between these releases, CVS is versioned with a -cvs tag: after
+ 0.1.1.1-alpha comes 0.1.1.1-alpha-cvs, and so on. But starting with
+ 0.1.2.1-alpha-dev, we switched to SVN and started using the "-dev"
+ suffix instead of the "-cvs" suffix.
+
+3. Version status.
+
+  Sometimes we need to determine whether a Tor version is obsolete,
+  experimental, or neither, based on a list of recommended versions.  The
+  logic is as follows:
+
+   * If a version is listed on the recommended list, then it is
+     "recommended".
+
+   * If a version is newer than every recommended version, that version
+     is "experimental" or "new".
+
+   * If a version is older than every recommended version, it is
+     "obsolete" or "old".
+
+   * The first three components (major,minor,micro) of a version number
+     are its "release series".  If a version has other recommended
+     versions with the same release series, and the version is newer
+     than all such recommended versions, but it is not newer than
+     _every_ recommended version, then the version is "new in series".
+
+   * Finally, if none of the above conditions hold, then the version is
+     "un-recommended."