[Python-Dev] Bugfix releases should not change APIs

[Steve Holden]

Terry Reedy wrote:
> I had the strong impression that there was a policy that x.y.z bugfix
> releases should only fix bugs and not add new features and revise
> current ones. The rationale, as I understood it, is that x.y.z releases
> should be increasingly better implementations of a stable x.y feature
> set. Adding features is 'bad' because code using a new feature will not
> work in previous releases of the same x.y version. Changing features is
> even worse because it may also break working code going forward.
> 
> Because of this policy, an x.y.z Windows installer (I do not know about
> others) deletes any earlier release of the same version. Also, there is
> no What's New in Python x.y.z (relative to x.y.(z-1) since such should
> be empty. Consequently, violations of the policy are pretty much silent
> and well hidden.
> 
> Yesterday, I spent two hours puzzling over the failure of my previously
> 'green' test sequence that tested a custom test function. I finally
> realized that the change was not due to anything I did (or undid), but a
> change in 3.1.2 in the interaction of StringIO.truncate,
> StringIO.getvalue, and print(x, StringIO()). (I should note the it is
> the usual stability and quality of Python that made me slow to blame
> Python rather than myself.)
> 
> After filing
> http://bugs.python.org/issue8840
> I was rather shocked to be told that the code-breaking and
> policy-violating change was intentional because being 'more consistent
> with other file-handling APIs out there' was somehow more important than
> consistency within version releases. It also seems to me that discussion
> of code-breaking API changes like this should involve more than one user
> and one developer. See
> http://bugs.python.org/issue6939
> 
> I have fixed my tests so they works in 3.1.2 and should work in other
> 3.1 releases, but that would be a nuisance to test. Of course, I should
> not have to worry about API changes within a version series.
> 
> I think issue 8840 illustrates another reason for the bugfix-only
> policy. New x.y features and docs are (nearly always) added before the
> first beta. They can then be tested, discussed, and improved. This
> 'cooking' does not occur for bugfix releases. For reasons I give in my
> response on the tracker, I think the new behavior is buggy and the doc
> deficient.
> 
> So, I think
> 1) the supposed bugfix-only policy should really be the policy;
> 2) the violation in 3.1.2 should be reverted in 3.1.3, and the API
> change reviewed in the normal 3.2 alpha/beta process.
> I am curious as to what others think on both points.
> 
I think it shows how developers can "get worked over" if they are
insufficiently vigilant.

1) I completely agree, and adduce as evidence the fact that something
like this always seems to happen when the rule is broken;

2) But we may wish to release 3.1.2.1(?) which backports fixes from the
3.2 line but retains the file store semantics (which I am assured will
be easy in the glorious reign of Hg).

Surely some compatible "shim" layer could have been introduced?

What is the process for ensuring that such API changes do *not* creep
into maintenance releases?

regards
 Steve


-- 
Steve Holden           +1 571 484 6266   +1 800 494 3119
See Python Video!       http://python.mirocommunity.org/
Holden Web LLC                 http://www.holdenweb.com/
UPCOMING EVENTS:        http://holdenweb.eventbrite.com/
"All I want for my birthday is another birthday" -
                                     Ian Dury, 1942-2000