Skip to content
Merged
41 changes: 30 additions & 11 deletions CONTRIBUTING.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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:``.


Sign the CLA
Expand Down Expand Up @@ -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.
61 changes: 37 additions & 24 deletions pep-0001.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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
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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Active Informational and Process PEPs may be updated over time to reflect
Active, Informational and Process PEPs may be updated over time to reflect

Copy link
Member Author

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.

Suggested change
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

Suggested change
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?

Suggested change
Active Informational and Process PEPs may be updated over time to reflect
Active (Informational and Process) PEPs may be updated over time to reflect

Copy link
Member

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.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, I applied that

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`_).
Copy link
Member

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.

Copy link
Member Author

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

Suggested change
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.

Copy link
Member

@AA-Turner AA-Turner Mar 14, 2022

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

Copy link
Member Author

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 ?

Copy link
Member

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.

Copy link
Member Author

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.

Suggested change
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.


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?
Expand Down Expand Up @@ -693,23 +700,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
Expand Down Expand Up @@ -867,6 +872,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
=========
Expand Down