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

[Ben Finney]

Trent Mick <trentm at gmail.com> writes:

> 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

Thank you for this series, it is good to have these summaries as a focus
for discussion.

> 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

An important part of the specification here is how versions compare
sequentially.

My understanding is the above version strings should be compared by the
following rules:

  * A version string is interpreted as a tuple of components. Each
    component is a sequence of characters from the set [0-9A-Za-z]. Each
    component is separated from others by a single full-stop (‘.’)
    character.

  * Two version strings are compared for sequence by comparing their
    component tuples.

    * Each pair of components (from the two version tuples) is compared
      from left to right.

    * Contiguous sequences of digits are interpreted as integers and
      compared numerically; other characters compare as per the ASCII
      character set sequence.

  * The first component in turn that differs between the two tuples
    thereby determines the sequencing of the two version strings; if all
    corresponding components compare equal then the two strings
    represent the same version.

My experience with version string interpretations suggests the above
rules formally describe a fairly solid consensus about how version
strings should compare.

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

Right, thank you for treating this as an addendum.

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

I think this description of setuptools's specifics is interesting only
in that it describes one particular implementation; I do *not* think any
authority should be vested in this implementation merely because it's
setuptools.

> # ".devNNNN" in the new versioning proposal
> 
> In general, people tended to agree that development builds are a
> reasonable thing.

No disagreement here.

> 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

My beef comes in at this point. Why on earth should we have a
specification that enshrines the above, which is only one of many
incompatible special-case extensions to an otherwise simple comparison
algorithm?

It's especially puzzling why we would choose something more complex when
“the run-up to 1.0” is easily versioned as version numbers that will
compare as previous to version 1.0.

    0.0.5
    0.18.3
    0.23
    0.999.dev-r342
    0.999.dev-r343
    0.999.dev-r350
    0.999.dev-r355
    1.0

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

It's precisely the fact that it's (AFAICT) far more controversial than
the solid consensus on the version comparisons without special cases
that makes me think it has no place in a specification that we hope to
be broadly accepted.

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

If that's an accurate representation of the discussion, I want to point
out the huge non sequitur that has occurred. I've demonstrated above
that one can easily have nightly builds of product X *and* have a simple
version comparison algorithm that has no special-cased words.

So it's a false dilemma to present it as “simple version comparison
versus versions for nightly builds”. We *can* have both, so anyone who
wants to take one of those away still has all their persuasion work
ahead of them.

> Why "dev" at all and not "-", "_", or "~" or just another "."?
[…]

> Why "dev"?
[…]

> Why ".devN" (1.0a1.dev456) instead of just "devN" (1.0a1dev456)?
[…]

All of these are secondary to “Why special-case any word at all,
instead of just using versions that *already* compare in the right
sequence by a simple uncontroversial algorithm with no special cases?”

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

What's wrong with appending more components so that these post-releases
will compare in the right sequence anyway?

Another demonstration:

    1.0      # release of 1.0

    1.0.0.1  # first post-1.0 release
    1.0.0.2  # second post-1.0 release

    1.0.1    # working on the next release
    1.0.2
    1.0.3

The “work leading up to version 1.1” has already been tagged version
1.0.1, 1.0.2 etc. Then the need for an additional release of the version
1.0 code is needed; that's tagged version 1.0.0.1, and the next such
release can be 1.0.0.2, etc. while 1.0.3 is developed.

This *works*, and is easily understood and IME obvious to know where the
versions compare. So again, anyone who wants to take away one of
“simple version comparison” and “ability to tag post-release versions
in correct sequence” has all their persuasive work ahead of them.

So I think both of “.devXXX needs to be special-cased” and “.postXXX
needs to be special-cased” are demonstrably false, and as a result the
inclusion of these into the specification is not sufficiently justified.

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

Thanks again.

-- 
 \         “Truth would quickly cease to become stranger than fiction, |
  `\                     once we got as used to it.” —Henry L. Mencken |
_o__)                                                                  |
Ben Finney