[Distutils] Differences in PEP386 and setuptools

[Toshio Kuratomi]

On Thu, Sep 27, 2012 at 09:25:51AM -0400, Donald Stufft wrote:
> On Thursday, September 27, 2012 at 9:12 AM, Erik Bray wrote:
> 
>     My guess--and this is pure speculation as I wasn't following the
>     original discussions either--is that it fell out of the desire to
>     require versions to be lexicographically ordered.
> 
This was not it.  I was for a lexicographic ordering but it was rejected.
> 
> 
> If that's the reason (and I wasn't around during the original discussions) then
> that's already been broken by rc/final (final is given an internal
> representation
> of `z` to allow ordering to work. 

Seems a little fragile :-)  But it is internal...
> 
> The way the PEP is written .devN is a pre-release of a specific version (a
> version
> being a numbered release of either alpha, beta, candidate, or final). While I
> think
> pre-releases of a specific version is likely useful in some context, I think
> that it
> should be using an identifier more like `pre`. Using the `dev` tag to me
> violates
> what a user expects from history.
> 
> I'm not discounting that there is a reason that makes sense though, hopefully
> if
> there is one someone will be able to come forth with it.
>
I was hoping that Tarek would chime in since the discussion about this was
years ago (2009, I think) and my memory is slightly fuzzy.  I'll try to
remember the rationale and Tarek can correct me.

setuptools allows any random string into the versions.  Certain strings have
special meaning.  Unknown strings are lexicographically sorted.  Rereading
this section of the PEP
http://www.python.org/dev/peps/pep-0386/#caveats-of-existing-systems

will give you the background on problems with the setuptools concept.
For part of the rationale about .dev, the first paragraph of the rationale
is important.  setuptools allowed too many things to be allowed into
versions.  Remembering how the specialcases mix with the lexicographic
sorting lead to confusion when some project starts working with non-standard
version strings.  So one of the goals of PEP 386 was to make a small,
discrete number of legal version strings.

Keeping that in mind, these are the alpha tags that PEP386 allows:
a, b, c, rc, .post, .dev

* a, b, c, and rc are the typical alpha beta release candidate tags.  We
  debated whether to allow the single letter versions or the long versions
  "alpha", "beta", "rc".  In the end, which set of tags was used was
  a bikeshed argument so it was chosen by PEP-author decree.  I personally
  felt that having both "c" and "rc" was counter to the goals of the PEP but
  we at least agreed that "rc" would intuitively sort after "c" so it wasn't
  as bad as having both "alpha" and "a" where there would be no intuitively
  correct sorting.
* For .post there was a desire to have a tag that sorted after release.
  Choice of .post for the bikeshed color was not controversial.
* For .dev there was a desire to have a tag that sorted before release.
  Choice of .dev for the bikeshed was debated but in the end it was
  a bikeshed and we were all very tired of it.  I'm not sure at this point
  who was championing .dev over .pre or similar or what their rationale was.


> I personally feel
> though
> that the current behavior is unexpected, will cause confusion as long as
> releases
> are being ordered by both pkg_resources and PEP386, and goes against common
> usage of the release tags. My proposal would be to replace the .devN
> pre-release
> tag with .preN, and add a `devN` tag (perhaps optional N, with an omitted N
> being
> equal to `dev0`. I feel like this will fit into people's expectations better,
> and make
> migration easier.
>
I would be for renaming .dev to .pre[1]_ but I would be against the rest of this
proposal.  Having one and only one way to spell things was one of the goals
of the pep.  Having two post release tags that don't already have a defined
meaning leads to confusion about what the ordering should be:

   foo-1.0.dev486 > foo-1.0.post486
   foo-1.0.dev486 < foo-1.0.post486

   foo-1.0.dev486 > foo-1.0.post386
   foo-1.0.dev486 < foo-1.0.post386

To someone who doesn't know the sorting order specified by PEP386, there's
no obvious way to tell which of those is true and which is false.

.. [1]_: rationale for .pre since someone probably has a rationale for .dev
         to counter this:
           * .pre makes it obvious that it has the opposite meaning and use
             case as .post.
           * .pre is more descriptive of how it is supposed to sort than .dev

-Toshio
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 198 bytes
Desc: not available
URL: <http://mail.python.org/pipermail/distutils-sig/attachments/20120927/b731a68a/attachment.pgp>