[Distutils] recollections of Pycon distutils versioning discussion (part 1)

[Tarek Ziadé]

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<trentm at gmail.com> wrote:
> 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 at gmail.com
> _______________________________________________
> Distutils-SIG maillist  -  Distutils-SIG at python.org
> http://mail.python.org/mailman/listinfo/distutils-sig
>



-- 
Tarek Ziadé | http://ziade.org