-
-
Notifications
You must be signed in to change notification settings - Fork 1.7k
Meta: Clearly document current guidance for changing existing PEPs #2378
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from 7 commits
74a3060
0e35681
3f49e45
6cafac8
0f278da
ccf9770
3968613
58e7055
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -18,12 +18,39 @@ first in an appropriate venue, drafting a PEP and gathering feedback, and | |
| developing at least a prototype reference implementation of your idea. | ||
|
|
||
|
|
||
| Contributing changes to existing PEPs | ||
| ------------------------------------- | ||
|
|
||
| In general, most non-Draft/Active PEPs are considered to be historical | ||
| documents rather than living specifications or documentation. Major changes to | ||
| their core content usually require a new PEP, while smaller modifications may | ||
| or may not be appropriate, depending on the PEP's status. See `PEP Maintenance | ||
| <https://peps.python.org/pep-0001/#pep-maintenance>`_ | ||
| and `Changing Existing PEPs | ||
| <https://peps.python.org/pep-0001/#changing-existing-peps>`_ in PEP 1 for more. | ||
|
|
||
| Copyediting and proofreading Draft and Active PEPs is welcome (subject to | ||
| review by the PEP author), and can be done via pull request to this repo. | ||
| Substantive content changes should first be proposed on PEP discussion threads. | ||
| We do advise against PRs that simply mass-correct minor typos on older PEPs | ||
| which don't significantly impair meaning and understanding. | ||
|
|
||
| If you're still unsure, we encourage you to reach out first before opening a | ||
| PR here. For example, you could contact the PEP author(s), propose your idea in | ||
| a discussion venue appropriate to the PEP (such as `Typing-SIG | ||
| <https://mail.python.org/archives/list/[email protected]/>`__ for static | ||
| typing, or `Packaging Discourse <https://discuss.python.org/c/packaging/>`__ | ||
| for packaging), or `open an issue <https://github.com/python/peps/issues>`__. | ||
|
|
||
|
|
||
| Commit messages and PR titles | ||
| ----------------------------- | ||
|
|
||
| When adding or modifying a PEP, please always include the PEP number in the | ||
| commit summary and pull request title. | ||
| For example, ``PEP NNN: <summary of changes>``. | ||
| When adding or modifying a PEP, please include the PEP number in the commit | ||
| summary and pull request title. For example, ``PEP NNN: <summary of changes>``. | ||
| Likewise, prefix rendering infrastructure changes with ``Infra:``, linting | ||
| alterations with ``Lint:`` and other non-PEP meta changes, such as updates to | ||
| the Readme/Contributing Guide, issue/PR template, etc., with ``Meta:``. | ||
CAM-Gerlach marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
|
|
||
| Sign the CLA | ||
|
|
@@ -122,11 +149,3 @@ or against all files with | |
| .. code-block:: bash | ||
|
|
||
| pre-commit run --all-files --hook-stage manual codespell | ||
|
|
||
| **Note**: While fixing spelling mistakes as part of more substantive | ||
| copyediting and proofreading of draft and active PEPs is okay, | ||
| we generally advise against PRs that simply mass-correct minor typos on | ||
| older PEPs that don't significantly impair meaning and understanding, | ||
| as these tend to create a fairly high level of noise and churn for | ||
| PEP readers, authors and editors relative to the amount of practical value | ||
| they provide. | ||
| Original file line number | Diff line number | Diff line change | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
|
@@ -458,19 +458,26 @@ if they are never meant to be completed. E.g. :pep:`1` (this PEP). | |||||||||||||||||
| PEP Maintenance | ||||||||||||||||||
| --------------- | ||||||||||||||||||
|
|
||||||||||||||||||
| In general, Standards track PEPs are no longer modified after they have | ||||||||||||||||||
| reached the Final state. Once a PEP has been completed, the Language and | ||||||||||||||||||
| Standard Library References become the formal documentation of the expected | ||||||||||||||||||
| behavior. | ||||||||||||||||||
| In general, PEPs are no longer substantially modified after they have reached | ||||||||||||||||||
CAM-Gerlach marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||||||||||||
| the Accepted, Final, Rejected or Superseded state. Once resolution is reached, | ||||||||||||||||||
| a PEP is considered a historical document rather than a living specification. | ||||||||||||||||||
| Formal documentation of the expected behavior should be maintained elsewhere, | ||||||||||||||||||
| such as the `Language Reference`_ for core features, the `Library Reference`_ | ||||||||||||||||||
| for standard library modules or the `PyPA Specifications`_ for packaging. | ||||||||||||||||||
|
|
||||||||||||||||||
| If changes based on implementation experience and user feedback are made to | ||||||||||||||||||
| Standards track PEPs while in the Accepted or Provisional State, those changes | ||||||||||||||||||
| should be noted in the PEP, such that the PEP accurately describes the state of | ||||||||||||||||||
| Standards track PEPs while in the Provisional or (with SC approval) Accepted | ||||||||||||||||||
CAM-Gerlach marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||||||||||||||
| state, they should be noted in the PEP, such that the PEP accurately describes | ||||||||||||||||||
| the implementation at the point where it is marked Final. | ||||||||||||||||||
|
|
||||||||||||||||||
| Informational and Process PEPs may be updated over time to reflect changes | ||||||||||||||||||
| to development practices and other details. The precise process followed in | ||||||||||||||||||
| these cases will depend on the nature and purpose of the PEP being updated. | ||||||||||||||||||
| Active Informational and Process PEPs may be updated over time to reflect | ||||||||||||||||||
|
||||||||||||||||||
| Active Informational and Process PEPs may be updated over time to reflect | |
| Active, Informational and Process PEPs may be updated over time to reflect |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Actually, the intended syntax is Active (Informational and Process) PEPs, not (Active, Informational and Process) PEPs as the above change would imply. Any suggestions to make that clearer (as that obviously wasn't what came across)? E.g.
| Active Informational and Process PEPs may be updated over time to reflect | |
| Active-status Informational and Process PEPs may be updated over time to reflect |
or
| Active Informational and Process PEPs may be updated over time to reflect | |
| Informational and Process PEPs that are Active may be updated over time to reflect |
or even as a literal parenthetical?
| Active Informational and Process PEPs may be updated over time to reflect | |
| Active (Informational and Process) PEPs may be updated over time to reflect |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The last one looks clearest to me.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks, I applied that
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Again, is this captured elsewhere to your satisfaction? If so the sentence starting "Substantive" can be removed.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I did some searching (before and now) and I couldn't find anywhere else that explicitly mentioned this. With how long PEP 1 is, it is not impossible that I missed it, but at least it didn't appear to be anywhere I could think to find it, and this seems to be the most logical place to put it.
We could also modify this to say
| being updated. Substantive changes to governance PEPs must be reviewed by the | |
| Steering Council (by opening a `Steering Council issue`_). | |
| being updated. Substantive changes to Active Process PEPs must be | |
| reviewed by the Steering Council (by opening a `Steering Council issue`_). |
since that more clearly defines what PEPs must have this approval, since "governance PEPs" are not so well defined.
To note, as I've noticed previously, PEP 13 is inexplicably listed as an Informational PEP rather than a Process PEP, despite it being the Meta/Process PEP of all Process PEPs as it defines the "process" by which the Python community governs itself and in turn decides on the PEP process, and is thus the most immutable of them all.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Your suggested wording looks good (although, I would actually interpret "governance PEPs" as just 13 and the 8000 series, so perhaps it would be useful to check what the Council care about enough to add to their workload!)
A
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Any thoughts on this @brettcannon ?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The SC cannot unilaterally change PEP 13. The procedure to change PEP 13 is described in the PEP itself. The same goes for the PyPA governance PEP for example.
IMO the previous wording is enough here, no addition about the SC is necessary.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Right, but this is about Active Process PEPs in general, not anything specific to one PEP, which is what my suggestion above changes it to be more clear on (and, inexplicably, PEP 13 is listed as a mere "Informational" PEP rather than a "Process" PEP, so technically it wouldn't apply to PEP 13 at all, albeit almost certainly due to an oversight). That said, the previous sentence says "The precise process followed in these cases will depend on the nature and purpose of the PEP being updated.", so if there's no need to explicitly specify this here, I'll just remove it.
| being updated. Substantive changes to governance PEPs must be reviewed by the | |
| Steering Council (by opening a `Steering Council issue`_). | |
| in question. |
To note, I originally included another clause specifying that beyond SC review, any guidance in the PEP in question [e.g. PEP 13, 609, etc] also needed to be followed when updating it, but I had elided it in the current version for brevity, due to concerns about the original proposed wording being too verbose and overly specific.
Uh oh!
There was an error while loading. Please reload this page.