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

[Trent Mick]

Here-in the second part of my recollections of the Pycon distutils versioning
discussions. This first part is here:
http://mail.python.org/pipermail/distutils-sig/2009-June/012143.html

The first part left us with this pseudo-pattern:

  N.N[.N]*[(abc)N[.N]*]

Some examples to help illustrate:

  1.0
  1.4.2.45.2.2.5
  1.2.3a4
  1.34.5.6c1
  3.0b2.1

That leaves the ".devN" and ".postN" business of the current version
proposal (PEP 386).

# A brief setuptools lesson

(Mainly this is because I needed it -- I'm not intimately familiar with
setuptools. Skip this section if you know this already.)

Setuptools defines
(http://peak.telecommunity.com/DevCenter/setuptools#specifying-your-project-s-version)
"pre-release tags" and "post-release tags" on a version number. In setuptools
one part of the "pre-release tags" are the "a", "b", "c" (for alpha, beta,
candidate) parts of the proposed pattern that we've already discussed. The
remaining part of "pre-release tags" is the use of "dev" or "pre", e.g.:

    1.0dev
    2.5.2pre
    3.1dev459259

(Strictly speaking also "preview" and any string that sorts less than
"final", but "dev" and "pre" are the common ones.)

"Post-release tags" are any non-numeric in the version string that sorts
greater than "final" or the special case "-". Practically speaking it is
almost always the latter because setuptools provides command-line
options (http://peak.telecommunity.com/DevCenter/setuptools#egg-info) to
automatically append an svn rev ("-rNNNNN") or a date ("-YYYYMMDD").
Examples:

    1.0-r2345
    5.4.3-20090107


# ".devNNNN" in the new versioning proposal

Reminder: I'm just trying to describe my recollections of the Pycon
discussions here. I'll post my current opinions in a separate email. I.e.,
don't shoot the messenger. :)

In general, people tended to agree that development builds are a reasonable
thing. Your project is in the run-up to 1.0 and you'll be doing regular
builds at incremental revisions of your source code control system.
Setuptools encourages (by offering certain command-line options) spelling
this kind of thing this way (though, of course there are other spellings of
the equivalent):

    1.0dev-r342
    1.0dev-r343
    1.0dev-r350
    1.0dev-r355

At this point in the Pycon discussions I vaguely recall that there was some
opposition to having support for spelling development builds in the
versioning scheme at all. However, I don't fully recall. If so, they were won
over (or drowned out) by (a) others giving examples of doing daily/nightly
builds of product X -- including me describing nightlies of the Komodo
product (not a
Python project) I work on -- and (b) the start of the debate on how to spell
"1.0dev-r342", those presuming that its inclusion was a forgone conclusion.
I'll touch more on this in a followup email.

Ensuing debate, pleading, fisticuffs, cajoling ... leading to

    N.N[.N]*[(abc)N[.N]*][.devN]
    1.0.dev456
    2.5.0b2.dev523

Why "dev" at all and not "-", "_", or "~" or just another "."? None of the
alternatives were explicit that this is a release that should sort *earlier*
than the version without it. Also, '-' is used to setuptools to mean a
*post*-release; '_' causes problems for Debian packaging; '~' is used in
Debian package versioning (IIRC, best to avoid using it); just '.' (e.g.
'1.0a1.456') can be ambiguous.

Why "dev"? Because it is by far the most common string used for this in
current PyPI versions. "pre" a far second.

Why ".devN" (1.0a1.dev456) instead of just "devN" (1.0a1dev456)? Partly a
feeling that the '.' helped separate from the leading part -- if "1.0.a1"
didn't look ridiculous we probably would have chosen that too.  :)
Also partly because there is justifiably little point in quibbling for
hours over a single '.' here.


# ".postNNNN" in the new versioning proposal

Amid fading sounds of hands being dusted off, backs being patted and
rising discussions of what's for dinner ("Salad bar or steak?" "What's
the special tonight?") the question:

    "What about post-releases?" -- Zooko

Groans. "Who uses that?" "Twisted, for example." "Really? Hrm, okay,
let's tack on a '.postN' (like the '.devN') and call it a night."

The discussion *was* longer than that, but not a whole lot longer. Mostly the
justification for ".postN" in the proposal rested on the example of at least
a couple significant Python projects using this (e.g. Twisted). An example
of the resulting sorting order:

    1.0a1
    1.0a2.dev456
    1.0a2
    1.0a2.1.dev456
    1.0a2.1
    1.0b1.dev456
    1.0b2
    1.0c1.dev456
    1.0c1
    1.0.dev456
    1.0
    1.0.post456

and the final pseudo-pattern:

    N.N[.N]*[(a|b|c)N[.N]*][(.devN|.postN)]

Those are my recollections of the Pycon versioning discussions. I want to
following up (in a separate email) with my current opinions.



Cheers,
Trent

-- 
Trent Mick
trentm at gmail.com