[Distutils] Review of latest draft of PEP 426 (Python package etadata v1.3)

[Nick Coghlan]

On Thu, Jan 31, 2013 at 9:39 PM, Donald Stufft <donald.stufft at gmail.com> wrote:
> On Thursday, January 31, 2013 at 1:20 AM, Nick Coghlan wrote:
>
>
> Correct. The desire is still to migrate to a more formal versioning
> scheme, hence PEP 386 by default if no Version-Scheme is specified.
> However, I don't want "but what if PEP 386 doesn't handle my
> pre/post/whatever release naming correctly" to be a potential blocker
> for migration the way it is with v1.2 of the metadata spec.
>
> Their is only one minor difference that I can find between how PEP386
> handles
> versions and how pkg_resources does. IMO We should moidfy PEP386 to
> match what pkg_resources did for that case and then as far as I can tell
> PEP386 will be a strict subset of pkg_resources.
>
> FWIW anyways

Ah, I finally managed to find the link I was looking for the other day
when I started this thread (the thread where you raised this question
last year and spelled out the details of the discrepancy:
http://mail.python.org/pipermail/distutils-sig/2012-September/018966.html)

By my reading, PEP 386 is fairly explicit overall about the way it
expected "dev" releases to be handled.

Firstly, it is explicit that it does *not* expect upstream projects to
use top level "dev" releases (point 2 in the PEP 386 requirements
sections). While it's not explicit on what it expects them to do
instead, the obvious alternative to dev releases is to start with
"alpha 0" instead of "alpha 1", as Python itself does:

    $ ./python -V
    Python 3.4.0a0

Secondly, PEP 386 is explicit that "dev" releases are then reserved
primarily for *package testing* (point 4 in the PEP 386 requirements
section), so it is possible to create developmental packages from
source control *without* conflicting with the eventual release name.

The problem with allowing both "pre" and "dev" (as suggested last
year) is that it's completely unclear how to sort them when they
appear at the same level. Does dev come before pre or after? Yes, a
computer can figure it out easily enough once you pick one order or
the other, but it's a bad combination for the human brain.

So, let's restrict our attentions (as Toshio recommended last year)
solely to the cases I was trying to address when proposing the
"Version-Scheme" field the other day: existing projects that currently
create "dev" releases before their alpha releases.

*If* we used Version-Scheme as the solution, then rather than just
falling back to "pkg_resources" comparison wholesale (with all the
permissiveness that implies), it might have been more appropriate for
the alternative scheme to be called "bare-dev-implies-a0". That is,
rather than being defined based on the current pkg_resources
behaviour, the new scheme would be based on the PEP 386 scheme, but
with the modification that when a tool sees an unqualified "X.Y.dev"
or "X.Y.Z.dev" release (i.e. any release where the "dev" immediately
follows the purely numeric component of the version), that should be
reinterpreted as if there was an "a0" component (as in "X.Y.a0.dev" or
"X.Y.Z.a0.dev") between the numeric component and the "dev" component
and sorted accordingly.

Alternatively, we could forget the Version-Scheme idea entirely, and
simply declare that "bare-dev-implies-a0" is a bug fix for a corner
case in PEP 386 that wasn't given sufficient consideration. Really,
what's the use case for making a bare "dev" release between a release
candidate and a full release? It doesn't make any sense (and if you
*really* needed to do something like that, you could do a post-release
of the previous release candidate instead). So, while the top level
dev release is listed between the final release candidate and the full
release in the example in PEP 386, I don't see any strong rationale
for doing it that way.

So, here's my suggestion for a way forward:

1. PEP 426 incorporates the "new versioning algorithm" section from
PEP 386 directly rather than by reference, with the clarification that
a top level "dev" release should be sorted before the first alpha
release
2. I accept PEP 426
3. I reject PEP 386 (there's a lot of irrelevant stuff in there about
changing distutils itself which is never going to happen anway)
4. I buy Daniel several beverages of his choice at PyCon US for
putting up with all this extra cleanup of the metadata spec that he
wasn't expecting when he proposed his update ;)

Thoughts?

Regards,
Nick.

-- 
Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia