Easier tracking of PEP changes, versions, or modification dates

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: https://github.com/python/peps

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.

1 Like

People post again when enough has changed in the PEP and the discussion has died down enough to warrant starting the discussion on the PEP up again.

No, but the git repo does.

How so? The top of https://github.com/python/peps/blob/master/pep-0518.txt says the PEP was last edited by me on Dec 31, 2019. Otherwise you can click on “History” and get the complete history of the PEP.

Could you say why you want this? The PEP process is decades old at this point and we have not felt the need for versioning, so I would like to understand what your specific use-case is before we start considering changing software and/or processes to accommodate it.

2 Likes

Indeed - happy to say why, and thanks for the answers.
I’ve looked at a variety of PEPs over time, and was surprised to discover that there were changes which I had missed. I’m used to other standardization practices, which do track versions or timestamps, and I had no idea that PEPs were changing without any obvious visible indication other than reading the whole thing or following links. I assumed that Post-History was an indication of when the PEP changed, i.e. when it was posted to the web site.

I don’t want to have to follow links just to know if there have been changes recently. A Last-modified date is pretty common on web sites and seems like it would be a straightforward addition which would help engage people more effectively and productively.

Were the changes post-acceptance? If they were then were the PEPs provisional? For instance, you linked to PEP 518 which is provisional and thus still open to changes (although it’s probably approaching time to mark it as final). I probably could have kept a changelog but I just didn’t think about it after the one semantic change we made to the PEP post-provisional acceptance (plus it was discussed heavily in #packaging so it wasn’t arbitrary or a surprise to the major stakeholders affected).

Sure, but I don’t want to have to do extra work on every PEP change either. :wink:

If you want to propose a PR to add such an output on python.org/dev/peps or the HTML output of the PEPs then please go for it!

Thanks again, and I hope I haven’t conveyed any criticism of the way any of these PEPs were handled. I don’t want to add busywork, and am already glad to have most of the points clarified so others will at least be able to find some discussion of this!

Indeed, the PEP that triggered my awareness of this confusion for me was the one I listed, 518. But I’ve been under the casual misconception that I knew how to tell when PEPs changed for a decade or more.

I’m glad it seems like adding a Last-modified: to the HTML output would be helpful. I guess the right place to learn about the current process is PEP Page Generation — Python.org Website 1.0 documentation

The Django code Django code behind the site is at python/pythondotorg: Source code for python.org.

My Django chops aren’t very up-to-date, so I probably won’t find time to implement this, but I’ve documented it as an issue with some helpful tips:

I can see where a “Last modified” info can be useful in some cases. But I probably don’t care much if there was minor typo fixes to a PEP. Do you suggest the" Last Modified" info be a manual info that PEP authors put in? Or automatically updated whenever there is a change?

Good question. My notion is to do it automatically by just using the git data, rather than putting a burden on authors. My writeup of Issue #1564 notes some simple git commands to retrieve all the mod dates for all the PEPs.
It also suggests linking directly to the modification history for each PEP so users can easily see the actual changes.

If there was interest, it shouldn’t be too hard to link to a page with more insights to the diffs for each PEP, e.g. number of lines changed.

As Brett noted, authors can already include a changelog or the like if they want to highlight anything about particular changes.

I’ve started working on adding the “Last modified” footer:

Does this match your expectation?

The last modified date is obtained by making a GET request to https://api.github.com/repos/python/peps/commits?path=pep-NNNN.rst, basically the commit date, and the url is the html_url from the commit, e.g. https://github.com/python/peps/commit/63996094014f0ce1fb852454f512701991bd76c4

Wow - fast work! It looks nice.

My notion, as outlined at https://github.com/python/pythondotorg/issues/1564
was to do the work in what I understand to be the current workflow, using data straight from the git repo that is created as described at https://pythondotorg.readthedocs.io/pep_generation.html, rather than via web queries. Are you doing this in dynamically in Javascript?
I also suggested pointing to the whole history, e.g. https://github.com/python/peps/commits/master/pep-0012.txt, which makes it easy to see previous changes to the same document, rather than a single commit.

But I don’t know the tradeoffs of the various options.