Should the text of PEPs include version numbers for reader convenience?
Or should we make it easier for casual readers to know when a PEP was last changed, and track the version history of a given PEP?
I would be surprised if this hadn’t been discussed before, but I looked and didn’t run across it here.
Background:
Each PEP, when served by www.python.org, includes a Post-History
header which looks sort of like a version number or modification date, but isn’t.
PEP 1 -- PEP Purpose and Guidelines | Python.org says:
Post-History is used to record the dates of when new versions of the PEP are posted to python-ideas and/or python-dev. Both headers should be in dd-mmm-yyyy format, e.g. 14-Aug-2001.
I’m curious to know more about the current and historical practices around when to post to those lists, but clearly documents change without being posted.
PEPs also have a footer that points to the source on GitHub, which is added by the web server, like:
Source: https://github.com/python/peps/blob/master/pep-0518.txt
The server doesn’t include a Last-modified
timestamp.
Someone who is unfamiliar with GitHub and stumbles across a PEP might not figure out when it was last changed or what the changes were, even if they find the source link, though all they have to do is click the “History” button on the source page.
Even if they read PEP 1, which also says:
Because the PEPs are maintained as text files in a versioned repository, their revision history is the historical record of the feature proposal.
(footnote) This historical record is available by the normal git commands for retrieving older revisions, and can also be browsed via HTTP here: GitHub - python/peps: Python Enhancement Proposals
they will have to wade thru various commands, pages and local searches to get that information. since all PEPs are in the same repo.
Alternatives
One common approach to this in the standards development world (e.g. the IETF) is to not alter documents after they are distributed, but to distribute updated versions, e.g. as a subsequent Internet Draft or via links to errata for approved RFCs.
Another common approach is to include version numbers or last-modified timestamps in the documents. This would allow even casual readers to track whether they were viewing the same version they read at some previous time.
If we don’t want the overhead of picking and updating version numbers, I suggest we update the www.python.org server to add a bit more to the footer of each PEP. E.g. a Last-modified:
footer with a link to the github history like https://github.com/python/peps/commits/master/pep-0518.txt. I’d suggest also updating PEP 1 to document that.
My guess is that the latter web-server-based approach is easiest and best leverages our modern tooling. But I include the others both because there may be other reasons for tracking versioning information for PEPs themselves, and to help others like me who might be wondering how the PEP process differs from other similar processes.