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

[Paul Moore]

2009/6/9 Trent Mick <trentm at gmail.com>:
> 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

 +1 to all this

> # 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.

OK

> # Super simple
>
> A very simple versioning scheme for released packages would be:
>
>    major.minor.patch
[...]
> # "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"
[...]
> # 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"
[...]
> So far I don't expect anything to be too controversial (but I'm probably
> wrong :).

All +1 from me.

> # 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

I see no issue with this - I'd expect it to be a relatively rarely
used generalisation, but conceptually it costs nothing, so I'm fine
with it. Actually, I do know of (non-Python) cases where a single N is
used - less is probably the best known - but I certainly don't care
enough to insist one way or the other.

> 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.

Purely theoretical example, I assume? I doubt I'd do this, but again,
who cares? No conceptual cost.

> # 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.

-1

29/4975 is hardly anything, and I don't believe this should be defined
on a "someone uses it so we should allow it" basis.

If someone supports this, they should be presenting a good use case,
with an explanation of why it is of value *to the end user* (ie, not
just to the project developers).

For something to consider - my view is that if you've done 2.2a1 and
you want a new release, it should be 2.2a2 - not 2.2a1.1 or any such
thing. If it's not good enough to be an a2, then why are you releasing
it? Note: there's an assumption implicit in this that a "version" is
something attached to a release - I have little sympathy with the idea
that every single Subversion revision (or Mercurial changeset, or
whatever) should have a unique "version" number. Unreleased versions
should be identified differently (and nobody should be specifying
dependencies on unreleased versions, before anybody suggests that!)

> # ... 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.

Thanks for posting this. So far, it's relatively uncontroversial, but
it still makes a great summary of the arguments and conclusions.

Paul.