Bugfix releases should not change APIs
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.
Terry Jan Reedy
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
- the supposed bugfix-only policy should really be the policy;
- 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
2010/5/28 Steve Holden steve@holdenweb.com:
Terry Reedy wrote:
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.
This was discussed on the mailing list and this was produced: http://mail.python.org/pipermail/python-dev/2009-September/092247.html
What is the process for ensuring that such API changes do *not* creep into maintenance releases?
Generally developers are good about checking with the wider developer community about possibly incompatible changes. And given the link I posted above I don't consider this change to have "crept" in.
On Fri, 28 May 2010 20:31:02 -0400 Steve Holden steve@holdenweb.com wrote:
I think it shows how developers can "get worked over" if they are insufficiently vigilant.
- I completely agree, and adduce as evidence the fact that something
like this always seems to happen when the rule is broken;
Well it's true that the change may have been unfortunate (this is the second bug report we get about it, the first one was from Holger Krekel IIRC), its exceptional nature had also been discussed on this mailing-list, and supported by Guido. It is not the product of oversight.
What it does teach us is that Python 3.1 sees some real use, and we have entered a phase where backwards compatibility will become as important as it was in the 2.x line.
- 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).
I think this would be worse, as in "even more confusing". We would have a 3.1.2 with changed behaviour, a 3.1.2.1 with reverted behaviour, and a 3.2 with changed behaviour again. Now that we have inflicted this pain on our users, let's not inflict more pain on them.
Regards
Antoine.
On 5/29/2010 6:39 AM, Antoine Pitrou wrote:
It is not the product of oversight.
I am actually glad, in a sense, that it was not casual whim. ;-) I do not like the change, since it moves streams back further away from Python's sequence model, but I withdraw the request for reversion in 3.1.3.
I will add further comments on the docs to the issue.
What it does teach us is that Python 3.1 sees some real use,
It is an odd 'coincidence' that the method changed was one of the only two stdlib methods I have used so far used directly. But with enough users, such happens.
What it teaches *me* is that before I install another release, I should, as planned, automate the running of all module tests together so I can easily test everything before and after a new installation.
When I do release sample chapters and code, I will try to remember to specify the version and platform I tested with.
we have entered a phase where backwards compatibility will become as important as it was in the 2.x line.
I have assumed that there might be a few stdlib API tweeks in 3.2 -- and that they would be well announced.
Terry Jan Reedy
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1
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
- the supposed bugfix-only policy should really be the policy;
- 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.
+1 on #1 as the general policy.
I don't have enough skin in the game of the 3.1.x world to have an opinion about this specific breakage, but I have certainly seen other examples in the 2.x releases, where such a resolution was the appropriate outcome.
Tres. - -- =================================================================== Tres Seaver +1 540-429-0999 tseaver@palladion.com Palladion Software "Excellence by Design" http://palladion.com
On 29/05/10 09:03, Terry Reedy wrote:
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
As Benjamin noted, that change was discussed on python-dev and actually made at Guido's direction.
So, I think
- the supposed bugfix-only policy should really be the policy;
- 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.
The bugfix-only policy remains in place, but there are corner cases (such as this one) where the definition of what is and isn't a bug gets fuzzy and we need to make a judgment call as to whether to fix them or not. In particular, fixing bugs often runs the risk of breaking existing workarounds for those bugs.
The decimal module, for example, has a standing policy to treat deviations from the standard as bugs, and this may lead to changes in the module if the standard is updated between two releases.
This specific change was discussed on python-dev and the chance of breaking existing 3.1 code was deemed preferable to retaining semantics that were seen as broken, so I would be against reverting it.
However, it may be worth modifying the policy to ensure that such exceptional bug fixes be mentioned prominently in the release notes and on the download page for that maintenance release.
Regards, Nick.
On 5/28/2010 11:41 PM, Nick Coghlan wrote:
However, it may be worth modifying the policy to ensure that such exceptional bug fixes be mentioned prominently in the release notes and on the download page for that maintenance release.
A sentence like "The behavior of it.X.truncate has been intentionally changed from ... to ... .", if I read and cognized it, would have helped me, in this case, to the problem and fix much more quickly.
Is it possible with svn or hg to get a list of the commits that changed version x to version y?
Would is not be possible to get a diff between at least the .rst versions of the docs for version x and version y?
Terry Jan Reedy
Is it possible with svn or hg to get a list of the commits that changed version x to version y?
A regular "svn log" on the maintenance branch will give you all the changes. You'll recognize from the checkin messages when the previous release was.
Would is not be possible to get a diff between at least the .rst versions of the docs for version x and version y?
That's most certainly possible, using "svn diff -rX:Y".
Regards, Martin
On 29/05/10 09:03, Terry Reedy wrote:
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
For the record, I have added links to Guido's python-dev post to both of these tracker issues.
Cheers, Nick.
participants (7)
-
"Martin v. Löwis" -
Antoine Pitrou -
Benjamin Peterson -
Nick Coghlan -
Steve Holden -
Terry Reedy -
Tres Seaver