PEP 12 & 1: Add a Change History section

[warsaw]

For PEP 694, I've found it very helpful to add a Change History section, which makes it easier for readers to understand the evolution of a PEP, especially complex ones. I think it's so useful, I'm proposing we officially add this to the PEP templates, although optionally. PEP authors can decide whether it's helpful or not, but if they do, a standard format is recommended.

---

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

[cdce8p]

It might also make sense to update the PR template then.

peps/.github/PULL_REQUEST_TEMPLATE/Add a new PEP.md

Lines 30 to 39 in 0d2bacb

	* [ ] [Suggested sections](https://peps.python.org/pep-0012/#suggested-sections) included (unless not applicable)
	* [ ] Motivation
	* [ ] Rationale
	* [ ] Specification
	* [ ] Backwards Compatibility
	* [ ] Security Implications
	* [ ] How to Teach This
	* [ ] Reference Implementation
	* [ ] Rejected Ideas
	* [ ] Open Issues

[warsaw]

It might also make sense to update the PR template then.

Thanks, great suggestion! I noticed a few other section headers missing so have now added those too (plus a spelling fix).

[warsaw]

BTW, ChatGPT has some fascinating things to say about the British inconsistency of the word "judgement":

So in Britain:
You pass judgement
A court hands down a judgment

Same country. Same word. Different spellings depending on whether wigs are involved.

[brettcannon]

I would specify the order people should use: chronological or reverse-chronological. Same with a general format (i.e. YYYY-MM-DD for the date).

[warsaw]

I would specify the order people should use: chronological or reverse-chronological. Same with a general format (i.e. YYYY-MM-DD for the date).

Good idea. Done.

[hugovk]

Wrap to ~80:

Suggested change

	[A summary of major changes the PEP has undergone. Whenever you update the ``Post-History``, add a new bullet
	item in newest-first (i.e. reverse chronological) order, using the same ``DD-MMM-YYYY`` format, with
	sub-bullets summarizing the changes. You can use the same link for the date bullet as you do in the
	``Post-History`` addition.]
	[A summary of major changes the PEP has undergone. Whenever you update the
	``Post-History``, add a new bullet item in newest-first (i.e. reverse
	chronological) order, using the same ``DD-MMM-YYYY`` format, with sub-bullets
	summarizing the changes. You can use the same link for the date bullet as you
	do in the ``Post-History`` addition.]

[hugovk]

Suggested change

	``MMM`` is the 3 English letter month abbreviation, i.e. one of Jan,
	``MMM`` is the three-letter English month abbreviation, i.e. one of Jan,

[hugovk]

Wrap to ~80:

Suggested change

	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
	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 to the PEP author's discretion, but such a section can be helpful for those following along to
	understand the evolution of your PEP. Here is :pep:`an example <694#change-history>`.
	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
	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
	to the PEP author's discretion, but such a section can be helpful for those
	following along to understand the evolution of your PEP. Here is :pep:`an
	example <694#change-history>`.