diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 636f99e47e3..dce854e3a68 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -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 +`_ +and `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 +`__ for static +typing, or `Packaging Discourse `__ +for packaging), or `open an issue `__. + + 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: ``. +When adding or modifying a PEP, please include the PEP number in the commit +summary and pull request title. For example, ``PEP NNN: ``. +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:``. 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. diff --git a/pep-0001.txt b/pep-0001.txt index 8aeccfbdf39..fe7284df381 100644 --- a/pep-0001.txt +++ b/pep-0001.txt @@ -458,19 +458,25 @@ 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 +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 +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 +changes to development practices and other details. The precise process +followed in these cases will depend on the nature and purpose of the PEP +in question. + +Occasionally, a Deferred or even a Withdrawn PEP may be resurrected +with major updates, but it is often better to just propose a new one. What belongs in a successful PEP? @@ -693,23 +699,21 @@ Alternatively, all support files may be placed in a subdirectory called are no constraints on the names used in files. -Reporting PEP Bugs, or Submitting PEP Updates -============================================= - -How you report a bug, or submit a PEP update depends on several -factors, such as the maturity of the PEP, the preferences of the PEP -author, and the nature of your comments. For the early draft stages -of the PEP, it's probably best to send your comments and changes -directly to the PEP author. For more mature, or finished PEPs you may -want to submit corrections as a `GitHub issue`_ or `GitHub pull request`_ so that -your changes don't get lost. +Changing Existing PEPs +====================== -When in doubt about where to send your changes, please check first -with the PEP author and/or a PEP editor. +Draft PEPs are freely open for discussion and proposed modification, at the +discretion of the authors, until submitted to the Steering Council or +PEP-Delegate for review and resolution. Substantive content changes should +generally be first proposed on the PEP's discussion thread listed in its +``Discussions-To`` header, while copyedits and corrections can be submitted +as a `GitHub issue`_ or `GitHub pull request`_. +PEP authors with write access to the PEP repository can update the PEPs +themselves by using ``git push`` or a GitHub PR to submit their changes. +For guidance on modifying other PEPs, consult the `PEP Maintenance`_ section. -PEP authors with write access to the PEP repository can update the -PEPs themselves by using "git push" or the GitHub PR interface to submit their -changes. +See the `Contributing Guide`_ for additional details, and when in doubt, +please check first with the PEP author and/or a PEP editor. Transferring PEP Ownership @@ -867,6 +871,14 @@ Footnotes .. _Packaging category: https://discuss.python.org/c/packaging/ +.. _Language Reference: https://docs.python.org/3/reference/index.html + +.. _Library Reference: https://docs.python.org/3/library/index.html + +.. _PyPA Specifications: https://packaging.python.org/en/latest/specifications/ + +.. _Contributing Guide: https://github.com/python/peps/blob/main/CONTRIBUTING.rst + Copyright =========