diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 59819579f7e2..c88b9bd64477 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -21,62 +21,34 @@ developing at least a prototype reference implementation of your idea. Contributing changes to existing PEPs ------------------------------------- -In general, PEPs that are not marked as Draft, Active or Provisional 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: - -* **Rejected**, **Deferred**, **Withdrawn** and **Superceded** PEPs should - usually only be modified when necessary to correct technical issues with - the syntax. Occasionally, a Deferred or even Withdrawn PEP may be resurrected - with major updates, but it is often better to just propose a new one. - -* **Final** PEPs are considered complete, though small fixes to unintentional - errors in the document that impair understanding may be accepted. - -* **Accepted** PEPs may be updated to reflect minor details of the final - implementation, but changes to the specification should be avoided. - -* **Provisional** PEPs can be incrementally modified if needed, though rewrites - and compatibility breakage are discouraged unless absolutely necessary. - -* **Active** PEPs can and should be updated whenever the information described - changes. Substantive changes to governance PEPs should be reviewed by the - Steering Council (by opening an - `issue `__ in the SC repo) - and are subject to any further conditions stated in the PEP itself. - -* **Draft** PEPs are freely open for discussion and proposed modification - until submitted to the Steering Council or PEP-Delegate. - Copyediting, formatting and proofreading can be opened here as pull requests, - while more substantive content changes should generally be first proposed - on the PEP's discussion thread listed in its ``Discussions-To`` header. - -Also, while fixing spelling and formatting issues as part of more substantive -copyediting and proofreading of draft and active PEPs is encouraged, -we generally advise against PRs that simply mass-correct minor typos -that don't significantly impair meaning and understanding. - -If you're 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 (e.g. -`Typing-SIG `__ -for static typing, or the `Packaging Discourse -`__ for packaging), and/or -open an `issue on this repo `__. +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 1 +`__ for more. + +Copyediting and proofreading Draft and Active PEPs (including fixing spelling +and formatting issues) is welcomed, and can be done via pull request to this +repo, though we generally advise against PRs that simply mass-correct minor +typos on older PEPs which don't significantly impair meaning and understanding. +Substantive content changes should first be proposed on PEP discussion threads. + +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: ``. -Likewise, prefix rendering infrastructure changes with ``Infra:``, -linting-related alterations with ``Lint:`` and other non-PEP meta changes, -such as updates to the Readme/Contributing Guide, issue/PR template, etc., -with ``Meta:``. +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 diff --git a/pep-0001.txt b/pep-0001.txt index 8aeccfbdf396..1f17e4847812 100644 --- a/pep-0001.txt +++ b/pep-0001.txt @@ -458,19 +458,30 @@ 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 Final, Rejected or Superseded state. Once a PEP has been completed, +it is considered to be a historical document rather than living specifications. +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 +Standards track PEPs while in the Accepted or Provisional state, they should be noted in the PEP, such that the PEP accurately describes the state of 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 +being updated. Substantive changes to governance PEPs must be reviewed by the +Steering Council (by opening a `Steering Council issue`_). + +Draft PEPs are freely open for discussion and proposed modification 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. +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? @@ -867,6 +878,13 @@ 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/ + + Copyright =========