[Python-Dev] Bugfix releases should not change APIs (original) (raw)

Steve Holden steve at holdenweb.com
Sat May 29 02:31:02 CEST 2010

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

More information about the Python-Dev mailing list