iSharkFly-Open
/
python-peps
mirror of https://github.com/python/peps.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Meta: Clearly document current guidance for changing existing PEPs (#2378) 

* Meta: Document expectations for changing existing PEPs in contrib guide

* Meta: Clarify commit message/PR title prefixes in contrib guide

* Meta: Further improve change policy in CG per Jelle's feedback

* Meta: Reduce verbosity and perscriptiveness of changes section in CG

* Meta: Move more general/normative PEP modification guidance to PEP 1

* Meta: Further revise PEP change guidance to reflect current reality

* Meta: Update, simplify and consolidate guidance on changing PEPs

* PEP 1: Remove sentence explicitly discussing changing governance PEPs
This commit is contained in:
CAM Gerlach 2022-04-06 18:21:47 -05:00 committed by GitHub
parent f73a0aa1ca
commit 63d802d093
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 66 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
CONTRIBUTING.rst
View File

@ -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/typing-sig@python.org/>`__ 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:``.
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.

60
pep-0001.txt
View File

@ -460,19 +460,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?
@ -699,23 +705,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
=============================================
Changing Existing PEPs
======================
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.
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.
When in doubt about where to send your changes, please check first
with the PEP author and/or a PEP editor.
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
@ -858,6 +862,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
=========