diff options
author | Nick Mathewson <nickm@torproject.org> | 2023-10-12 12:27:58 -0400 |
---|---|---|
committer | Nick Mathewson <nickm@torproject.org> | 2023-10-12 12:27:58 -0400 |
commit | f7e5a95ee96d8ef52c1732d066c1249a6f84391e (patch) | |
tree | 2e1ddd85f471143518d0df7c7645d066d43bc149 /spec/version-spec.md | |
parent | e4e0d93d56ee8c1aec4c2efaa7046b651f0fe55c (diff) | |
download | torspec-f7e5a95ee96d8ef52c1732d066c1249a6f84391e.tar.gz torspec-f7e5a95ee96d8ef52c1732d066c1249a6f84391e.zip |
Convert text specifications to mdbook.
Diffstat (limited to 'spec/version-spec.md')
-rw-r--r-- | spec/version-spec.md | 93 |
1 files changed, 93 insertions, 0 deletions
diff --git a/spec/version-spec.md b/spec/version-spec.md new file mode 100644 index 0000000..ac9432b --- /dev/null +++ b/spec/version-spec.md @@ -0,0 +1,93 @@ +HOW TOR VERSION NUMBERS WORK + +Table of Contents + +```text + 1. The Old Way + 2. The New Way + 3. Version status. +``` + +<a id="version-spec.txt-1"></a> +# 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". + +<a id="version-spec.txt-2"></a> +# 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. + +<a id="version-spec.txt-3"></a> +# Version status. + +```text + 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." +``` + |