This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: Minor clarification in devguide
Type: enhancement Stage: resolved
Components: Devguide Versions:
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: ezio.melotti Nosy List: eric.araujo, ezio.melotti, nailor, petri.lehtinen, python-dev, sandro.tosi, terry.reedy, tshepang, zormit
Priority: normal Keywords: needs review, patch

Created on 2011-06-09 15:45 by eric.araujo, last changed 2022-04-11 14:57 by admin. This issue is now closed.

Files
File name Uploaded Description Edit
clarify-bwcompat-devguide.diff eric.araujo, 2011-06-09 15:45
clarify-bwcompat-devguide_v2.diff nailor, 2011-10-18 08:50
devguide-patch.diff zormit, 2014-01-27 23:23
Messages (19)
msg137994 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-06-09 15:45
I found the wording of one line of the devguide strange and changed it IMO for the better.  Please review.
msg138778 - (view) Author: Petri Lehtinen (petri.lehtinen) * (Python committer) Date: 2011-06-21 10:40
New semantics may also be something else than new classes or functions. New optional function arguments exposing new functionality, for example.
msg138924 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-06-24 11:55
What about this: (this obviously does not apply to new classes, functions or arguments)
msg139079 - (view) Author: Sandro Tosi (sandro.tosi) * (Python committer) Date: 2011-06-25 15:01
(this obviously does not apply to new classes, functions or *optional* arguments) ?
msg139113 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-06-25 20:07
Good idea.  So, any -1 on this:

(this obviously does not apply to new classes or functions, or new optional arguments)
msg139120 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2011-06-25 21:25
The parenthetical comment is a complete sentence, and no longer trivial. I would separate it and write it more simply as
"... their code. (This obviously does not apply to new classes, functions, or optional arguments.)"
msg139284 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-06-27 14:38
Okay for a new sentence.  I think repeating new is clearer:

(This obviously does not apply to new classes or functions, or new optional arguments.)
msg145786 - (view) Author: Jyrki Pulliainen (nailor) * Date: 2011-10-18 08:50
Updated the existing patch with the new wording
msg145825 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-10-18 16:02
I like it.  Terry, objections?
msg145828 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2011-10-18 16:07
LGTM.

(Actually you can still break someone's code by introducing new functions/classes, in case they get imported with 'from mod import *' and override some local function/class with the same name -- but this is such an obscure case that doesn't deserve to be mentioned (and 'import *' is bad practice anyway).)
msg145842 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2011-10-18 17:33
To be more exact, "optional arguments" should be more extended to "optional arguments whose default maintains the existing behavior"
msg145988 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2011-10-19 22:59
I don't think we need to mention that.  Actually the tone of the whole paragraph could be relaxed a bit, because it first says that "any change **will** break code" (which is not true), except "new semantic, obviously" (which is not true either).

The whole sentence could also be dropped altogether IMHO.
"""
Basically just put yourself in the shoes of someone whose code will be broken by a change to pre-existing semantics.
"""
is already clear enough, and it could be rephrased to
"""
Basically just put yourself in the shoes of someone whose code will be broken by the change(s) introduced by the patch.
"""
to avoid talking about 'semantics'.
msg146078 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-10-21 13:26
This is the wording I committed:

(This obviously does not apply to new classes or functions; new arguments should be optional and have default values which maintain the existing behavior.)

Should I push or should I delete the changeset?
msg146138 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2011-10-21 21:38
Ezio's comment got me to reread the entire paragraph. I do not like it. 'Having you think' is wrong; 'Basically just' is unneeded; 'guaranteed' is hyperbole; and the paragraph is otherwise repetitive, vague, and pretty useless. For most issues "the core developer who eventually handles your patch will make the final call on whether something is acceptable" is not exactly true and misses the point that we have clearly defined policies that all core developers follow. Here is a suggested replacement that says what is actually acceptable for what versions.

"Second, follow our backwards-compatibility and upgrade policies. New parameters (whose default is the current behavior), functions, and methods may be accepted, but only for a future x.y version. New classes, modules, and syntax (including keywords) get increasingly severe scrutiny and require discussion on the python-dev list. Bug fixes that make behavior better match the documented intention are nearly always accepted for current releases. So are fixes for mistakes and sufficiently bad wording in the documents. Changes away from the current documented behavior are only occasionally accepted and only for future releases. Since they nearly always require at least a few people to update their code, they require special consideration, including a python-dev discussion, and a deprecation process."
msg146140 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2011-10-21 21:54
That's a bit heavy in my opinion.  I don't think it's necessary to define in detail what "backward-compatibile" means, it's probably enough to say that whatever code might be running before the patch should keep running fine even after.  Bug fixes can change the behavior -- but only if the current behavior is clearly wrong.

In addition you might want to define the meaning of "features", "bug fixes", and "security fixes", mention what releases accept what, say that doc fixes are usually fine in bug fix releases too, and possibly document the deprecation process.  But maybe this is getting out of the initial scope of the issue :)
msg146291 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2011-10-24 10:45
PEP 387 explains the rules about backward compatibility.  The paragraph could just link to that.
msg209487 - (view) Author: Moritz Neeb (zormit) * Date: 2014-01-27 23:23
Tried to summarize the previous discussion and generate a compromise here. Patch attached.
msg210809 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2014-02-10 08:29
New changeset 4ce6bfb27267 by Ezio Melotti in branch 'default':
#12296: clarify paragraph about backward-compatibility.  Patch by Moritz Neeb, Jyrki Pulliainen, and Éric Araujo.
http://hg.python.org/devguide/rev/4ce6bfb27267
msg210810 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2014-02-10 08:30
Fixed, thanks for the patches!
History
Date User Action Args
2022-04-11 14:57:18adminsetgithub: 56505
2014-02-10 08:30:22ezio.melottisetstatus: open -> closed
versions: - 3rd party
messages: + msg210810

assignee: eric.araujo -> ezio.melotti
resolution: fixed
stage: patch review -> resolved
2014-02-10 08:29:01python-devsetnosy: + python-dev
messages: + msg210809
2014-01-27 23:23:45zormitsetfiles: + devguide-patch.diff
nosy: + zormit
messages: + msg209487

2012-09-23 13:17:29ezio.melottisettype: enhancement
2012-01-11 10:02:18tshepangsetnosy: + tshepang
2011-10-24 10:45:41ezio.melottisetmessages: + msg146291
2011-10-21 21:54:57ezio.melottisetmessages: + msg146140
2011-10-21 21:38:51terry.reedysetmessages: + msg146138
2011-10-21 13:26:34eric.araujosetmessages: + msg146078
2011-10-19 22:59:06ezio.melottisetmessages: + msg145988
2011-10-18 17:33:04terry.reedysetmessages: + msg145842
2011-10-18 16:07:52ezio.melottisetnosy: + ezio.melotti
messages: + msg145828
2011-10-18 16:02:05eric.araujosetmessages: + msg145825
2011-10-18 08:50:45nailorsetfiles: + clarify-bwcompat-devguide_v2.diff
nosy: + nailor
messages: + msg145786

2011-06-27 14:38:20eric.araujosetmessages: + msg139284
2011-06-25 21:25:28terry.reedysetnosy: + terry.reedy
messages: + msg139120
2011-06-25 20:07:20eric.araujosetmessages: + msg139113
2011-06-25 15:01:24sandro.tosisetnosy: + sandro.tosi
messages: + msg139079
2011-06-24 11:55:38eric.araujosetmessages: + msg138924
2011-06-21 10:40:54petri.lehtinensetnosy: + petri.lehtinen
messages: + msg138778
2011-06-09 15:45:26eric.araujocreate