Skip to content

PEP 1, 12 and template: update style #5082

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.

Sign up for GitHub

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

Open
hugovk wants to merge 3 commits into
base: main
Choose a base branch
from
+81 −81
Open

PEP 1, 12 and template: update style #5082

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
8c5f467
Use sentence case for headers
hugovk Aug 6, 2026
43de40a
Avoid Latin abbreviations
hugovk Aug 6, 2026
9b51b21
ReStructuredText -> reStructuredText
hugovk Aug 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
84 changes: 42 additions & 42 deletions peps/pep-0001.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ commands for retrieving older revisions, and can also be browsed
`on GitHub <https://github.com/python/peps>`__.


PEP Audience
PEP audience

@warsaw warsaw Aug 6, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Changing PEP 1's headers is fine in isolation since it's not a template, but ... is it worth it? We have so many all-caps headers in the PEPs, I'm not so sure.

============

The typical primary audience for PEPs are the core developers of the CPython
Expand All @@ -43,7 +43,7 @@ to manage complex design coordination problems that require collaboration across
multiple projects.


PEP Types
PEP types
=========

There are three kinds of PEP:
Expand Down Expand Up @@ -73,7 +73,7 @@ There are three kinds of PEP:
Any meta-PEP is also considered a Process PEP.


PEP Workflow
PEP workflow
============

Python's Steering Council
Expand All @@ -85,7 +85,7 @@ in :pep:`13`, in their role as the final authorities on whether or not PEPs
will be accepted or rejected.


Python's Core Developers
Python's core developers
------------------------

There are several references in this PEP to "core developers". This refers to
Expand All @@ -103,12 +103,12 @@ Council's design authority derives from their election by the currently active
core developers. Now, PEP-Delegate is used in place of BDFL-Delegate.


PEP Editors
PEP editors
-----------

The PEP editors are individuals responsible for managing the administrative
and editorial aspects of the PEP workflow (e.g. assigning PEP numbers and
changing their status). See `PEP Editor Responsibilities & Workflow`_ for
and editorial aspects of the PEP workflow (for example, assigning PEP numbers and
changing their status). See `PEP editor responsibilities & workflow`_ for
details.

PEP editorship is by invitation of the current editors, and they can be
Expand Down Expand Up @@ -163,7 +163,7 @@ Submitting a PEP
Following the above initial discussion, the workflow varies based on whether
any of the PEP's co-authors are core developers. If one or more of the PEP's
co-authors are core developers, they are responsible for following the process
outlined below. Otherwise (i.e. none of the co-authors are core developers),
outlined below. Otherwise (when none of the co-authors are core developers),
then the PEP author(s) will need to find a sponsor for the PEP.

Ideally, a core developer sponsor is identified, but non-core sponsors may also
Expand Down Expand Up @@ -193,7 +193,7 @@ The standard PEP workflow is:

* In the "Type:" header field, enter "Standards Track",
"Informational", or "Process" as appropriate, and for the "Status:"
field enter "Draft". For full details, see `PEP Header Preamble`_.
field enter "Draft". For full details, see `PEP header preamble`_.

* Update `.github/CODEOWNERS`_ such that any co-author(s) or sponsors
with write access to the `PEP repository`_ are listed for your new file.
Expand All @@ -210,7 +210,7 @@ The standard PEP workflow is:
* It is sound and complete. The ideas must make technical sense. The
editors do not consider whether they seem likely to be accepted.
* The title accurately describes the content.
* The PEP's language (spelling, grammar, sentence structure, etc.)
* The PEP's language (spelling, grammar, sentence structure, and so on).
and code style (examples should match :pep:`7` & :pep:`8`) should be

@StanFromIreland StanFromIreland Aug 11, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Along with Latin abbreviations, I suggest expanding ampersands in prose.

correct and conformant. The PEP text will be automatically checked for
correct reStructuredText formatting when the pull request is submitted.
Expand Down Expand Up @@ -240,7 +240,7 @@ during the approval phase, and are the final arbiter of a draft's PEP-ability.
Developers with write access to the `PEP repository`_ may claim PEP
numbers directly by creating and committing a new PEP. When doing so, the
developer must handle the tasks that would normally be taken care of by the
PEP editors (see `PEP Editor Responsibilities & Workflow`_). This includes
PEP editors (see `PEP editor responsibilities & workflow`_). This includes
ensuring the initial version meets the expected standards for submitting a
PEP. Alternately, even developers should submit PEPs via pull request.
When doing so, you are generally expected to handle the process yourself;
Expand Down Expand Up @@ -321,7 +321,7 @@ are a critical part of what the Steering Council or PEP-Delegate will
consider when reviewing the PEP.


PEP Review & Resolution
PEP review & resolution
-----------------------

Once the authors have completed a PEP, they may request a review for
Expand All @@ -331,7 +331,7 @@ responsibility of the Steering Council, which is formally initiated by
opening a `Steering Council issue`_ once the authors (and sponsor, if any)
determine the PEP is ready for final review and resolution.

To expedite the process in selected cases (e.g. when a change is clearly
To expedite the process in selected cases (for example, when a change is clearly
beneficial and ready to be accepted, but the PEP hasn't been formally submitted
for review yet), the Steering Council may also initiate a PEP review, first
notifying the PEP author(s) and giving them a chance to make revisions.
Expand Down Expand Up @@ -367,7 +367,7 @@ The Steering Council will generally approve such self-nominations by default,
but may choose to decline them.
Possible reasons for the Steering Council declining a
self-nomination as PEP-Delegate include, but are not limited to, perceptions of
a potential conflict of interest (e.g. working for the same organisation as the
a potential conflict of interest (for example, working for the same organisation as the
PEP submitter), or simply considering another potential PEP-Delegate to be
more appropriate. If core developers (or other community members) have concerns
regarding the suitability of a PEP-Delegate for any given PEP, they may ask
Expand Down Expand Up @@ -420,7 +420,7 @@ PEPs may still be Rejected or Withdrawn *even after the related changes have
been included in a Python release*.

Wherever possible, it is considered preferable to reduce the scope of a proposal
to avoid the need to rely on the "Provisional" status (e.g. by deferring some
to avoid the need to rely on the "Provisional" status (for example, by deferring some
features to later PEPs), as this status can lead to version compatibility
challenges in the wider Python ecosystem. :pep:`411` provides additional details
on potential use cases for the Provisional status.
Expand Down Expand Up @@ -461,10 +461,10 @@ deprecation process (which may require a new PEP providing the rationale for
the deprecation).

Some Informational and Process PEPs may also have a status of "Active"
if they are never meant to be completed. E.g. :pep:`1` (this PEP).
if they are never meant to be completed. For example: :pep:`1` (this PEP).


PEP Maintenance
PEP maintenance
---------------

In general, PEPs are no longer substantially modified after they have reached
Expand Down Expand Up @@ -496,7 +496,7 @@ Each PEP should have the following parts/sections:
1. Preamble -- :rfc:`2822` style headers containing meta-data about the
PEP, including the PEP number, a short descriptive title (limited
to a maximum of 44 characters), the names, and optionally the
contact info for each author, etc.
contact info for each author, and so on.

2. Abstract -- a short (~200 word) description of the technical issue
being addressed.
Expand All @@ -518,24 +518,24 @@ Each PEP should have the following parts/sections:
5. Rationale -- The rationale fleshes out the specification by
describing why particular design decisions were made. It should
describe alternate designs that were considered and related work,
e.g. how the feature is supported in other languages.
for example, how the feature is supported in other languages.

The rationale should provide evidence of consensus within the
community and discuss important objections or concerns raised
during discussion.

6. Backwards Compatibility -- All PEPs that introduce backwards
6. Backwards compatibility -- All PEPs that introduce backwards
incompatibilities must include a section describing these
incompatibilities and their severity. The PEP must explain how the
author proposes to deal with these incompatibilities. PEP
submissions without a sufficient backwards compatibility treatise
may be rejected outright.

7. Security Implications -- If there are security concerns in relation
7. Security implications -- If there are security concerns in relation
to the PEP, those concerns should be explicitly written out to make
sure reviewers of the PEP are aware of them.

8. How to Teach This -- For a PEP that adds new functionality or changes
8. How to teach this -- For a PEP that adds new functionality or changes
language behavior, it is helpful to include a section on how to
teach users, new and experienced, how to apply the PEP to their
work.
Expand All @@ -544,7 +544,7 @@ Each PEP should have the following parts/sections:
changes that would help users adopt a new feature or migrate their
code to use a language change.

9. Reference Implementation -- The reference implementation must be
9. Reference implementation -- The reference implementation must be
completed before any PEP is given status "Final", but it need not
be completed before the PEP is accepted. While there is merit
to the approach of reaching consensus on the specification and
Expand All @@ -556,7 +556,7 @@ Each PEP should have the following parts/sections:
appropriate for either the Python language reference or the
standard library reference.

10. Rejected Ideas -- Throughout the discussion of a PEP, various ideas
10. Rejected ideas -- Throughout the discussion of a PEP, various ideas
will be proposed which are not accepted. Those rejected ideas should
be recorded along with the reasoning as to why they were rejected.
This both helps record the thought process behind the final version
Expand All @@ -567,7 +567,7 @@ Each PEP should have the following parts/sections:
Rationale section that is focused specifically on why certain ideas
were not ultimately pursued.

11. Open Issues -- While a PEP is in draft, ideas can come up which
11. Open issues -- While a PEP is in draft, ideas can come up which
warrant further discussion. Those ideas should be recorded so people
know that they are being thought about but do not have a concrete
resolution. This helps make sure all issues required for the PEP to be
Expand All @@ -581,10 +581,10 @@ Each PEP should have the following parts/sections:
13. Footnotes -- A collection of footnotes cited in the PEP, and
a place to list non-inline hyperlink targets.

Change History -- A summary of major changes the PEP has undergone, based on
14. Change history -- A summary of major changes the PEP has undergone, based on
discussions and feedback. Think of this as a "changelog" or "release notes"
for the PEP. In general, whenever you update the ``Post-History`` header
for major changes, add a new bullet item in newest-first (i.e. reverse
for major changes, add a new bullet item in newest-first (that is, reverse
chronological) order, using the same ``DD-MMM-YYYY`` format, with
sub-bullets summarizing the changes. You can consider linking this to the
same link as the ``Post-History`` link. This isn't mandatory, so it's left
Expand All @@ -596,7 +596,7 @@ Change History -- A summary of major changes the PEP has undergone, based on
public domain and CC0-1.0-Universal_ (see this PEP for an example).


PEP Formats and Templates
PEP formats and templates
=========================

PEPs are UTF-8 encoded text files using the reStructuredText_ format.
Expand All @@ -610,7 +610,7 @@ The PEP text files are automatically
for easier `online reading <https://peps.python.org/>`__.


PEP Header Preamble
PEP header preamble
===================

Each PEP must begin with an :rfc:`2822` style header preamble. The headers
Expand Down Expand Up @@ -673,7 +673,7 @@ reject a PEP.
*Note: The Resolution header is required for Standards Track PEPs
only. It contains a URL that should point to an email message or
other web resource where the pronouncement about
(i.e. approval or rejection of) the PEP is made.*
(approval or rejection of) the PEP is made.*

The Discussions-To header provides the URL to the current
canonical discussion thread for the PEP.
Expand All @@ -691,7 +691,7 @@ The Created header records the date that the PEP was assigned a
number, while Post-History is used to record the dates of and corresponding
URLs to the Discussions-To threads for the PEP, with the former as the
linked text, and the latter as the link target.
Both sets of dates should be in ``dd-mmm-yyyy`` format, e.g. ``14-Aug-2001``.
Both sets of dates should be in ``dd-mmm-yyyy`` format, for example, ``14-Aug-2001``.

Standards Track PEPs will typically have a Python-Version header which
indicates the version of Python that the feature will be released with.
Expand All @@ -711,20 +711,20 @@ Replaces header containing the number of the PEP that it rendered
obsolete.


Auxiliary Files
Auxiliary files
===============

PEPs may include auxiliary files such as diagrams. Such files should be
named ``pep-XXXX-Y.ext``, where "XXXX" is the PEP number, "Y" is a
serial number (starting at 1), and "ext" is replaced by the actual
file extension (e.g. "png").
file extension (for example, "png").

Alternatively, all support files may be placed in a subdirectory called
``pep-XXXX``, where "XXXX" is the PEP number. When using a subdirectory, there
are no constraints on the names used in files.


Changing Existing PEPs
Changing existing PEPs
======================

Draft PEPs are freely open for discussion and proposed modification, at the
Expand All @@ -741,7 +741,7 @@ 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
Transferring PEP ownership
==========================

It occasionally becomes necessary to transfer ownership of PEPs to a
Expand All @@ -750,7 +750,7 @@ a co-author of the transferred PEP, but that's really up to the
original author. A good reason to transfer ownership is because the
original author no longer has the time or interest in updating it or
following through with the PEP process, or has fallen off the face of
the 'net (i.e. is unreachable or not responding to email). A bad
the 'net (for example, is unreachable or not responding to email). A bad
reason to transfer ownership is because the author doesn't agree with the
direction of the PEP. One aim of the PEP process is to try to build
consensus around a PEP, but if that's not possible, an author can always
Expand All @@ -765,7 +765,7 @@ doesn't respond in a timely manner, the PEP editors will make a
unilateral decision (it's not like such decisions can't be reversed :).


PEP Editor Responsibilities & Workflow
PEP editor responsibilities & workflow
======================================

A PEP editor must be added to the ``@python/pep-editors`` group on GitHub and
Expand All @@ -788,13 +788,13 @@ For each new PEP that comes in an editor does the following:

* The title should accurately describe the content.

* The file name extension is correct (i.e. ``.rst``).
* The file name extension is ``.rst``.

* Ensure that everyone listed as a sponsor or co-author of the PEP who has write
access to the `PEP repository`_ is added to `.github/CODEOWNERS`_.

* Skim the PEP for obvious defects in language (spelling, grammar,
sentence structure, etc.), and code style (examples should conform to
* Skim the PEP for obvious defects in language (such as spelling, grammar,
sentence structure), and code style (examples should conform to
:pep:`7` & :pep:`8`). Editors may correct problems themselves, but are
not required to do so (reStructuredText syntax is checked by the repo's CI).

Expand Down Expand Up @@ -825,7 +825,7 @@ Once the PEP is ready for the repository, a PEP editor will:
* Merge the new (or updated) PEP.

* Inform the author of the next steps (open a discussion thread and
update the PEP with it, post an announcement, etc).
update the PEP with it, post an announcement, and so on).

Updates to existing PEPs should be submitted as a `GitHub pull request`_.

Expand Down Expand Up @@ -887,7 +887,7 @@ Footnotes
.. _Contributing Guide: https://github.com/python/peps/blob/main/CONTRIBUTING.rst


Change History
Change history
==============

* 2026-02-02
Expand Down
Loading
Loading