[issue16574] clarify policy on updates to final peps
New submission from Chris Jerdonek: This issue is to clarify the policy in PEP 1 regarding non-substantive changes to PEPs in the Final state (minor clarifications, rephrasings, etc). Currently, PEP 1 says, "In general, Standards track PEPs are no longer modified after they have reached the Final state." (from http://www.python.org/dev/peps/pep-0001/#pep-maintenance ) However, others have pointed out that minor clarifications and rephrasings are in fact allowed: http://bugs.python.org/issue15990#msg176575 The updated wording should also state the policy or process regarding such changes (who is allowed to make them and whether and from whom approval is needed to make such changes, etc). ---------- assignee: docs@python components: Documentation messages: 176598 nosy: barry, chris.jerdonek, docs@python, eric.araujo, ezio.melotti, goodger, ncoghlan priority: normal severity: normal status: open title: clarify policy on updates to final peps type: enhancement _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16574> _______________________________________
Martin v. Löwis added the comment: I don't think this needs clarification. The status quo is fine. ---------- nosy: +loewis _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16574> _______________________________________
Chris Jerdonek added the comment: Are you saying that PEP 1 is correct and that Final PEPs should not be modified, or that the PEP isn't correct but that it shouldn't be modified? If the latter, for someone new it's not clear whether minor clarifications are permitted and if so, how to go about making one. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16574> _______________________________________
Éric Araujo added the comment: I think Brett edited PEP 302 a decade after its acceptance. ---------- nosy: +brett.cannon _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16574> _______________________________________
Barry A. Warsaw added the comment: On Nov 29, 2012, at 12:56 AM, Chris Jerdonek wrote:
Currently, PEP 1 says, "In general, Standards track PEPs are no longer modified after they have reached the Final state."
I agree w/mvl. This is still true, and it doesn't mean PEPs can't be modified after reaching Final state. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16574> _______________________________________
Éric Araujo added the comment: Right, “in general” is good enough to capture what we do. Chris, closing? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16574> _______________________________________
Chris Jerdonek added the comment: Okay, so in a comment to issue 15990, Ezio suggested that some clarifying changes to PEP 362 might be worth making. How would I (or someone else) go about doing that? Where would they begin? I think this recent e-mail from Nick applies: http://mail.python.org/pipermail/python-dev/2012-November/122525.html ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16574> _______________________________________
Chris Jerdonek added the comment: By the way, I don't especially care if the clarification goes in the PEP itself or not. What's more important is that it be documented *somewhere* (which could also be the devguide, for example). My interest in knowing the process is genuine. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16574> _______________________________________
Brett Cannon added the comment: Once PEPs reach their final status, I view them basically done if there is more official docs. For instance, I updated PEP 302 because the import and importlib docs were not as thorough as they are now thanks to Barry. But now that we have proper docs I don't plan to muck with PEP 302 anymore. That being said, I wouldn't object if someone chose to put the effort into updating PEP 302 in the future, I just won't. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16574> _______________________________________
Éric Araujo added the comment: I think the gist here is that “in general” is good enough, given that there is unwritten consensus about what edits are possible in the developers’ heads. Most of the time unwritten knowledge is not good, but (if I get what Martin and Barry mean correctly) for PEP rules this is fine. We don’t want an over-detailed or inflexible process. About the mail from Nick: it was talking about writing a new informational PEP, so I don’t see the link with final standards track PEPs. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16574> _______________________________________
Ezio Melotti added the comment: FTR the reason I suggested to modify PEP 362 is that we are linking to it from the docs. This means that people will go and read the PEP looking for clarifications, so the PEP should be clear. In this regard I see the PEP (or at least the relevant section) as documentation, and given that it's about an aspect of Python that is not going to change any time soon, it makes sense to get it right and keep referencing the PEP. This doesn't normally apply to most of the other PEPs, especially if what they proposed is now documented on docs.python.org. (On a side note, I now noticed that the parameter kinds are also documented in http://docs.python.org/dev/library/inspect.html#inspect.Parameter.kind, so we could link to that instead of linking to the PEP.) ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16574> _______________________________________
Chris Jerdonek added the comment:
I think the gist here is that “in general” is good enough, given that there is unwritten consensus about what edits are possible in the developers’ heads.
As I said, I'm okay with keeping the PEP as is (with "in general," etc) provided a clarification is documented elsewhere like in the devguide. What I want to avoid are, as you say, there being "unwritten" rules about changing PEPs in the Final state. (It was the general remarks about unwritten rules in Nick's e-mail that I felt were applicable.) The written rules need not be overly-detailed or inflexible so long as they give newcomers without that common understanding a leg up on what to do. It could be something as simple as "non-substantive changes to PEPs in the Final state should be treated like any other changes to the documentation" (or whatever the general process/criteria should be for such changes). ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16574> _______________________________________
Nick Coghlan added the comment: Yeah, I agree the "in general" in PEP 1 is enough of a caveat. The unwritten rules in this particular case are that if something in a PEP is important enough to be permanently referenced, then it's important enough to be part of the language spec (either the main language reference or the stdlib reference), or else it should be a versioned informational PEP that gets replaced when updated (e.g. the WSGI spec, DB-API, packaging metadata etc). There have been a few PEPs, most notably the import PEPs, where that wasn't possible because such docs didn't exist, and documenting the existing system would have taken so many caveats that nobody was ever willing to do it. So PEP 302 became the de facto documentation for the modular part of the import system. Now that we have real docs in the language reference for 3.3+, PEP 302 will finally be able fade into irrelevance as a normative document. Now that the import case is resolved, I can't think of any Final PEPs where we're likely to break the rules any more, unless it's just to update them with a link to the normative docs. ---------- components: +Devguide -Documentation _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16574> _______________________________________
Martin v. Löwis added the comment: 1. I think that the PEP author has the final say as to what specific text goes into the PEP. Contributors shouldn't modify other people's PEP without consent from the author(s). 2. This holds for all stages, including the Final stage. If the PEP author wants to clarify/elaborate, they may; if they don't feel like it, they don't need to (even if the implementation later deviates from the PEP). 3. We should avoid to refer to PEPs for specification in the documentation. If there is a documentation issue proposing to update the PEP because it's referenced from the documentation, the right action should be to stop referencing it, and to incorporate the PEP text into the documentation (as needed). 4. Even without the "In general" cop-out, I think the PEP is fine as written. It doesn't say (as Chris suggested in msg176603) that Final PEPs *should not* be modified, but that they *are not* modified. PEP 1 describes an ideal process, nobody should be surprised that the real world does not always follow the ideal. My biggest complaint about PEP 1 not being followed is the "PEP authors are responsible for collecting community feedback" requirement. Editing Final PEPs is absolutely no concern to me, since the PEP has already achieved what it was written for. So even if this rule was regularly ignored, I'd still continue to be a happy contributor to Python. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16574> _______________________________________
Barry A. Warsaw added the comment: On Nov 29, 2012, at 12:16 PM, Martin v. Löwis wrote:
1. I think that the PEP author has the final say as to what specific text goes into the PEP. Contributors shouldn't modify other people's PEP without consent from the author(s).
2. This holds for all stages, including the Final stage. If the PEP author wants to clarify/elaborate, they may; if they don't feel like it, they don't need to (even if the implementation later deviates from the PEP).
3. We should avoid to refer to PEPs for specification in the documentation. If there is a documentation issue proposing to update the PEP because it's referenced from the documentation, the right action should be to stop referencing it, and to incorporate the PEP text into the documentation (as needed).
4. Even without the "In general" cop-out, I think the PEP is fine as written. It doesn't say (as Chris suggested in msg176603) that Final PEPs *should not* be modified, but that they *are not* modified. PEP 1 describes an ideal process, nobody should be surprised that the real world does not always follow the ideal. My biggest complaint about PEP 1 not being followed is the "PEP authors are responsible for collecting community feedback" requirement. Editing Final PEPs is absolutely no concern to me, since the PEP has already achieved what it was written for. So even if this rule was regularly ignored, I'd still continue to be a happy contributor to Python.
I agree with all of this. Occasionally PEPs themselves may leave open the possibility for future additions or changes. Release schedule PEPs are one example. PEP 425 is another example, where the PEP seems like the logical choice for registering future tags. All this is fine IMHO, and doesn't need any further clarification in PEP 1. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16574> _______________________________________
Chris Jerdonek added the comment: Thanks for the feedback. I will post here a devguide patch to include some of this information in the devguide. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16574> _______________________________________
Terry J. Reedy added the comment: With respect to editing final peps, I think this issue should be closed. The current PEP 1 statement accurately describes what we do, which is that in general we do not edit final peps. Moreover, Chris has not submitted a patch and I doubt anyone else knows what he thought he might add or where, The only related question I have is in relation to Martin's point 3. https://docs.python.org/devguide/documenting.html#id3 has the following: pep A reference to a Python Enhancement Proposal. This generates appropriate index entries. The text “PEP number” is generated; in the HTML output, this text is a hyperlink to an online copy of the specified PEP. Should we add something like "Such links should not be a substitute for properly documenting the language in the manuals." ---------- nosy: +terry.reedy _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16574> _______________________________________
Carol Willing added the comment: This patch should close this languishing devguide issue. This patch adds wording suggested by Terry Reedy re: pep documentation reference to section 7.4.5 Inline markup (https://docs.python.org/devguide/documenting.html#id3). The devguide covers the pep process and PEP 1 in section 20.1.2 (https://docs.python.org/devguide/langchanges.html?highlight=pep#pep-process). ---------- keywords: +patch nosy: +willingc stage: -> patch review Added file: http://bugs.python.org/file39101/iss16574.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16574> _______________________________________
Éric Araujo added the comment: Patch LGTM. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16574> _______________________________________
Changes by Carol Willing <willingc@willingconsulting.com>: ---------- stage: patch review -> commit review _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16574> _______________________________________
Roundup Robot added the comment: New changeset 0c4006b7c7ff by Berker Peksag in branch 'default': Issue #16574: Clarify that once a PEP has implemented, it needs be https://hg.python.org/devguide/rev/0c4006b7c7ff ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16574> _______________________________________
Berker Peksag added the comment: Thanks! ---------- nosy: +berker.peksag resolution: -> fixed stage: commit review -> resolved status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16574> _______________________________________
participants (11)
-
Barry A. Warsaw -
Berker Peksag
-
Brett Cannon
-
Carol Willing
-
Chris Jerdonek
-
Ezio Melotti
-
Martin v. Löwis
-
Nick Coghlan
-
Roundup Robot
-
Terry J. Reedy
-
Éric Araujo