Skip to content

PEP 12 & 1: Move Specification before Rationale #4802

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

Draft
dstufft wants to merge 1 commit into
base: main
Choose a base branch
from
+14 −10
Draft

PEP 12 & 1: Move Specification before Rationale #4802

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
2 changes: 1 addition & 1 deletion .github/PULL_REQUEST_TEMPLATE/Add a new PEP.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,8 +29,8 @@ If your PEP is not Standards Track, remove the corresponding section.
* [ ] PEP topic [discussed in a suitable venue](https://peps.python.org/pep-0001/#start-with-an-idea-for-python) with general agreement that a PEP is appropriate
* [ ] [Suggested sections](https://peps.python.org/pep-0012/#suggested-sections) included (unless not applicable)
* [ ] Motivation
* [ ] Rationale
* [ ] Specification
* [ ] Rationale
* [ ] Backwards Compatibility
* [ ] Security Implications
* [ ] How to Teach This
Expand Down
14 changes: 7 additions & 7 deletions peps/pep-0001.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -509,7 +509,13 @@ Each PEP should have the following parts/sections:
projects in the Python ecosystem. PEP submissions without
sufficient motivation may be rejected.

4. Rationale -- The rationale fleshes out the specification by
4. Specification -- The technical specification should describe the
syntax and semantics of any new language feature. The
specification should be detailed enough to allow competing,
interoperable implementations for at least the current major Python
platforms (CPython, Jython, IronPython, PyPy).

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.
Expand All @@ -518,12 +524,6 @@ Each PEP should have the following parts/sections:
community and discuss important objections or concerns raised
during discussion.

5. Specification -- The technical specification should describe the
syntax and semantics of any new language feature. The
specification should be detailed enough to allow competing,
interoperable implementations for at least the current major Python
platforms (CPython, Jython, IronPython, PyPy).

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
Expand Down
8 changes: 6 additions & 2 deletions peps/pep-0012.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,13 +32,17 @@ The source for this (or any) PEP can be found in the
as well as via a link at the bottom of each PEP.


Rationale
=========
Specification
Copy link
Member Author

@dstufft dstufft Feb 3, 2026

Choose a reason for hiding this comment

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

This is kind of a silly change, but I wanted to add the Specification section here and it looked even sillier just leaving it blank, so my rationalization is that "You need to use this template" is the specification, and "rest is useful and does good stuff" is why we decided to use rest in this template.

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

If you intend to submit a PEP, you MUST use this template, in
conjunction with the format guidelines below, to ensure that your PEP
submission won't get automatically rejected because of form.


Rationale
=========

ReStructuredText provides PEP authors with useful functionality and
expressivity, while maintaining easy readability in the source text.
The processed HTML form makes the functionality accessible to readers:
Expand Down
Loading