Great post, thanks a lot Trent !
Maybe you could push the summary in
http://wiki.python.org/moin/Distutils/VersionComparison
to decouple it from the Mailing List
Regards
Tarek
On Tue, Jun 9, 2009 at 9:58 AM, Trent Mick
Here-in my recollections of the Pycon distutils versioning discussions... but only up to the part where reasoning for the ".dev" and ".post" parts are added to the scheme.
Hopefully the following will be helpful for reference in the current version discussions.
# Goals
- as self-explanatory and clear versioning as reasonable. A whole dog's breakfast of versions is just a pain. - deterministic translation btwn version string and version tuple. Bonus points if two reasonable humans would sort them the same way. - capable dependency specs and reasonably readable
# Preliminaries
When I say things like "this isn't common on PyPI" below, this is from analysing a dump of all the version strings currently in use on PyPI. This list was produced by Martin von Loewis during Pycon.
# Super simple
A very simple versioning scheme for released packages would be:
major.minor.patch
where those are all numeric fields. Update the "patch"-level when making a small change without compatibility issues. Update the "minor" field when adding a feature. Update the "major" field when making backward incompat changes. Easy.
Incidentally this is what Ruby suggests for Gem authors ("Gems" are Ruby packages), though they call the last field "build":
[http://rubygems.org/read/chapter/7]
Any "public" release of a gem should have a different version. Normally that means incrementing the build number. This means a developer can generate builds all day long for himself, but as soon as he/she makes a public release, the version must be updated.
# "But I want to do an alpha release!"
I don't think I'm overstating in saying that most of us (those that care to help in defining Python packaging tools) would want to allow alpha/beta releases. Certainly this was true at the Pycon discussions. This gives us:
N.N.NaN # e.g. "1.0.0a2" N.N.NbN # e.g. "2.6.0b1"
Alternatives like the following were discarded:
- "1.0.0.a2" The '.' before the 'a' separator, while nice for parsing is not common practice at all. - "1.0.0alpha2" While this *does* appear on PyPI, it is less common than just using the single character. As well, Python itself uses 'a'. - "1.0.0a" No alpha version. The concensus was to not support this. Reasonable people disagreed on whether this would imply "a0" or "a1". It was felt that explicit was better than implicit here. As well, Python itself always has a version on the alpha/beta.
# To "c", or not to "rc"?
Doing a release candidate is reasonable too, it was felt. That gives us:
N.N.NaN # e.g. "1.0.0a2" N.N.NbN # e.g. "2.6.0b1" N.N.NcN # e.g. "2.6.0c1"
Why "c" instead of "rc"? All of "c", "rc", and "candidate" are in use on PyPI (I don't have percentages right now). "c" won because:
- that's what Python itself uses - the one-character symmetry with 'a' and 'b' is nice - it was felt that 'c' clearly enough indicated "release candidate"
So far I don't expect anything to be too controversial (but I'm probably wrong :).
# Just three N's?
The current PyPI versions include quite a few versions with just two "N's" -- e.g. "0.1", "3.5a2" -- as well as a some, though fewer, with four N's -- e.g. "1.5.4.3". This gives us (this is just a pseudo-pattern):
N.N[.N]*[(abc)N]
It was felt that just a single N -- e.g. "1" -- should be disallowed. However, the upper limit was left unbounded, i.e. this is allowed:
1.2.3.4.5.6.7.8.9a3
An example of where more N's is useful is for a Python module that wraps a third-party library. Say that library ("libfoo") version is 2.5.2, a reasonable version for "python-libfoo" might be "2.5.2.1.0" where the first three bits track the "libfoo" version.
# Multiple N's after the "abc".
"1.2.0a3.4" or in the pseudo-pattern I've been using:
N.N[.N]*[(abc)N[.N]*]
This was discussed and added. I don't recall who supported this.
Personally I've not had a need for this. 29 out of 4975 PyPI versions (in MvL's list generated during Pycon) use this -- and in 7 of those that last ".N" is a date stamp (e.g. "1.0a2.20070215") where I think the datestamp is meant as a sort of ".dev" or "pre-release" tag or build number.
# ... the rest
I'll try to post tomorrow night with my recollections and current understanding of the rational for the ".dev" and ".post" parts of the proposed version scheme.
Cheers, Trent
-- Trent Mick trentm@gmail.com _______________________________________________ Distutils-SIG maillist - Distutils-SIG@python.org http://mail.python.org/mailman/listinfo/distutils-sig
-- Tarek Ziadé | http://ziade.org