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

[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 at gmail.com