Split version info into separate spec doc.

svn:r3783

6 files changed, 55 insertions, 36 deletions

diff --git a/contrib/osx/package.sh b/contrib/osx/package.sh
index afb7268566..09779b7540 100644
--- a/contrib/osx/package.sh
+++ b/contrib/osx/package.sh
@@ -129,7 +129,7 @@ groff doc/tor.1 -T ps -m man | ps2pdf - $DOC/tor-reference.pdf
 groff doc/tor-resolve.1 -T ps -m man | ps2pdf - $DOC/tor-resolve.pdf
 
 mkdir $DOC/Advanced
-cp doc/tor-spec.txt doc/rend-spec.txt doc/control-spec.txt doc/socks-extensions.txt $DOC/Advanced
+cp doc/tor-spec.txt doc/rend-spec.txt doc/control-spec.txt doc/socks-extensions.txt doc/version-spec.txt $DOC/Advanced
 cp doc/CLIENTS $DOC/Advanced/CLIENTS.txt
 cp doc/HACKING $DOC/Advanced/HACKING.txt
 cp ChangeLog $DOC/Advanced/ChangeLog.txt
diff --git a/contrib/package_nsis.sh b/contrib/package_nsis.sh
index 770913f472..8ad3e391c3 100644
--- a/contrib/package_nsis.sh
+++ b/contrib/package_nsis.sh
@@ -28,7 +28,7 @@ clean_newlines() {
 }
 
 for fn in CLIENTS tor-spec.txt HACKING rend-spec.txt control-spec.txt \
-   tor-doc.html tor-doc.css; do
+   tor-doc.html tor-doc.css version-spec.txt; do
     clean_newlines doc/$fn win_tmp/doc/$fn
 done
 
diff --git a/doc/Makefile.am b/doc/Makefile.am
index f41355a48c..861a62254e 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1,4 +1,4 @@
-EXTRA_DIST = tor-spec.txt CLIENTS FAQ HACKING rend-spec.txt control-spec.txt tor-doc.html tor-doc.css tor-resolve.1
+EXTRA_DIST = tor-spec.txt CLIENTS FAQ HACKING rend-spec.txt control-spec.txt tor-doc.html tor-doc.css tor-resolve.1 version-spec.txt
 
 man_MANS = tor.1 tor-resolve.1
 
diff --git a/doc/TODO b/doc/TODO
index eb14e430f7..b55bde5dc9 100644
--- a/doc/TODO
+++ b/doc/TODO
@@ -116,8 +116,11 @@ R o HTTPS proxy for OR CONNECT stuff. (For outgoing SSL connections to
   o Feed end reason back into SOCK5 as reasonable.
 R o cache .foo.exit names better, or differently, or not.
   o make !advertised_server_mode() ORs fetch dirs less often.
-N - Clean up NT service code even more.  Document it. Enable it by default.
-    Make sure it works.
+N . NT Service code
+    o Clean up NT service code even more.
+    o Enable it by default.
+    o Make sure it works.
+    . Document it.
 
  Documentation
   o Document new version system.
diff --git a/doc/version-spec.txt b/doc/version-spec.txt
new file mode 100644
index 0000000000..85a964a082
--- /dev/null
+++ b/doc/version-spec.txt
@@ -0,0 +1,46 @@
+$Id$
+
+HOW TOR VERSION NUMBERS WORK
+============================
+
+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".
+
+
+The New Way
+-----------
+
+After 0.1.0, versions are of the format:
+   MAJOR.MINOR.MICRO(.PATCHLEVEL)(-status_tag)
+The stuff in parenthesis 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", 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.
+
+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.
diff --git a/src/or/or.h b/src/or/or.h
index 7e02496e2c..c802401964 100644
--- a/src/or/or.h
+++ b/src/or/or.h
@@ -1790,37 +1790,7 @@ void clear_trusted_dir_servers(void);
 /** Structure to hold parsed Tor versions.  This is a little messier
  * than we would like it to be, because we changed version schemes with 0.1.0.
  *
- * 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".
- *
- * After 0.1.0, versions are of the format:
- *    MAJOR.MINOR.MICRO(.PATCHLEVEL([-.]status_tag)?)?
- * 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.  If we *do*
- * encounter two versions that differ only by status tag, we compare them
- * lexically.
- *
- * 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.
+ * See version-spec.txt for the whole business.
  */
 typedef struct tor_version_t {
   int major;