Skip to content

Conversation

@dstufft
Copy link
Member

@dstufft dstufft commented Feb 3, 2026

Having the Rationale come before the Specification makes PEP documents more awkward to read and write as the PEP is expected to provide a rationale for the decisions made in the specification, before those decisions have even been introduced. This leads to either having to have the rationale play double duty for both introducing the decisions and explaining why or requires skipping to the Specification section, then coming back up to the Rationale.

With this change, a PEP flows in a more natural order of:

  1. Elevator Pitch
  2. Why should things change?
  3. What are you proposing.
  4. Why are you proposing that?

📚 Documentation preview 📚: https://pep-previews--4802.org.readthedocs.build/

@dstufft
Copy link
Member Author

dstufft commented Feb 3, 2026

I just happened to mention this annoyance I've had with PEPs to @warsaw and he recommended I make a PR to change it, so here I am :)

I'm keeping this as a draft until #4801 so I can use the fancy new Change History section,

Copy link
Member

@warsaw warsaw left a comment

Choose a reason for hiding this comment

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

My other PEP 12 changes have landed. Please merge this one and then I will post to DPO and update the Post-History and add a Change History section. Progress!

@warsaw warsaw marked this pull request as ready for review February 3, 2026 17:49
@warsaw warsaw requested review from a team, brettcannon and ncoghlan as code owners February 3, 2026 17:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants