[Numpy-discussion] Going toward time-based release ?

[Robert Kern]

On Mon, May 12, 2008 at 12:43 AM, Jarrod Millman <millman at berkeley.edu> wrote:
> On Sun, May 11, 2008 at 9:42 PM, Robert Kern <robert.kern at gmail.com> wrote:
>> The semantics of major.minor.micro for numpy got confused because of
>> an early mistake (IMO) wherein we designated 1.1 as a release which
>> would allow code breakage.
>
> I disagree.  I didn't realize that the ma change was going to break
> anyone's code.  Once I understood that it did I decided to call the
> release 1.1.0 rather than 1.0.5.

That's not what I'm referring to. Before 1.0 was released, people were
worried about the stability of the API, and Travis said that 1.0.x
would maintain API compatibility, but that 1.1, "maybe a year from
now," would be the opportunity to make API changes again. I think that
statement colored development substantially. We had to add features to
1.0.x releases instead of just bugfixes because 1.1 was going to be
this big thing.

> I think that it is reasonable to
> allow some API breakage in a minor release, but that there is no
> reason to encourage it and we should absolutely not require it.  The
> problem as I see it is that we were abusing the maintenance releases
> to add a significant number of features, rather than just simply
> fixing bugs.
>
>> I would very much like to get away from
>> that and follow Python's model of only doing bugfixes/doc-enhancements
>> in micro releases, new features in minor releases and code breakage
>> never (or if we absolutely must, only after one full minor release
>> with a deprecation warning).
>
> +1
> I absolutely agree.

You keep saying that you agree with me, but then you keep talking
about allowing "minor code breakage" which I do not agree with. I
don't think I am communicating the aversion to code breakage that I am
trying to espouse. While strictly speaking, there is a conceivable
reading of the words you use ("I think that it is reasonable to allow
some API breakage in a minor release" for example) which I can agree
with, I think we're meaning slightly different things. In particular,
I think we're disagreeing on a meta level. I do agree that
occasionally we will be presented with times when breaking an API is
warranted. As a prediction of future, factual events, we see eye to
eye.

However, I think we will make better decisions about when breakage is
warranted if we treat them as _a priori_ *un*reasonable. Ultimately,
we may need to break APIs, but we should feel bad about it. And I mean
viscerally bad. It is too easy to convince one's self that the new API
is better and cleaner and that "on balance" making the break is better
than not doing so. The problem is that the thing that we need to
balance this against, the frustration of our users who see their code
break and all of *their* users, is something we inherently can not
know. Somehow, we need to internalize this frustration ourselves.
Treating the breaking of code as inherently unreasonable, and refusing
to accept excuses *even if they are right on the merits* is the only
way I know how to do this. The scales of reason occasionally needs a
well-placed thumb of unreason.

-- 
Robert Kern

"I have come to believe that the whole world is an enigma, a harmless
enigma that is made terrible by our own mad attempt to interpret it as
though it had an underlying truth."
 -- Umberto Eco