[Python-Dev] draft pep: backwards compatibility

[glyph at divmod.com]

On 09:21 am, solipsis at pitrou.net wrote:
><glyph <at> divmod.com> writes:
>>
>>In order for any changes to be possible, there needs to be a clearly
>>labeled mine-field: don't touch or depend on these things in your 
>>Python
>>application or it *will* break every time Python is released.
>
>I think the "frozen area" should be defined positively (explicit public 
>APIs and
>explicitly guaranteed behaviour) rather than negatively (an explicit 
>"mine
>field"). Otherwise, we will forget to put some important things in the 
>minefield
>and get bitten later when we need to change those things in a
>backwards-incompatible way.

This is a false dichotomy; for core developers, the list needs to be 
exhaustive.  Everything that can change needs to be described as either 
compatible or incompatible.

However, the reason I say that the list needs to be phrased as a 
whitelist is that we have to assume *all* people writing Python code, 
who ever want to be able to upgrade Python, need to *completely* 
understand the list of things which they should not depend on.  Every 
piece of documentation they read and every API they find, the assumption 
is that it's going to be compatible and it's not something they need to 
worry about.

It's important to remember that this PEP has a "public" (python 
application programmers) and "private" (python core developer) 
interfaces, too ;-).
>For example, I think it was wrong to change the name of a test-skipping 
>unittest
>method just so that it wouldn't clash with a method created by Twisted
>subclassing unittest (besides, self.skip() was much nicer than 
>self.skipTest()
>;-)). Just because some class is public shouldn't prevent us to add new 
>public
>methods or attributes to it.

I think it would be wrong to have a blanket prohibition on such changes, 
by which I mean additions of names to public namespaces.  Twisted's own 
compatibility possibility would not forbid a similar change.  But in 
that specific case I think it was the right thing to do.  Like it or 
not, a lot of people use Twisted, a lot of people run tests with Trial, 
and we beat stdlib unittest to the punch on the 'skip' testing feature 
by a good 5 years.  We caught the change well before the release, we 
reported it and discussed it.

IMHO this is the best way to deal with incompatible changes, especially 
in the case of superclasses, given Python's subtle and complex 
inheritance semantics.  It's not feasible to provide a policy that 
somehow prohibits subclasses from adding names which may eventually be 
used on a superclass.

Projects which notice test failures with new versions of Python should 
report them so that the features can be adjusted to be compatible, 
assuming the project in question hasn't done anything in egregious 
violation of the compatibility policy (like invoking a private method). 
This lets users, system administrators, and application authors upgrade 
components individually, without worrying about the components further 
down the stack flaking out on them.  It also provides a feedback loop 
for the compatibility policy: if there are things that initially seem 
reasonable, but projects report compatibility issues when they are 
changed, they might need to be added later.