Proposal: PEPs should be change proposals

Core Workflow
1

tl;dr: I’d like to propose a long-term goal toward PEPs – Python Enhancement Proposals – being proposals.

This proposal is my own, I do not represent the Steering Council or any other group here.

Currently, PEPs are used for several kinds of documents other than “Enhancement Proposals”: process guidelines, charters, informational posts, standards, etc.

This makes it hard to talk about PEPs in general. For example, “How to write a PEP” advice is often implicitly talking about standards-track PEPs.

PEP 1 (PEP Purpose and Guidelines) does cover different types of PEPs, but non-standards-track ones are clearly second-class citizens. Worse, it’s not immediately clear which parts of the text only apply to change proposals.

This is confusing.

I see two ways to limit the confusion:

  • Limit PEPs to actual change proposals, and put other kinds of documents elsewhere, or
  • Keep the various kinds of PEPs as they are, and differentiate more clearly.

I believe the first is the better long-term solution, and I’d like to propose it as the “north star” – an agreed good direction to go in.

In my mind, the biggest benefit of this would be separation between the current state (implementation, documentation, standards) and changes to that state.
The current PEP process/template is really good for change proposals, but when reading a current standard (or docs, implementation, process), I don’t usually care about the motivation/rationale/teachability for the individual changes that resulted in the text. And when I do, I rarely want to see them in the main text.

The current way of doing things blurs the line to the detriment of both use cases, though the downsides are often not apparent before a standard needs changing. It is possible to keep them apart if one is careful, but it’s hard to do if we call both kinds of documents PEPs and give shared guidelines for both. It’s even more confusing for people who aren’t aware of the details, who routinely mistake old Standards-Track PEPs for current standards, or current Process PEPs as immutable historical documents.

Of course, if we agree on this “north star”, getting to that point will take time, or might never happen if no one does the work. That’s fine. But if someone wants to do that work they should be encouraged.
To be clear, I don’t want to block any work while the transition happens: until we have a better place for, say, release schedules yet, they should continue to be submitted as PEPs.

To be concrete, let me list the kinds of PEPs that aren’t change proposals, and how they might be handled better. Each would need separate discussion of course:

  • Governance (e.g. PEP 13, 609) and other formal rules (e.g. PEP 11, 5, 387, 291, 399, 411, 434): I would love to see these in a separate repository, with tighter access controls, more appropriate styling & metadata, and more visible versioning.
  • Process guides (e.g. PEP 101, 290) should be in the Devguide.
  • Protocol documentation (e.g. PEP 248, 249, 272, 333, 3333, 394) should be in the main docs (if the protocol can be versioned together with Python minor releases, and have a stdlib component) or a separate repository (like ASGI)
  • Style guides (e.g. PEP 7, 8, 257, 287) should be part of the Devguide.
  • Release schedules (e.g. PEP 664) should be entries in a machine-readable file, with a nice frontend and a calendar export. (See a recommendation from people who use this data.) Feature highlights are in What’s New docs.
  • Informational texts (e.g. PEP 672) should be in the docs (e.g. as “HOWTO” guides) or live as personal blog posts.
  • Change proposals treated as standards – most common for Packaging (e.g. PEP 440) and Typing (655), but also found for CPython (523) – should be converted to documentation before marked Final, as per PEP 1. (That’s a bit out of scope for this proposal, though: on those we already generally agree that the current state isn’t ideal.)

The alternative is that PEPs are not always proposals. This is the status quo, but if we keep it, we should make it much clearer that it is the case – and replace many uses of “PEP” by “Standards-Track PEP”.

8 Likes
2

I think the “change proposals treated as standards” case should be in scope. They may be relatively rare for CPython itself, but they are common for packaging and typing, and at a minimum this proposal should take a position on whether continuing to allow interest groups to adapt the PEP process to manage their standards is acceptable. (I hope the answer to that is “yes” :slightly_smiling_face:)

Personally, I think that allowing PEPs to define (and modify) standards is fine, but the rules should be made clearer - in particular, PEPs creating new standards should explicitly specify where the new standard will be documented, and as you say, the PEP should not be marked final until that documentation is created. The documentation is (in effect) the “implementation” of the standard in the same way that the code changes are the implementation of a new language feature.

There would be some work moving to this model - while packaging currently works this way, in principle at least (so this is more a call to “get off our backsides” and do what we claim to do :wink:), I don’t think the typing community currently has a formal repository for their standards. Also, CPython itself doesn’t really have a suitable location (for things like the DB-API or WSGI).

It’s also possible that people would consider documenting a standard twice, once in a PEP and subsequently in the standards documents, as pointless busy-work. Certainly it’s not always a simple copy and paste exercise - PEPs and standards have different structures and goals.

Overall, though, I think this is a good idea.

1 Like
3

AFAIK, both PyPA and typing-sig generally agree on the direction. Yes, actually moving in that direction is slow, but that’s not what this proposal is about.

Yes. And I don’t think that’s a problem.
Again, I want to encourage people to build the infrastructure for standards (and then move them there), not block others while the infrastructure is built.

Oh, we’d definitely want to avoid busy-work!
You could include the new standard in the PEP as is, and add the other sections around it (motivation, teachability, etc – ones relevant to the initial version). The PEP structure is not rigid, it’s possible to write the them with copy-paste in mind. (For example, my own PEP 630→HOWTO transition mostly touched the intro.)
Or link to a PR, the way typical CPython PEPs link to a reference implementation. You can even put an auxiliary document in the PEPs repo, if there’s no better place for it.

1 Like
4

I think you are reading too much into the term “Python Enhancement Proposal (PEP)” :slight_smile:

The idea was to have a central place where we can put all these different types of documents relevant to Python, so that they can easily be found by community members and other stake holders, but also to simplify linking and referencing between them.

Splitting up this wealth of information would cause fragmentation and not be beneficial to the community.

My impression is that your main criticism really focuses around PEP 1 not addressing the different types of documents we store in the PEP index with enough detail. That’s fair and certainly something which could be fixed, perhaps even splitting out the different explanations into new PEPs, one for each type you list.

Let’s not get back into the state we were in before going with PEPs. In those times, such information was dispersed across many different web pages, posts to news groups and mailing lists. The PEP index has changed all that for the better.

7 Likes
5

Thank you for listing out all the different types of PEP documents. I agree with Petr’s idea that PEPs should be change proposals and that other types of documentation can be hosted elsewhere.

Docs like Release Schedule, and Style Guides have much wider audience and usage by the users and developers, not just for core developers and contributors. Having machine-readable data of the release schedule will be helpful to the whole community.

I know that it is SC’s role to review PEPs and make pronouncements. What will happen if these docs were to be split out apart from the PEPs? Will there be different type of council/decision maker, or will the SC still decide on them?

6

I don’t think the suggestion is to go back to the state without any process. The way I see it, other types of docs can perhaps be decided/owned by different type of groups, and follow the same strict process as the PEP, just not on the PEP itself.

7

I agree that some of the documents that have traditionally been non-standards track PEPs could serve our community better by being in different places and not the PEPs repo. That said, I think we have to optimize on the consumers of these docs. E.g. discoverability, a clear sense of where to put what, change frequency and friction, etc. are all things to consider. (Serious deja vu from my previous $work responsibilities :smiley: )

3 Likes
8

One route would be to clarify the documentation regarding types of PEPs,
and then make indexes of each type, that link to the (current) PEP
repository. While appropriately crafted searches could produce a
listing similar to such an index, an index would have the benefit of
ordering, and possibly further categorization, for people that want to
browse and learn.

This would give the benefits of the separation of concerns, without
requiring massive changes to the current process.

9

Thank you, Mark, for summarizing the arguments for keeping PEPs!
I’d be fine with keeping the status quo (and improving the situation), if it turns out that’s what we want.

My main point is that it would be good to separate standards from documents that propose changes to the standards. If PEPs serve both roles, they won’t serve either one well. If we keep PEPs only, we should probably write two PEPs for the initial revision.
The downsides of mixing the two don’t become apparent until the document needs a major revision, at which point the PEP process tends to break down, as we’re repeatedly finding out:

  • PyPA moved to a separate standards repo
  • typing documentation is a bundle of PEPs that non-experts can’t quite navigate
  • Is PEP 5 a living standard or a historical document? How do you update it? Do you keep the 2000 version available? Should we keep a motivation/rationale log for changes, and if so, where?
  • PEP 646 is getting a rather complicated addition retroactively. If that’s allowed, what does it mean to be “compliant with PEP 646”? (Also see Guido’s post about PEP 3333 from 2010.)

I see the appeal for a central storage of Python-related documents, but I think it’s a simplification we’ve outgrown.
Should the interpreter_definition or Garbage Collector Design be PEPs? Why aren’t they? What should be the guidelines for updating them? Should the access controls be the same as for PEP 13?

That’s a great idea. Now that we have ~600 PEPs, maybe it’s time to evaluate if it worked.
Do you find it easy to find information in the PEP index? I … well, I do, but I consider it a specialized skill.
As for referencing – for the documents I’m proposing to move out, URLs would work quite well. Yes, in general URLs can go stale, but you can mitigate that with some care.
On the other hand, using arbitrary numbers for features works best for a limited time and audience. IMO, continuing to use them for accepted standards/features is actually hostile to a wider audience.

Definitely! I understand that PEPs were an improvement.
But, consider the Devguide: the place for version-independent, dev-facing docs, structured a bit more like a wiki than a collection of whitepapers. For that, it’s better than PEPs. Let’s do more of those.
And let’s keep PEPs for what they’re good for (and for things that don’t have a better home yet).

Yes. Definitely.

1 Like
10

Reading your reply, I believe that your concern is more about process than actually keeping everything in one place. That’s good :slight_smile:

I think we need to view PEPs more broadly as documents to base discussions and decisions on.

If a PEP is used to define a standard, revisions to that standard can be incorporated into the document using documented additions (many PEPs have an editing history for this purpose), or a new PEP for a later accepted version of the standard can be posted. The is how the DB-SIG works on the DB-API documents (PEP 248 and 249), for example. We clearly state what is part of the standard, what is an optional extension and where we see changes coming in new versions.

If a PEP is meant to support a decision made by the SC or the core devs, it is really up to the SC to define how the document should evolve. After the final decision, changes could still be made, but those should be well visible. Again, whether to create a new PEP for a changed version depends on the scope of the changes.

To manage such document evolution, we have the PEP headers. PEPs can be superseded by others. Much like RFC can be replaced with new RFCs suggesting new variants of the standard or extensions.

I guess whether or not something needs a PEP is debatable. If the consequences to the larger Python community, e.g. affecting backwards compatibility, are serious, a PEP will definitely be warranted. If a new internal CPython subsystem is being devised, which only affects core devs, I would not necessarily regard a PEP as necessary – it’s more important that the logic is documented in the dev guide for other core devs to use as reference. But that’s my personal view… if there’s something which needs to be discussed in a larger context, PEPs are certainly the better way to make decisions on design more transparent.

The index could certainly be improved now that it has grown to a significant number of documents.

It would probably be useful to add topic based entry point to the PEPs in addition to the current index, which focuses more on state, category and process management. Similar to what @Glenn mentioned.

Even without such additional indexes, PEPs are well covered by internet search engines, so it’s typically easy to find the right PEP by just adding “python pep” to the search string.

2 Likes
11

The DB-API PEPs (both Created: 29-Mar-2001 btw – that looks like a mistake) seem like they could use the same kind of process as the Packaging and Typing PEPs: they’re both removed from core Python (mainly: they don’t follow CPython versioning so they’re not a good fit for the main docs), and they’re standards that might need some kind of versioning. Of course, these sigs need to manage a lot more changes than DB.

And with messages like in PEP 630, it’s then easy to find the current version. Superseded-By headers don’t quite stand out.

12

The SC can delegate anything, while it still has the final say if there are disagreements. For example, the SC doesn’t really vet PEP 8 updates currently – though it can step in if there are any complaints.
I’d expect release schedules to be decided by release managers, and style guide updates being fine with consensus on the PR. Or on Discourse for bigger stuff, or a PEP for a total rewrite.

13

Would you keep all the docs in one place but start using more prefixes then just PEP?

Each category of document would have its own process, expections and prefix.

14

We have the devguide for process-related docs and docs.python.org for language-related things. packaging.python.org covers packaging. I would assume we would work with the appropriate group(s) to set up the right place online from them to host their specifications as originally outlined/changed by PEPs. But I think Petr’s suggestion is PEPs become a recording of (proposed) changes to things that fall under the SC’s purview (even in packaging-related stuff as that’s technically a delegated responsibility from the SC), and the things that get changed live where it most makes sense.

15

The DB-API is maintained outside core Python by the DB SIG, but still very much part of what Python is all about, so right on target for PEPs. Same for packaging or typing.

I don’t really see any benefit by moving things out of the PEP index into separate repos, or reserving the PEP index solely for SC related documents. We already have enough fragmentation in the Python eco-system (e.g. the data science field, typing, packaging and async each working in its their eco systems). We don’t need more of this.

I agree that the PEP index could need a bit more structure and perhaps guidance, so that it becomes easier to navigate. To achieve this, PEP 1 could have separate sections for each type of PEP document, or we could have separate PEPs outlining the intent, process and guidance for each type.

Additionally, we could add topic indexes, collecting PEPs belonging to various topics.

And finally, I think we should open up the PEP index to welcome additions by the above mentioned groups, so that we can use it to help in reunifying the Python community. E.g. we could have PEPs defining the basic API of dataframes, model interfaces, the ASGI API, perhaps an async version of the DB-API, etc.

PS: Thanks for the hint with the wrong creation date on the PEPs. This was the creation date of the PEP versions of the specs, not their original creation date, which far precedes the whole PEP idea.

1 Like
16

Why not? It’s my view that modularity is one of the better ways to improve efficiency of organisations. It sets up boundaries which allow smaller groups to focus on improving specific verticals.

If the PEPs are targets of discussion which the SC have final say over, which groups are not under the SC’s purview?

17

Agreed.

Modularity is great for making sure that organizations can properly scale and efforts are undertaken by the right domain experts. However, the results of that work should ideally end up in a central knowledge base, so that everyone involved has the chance to easily get a full picture of where the organization is heading – including the Steering Council, who’s main role is to provide guidance for that direction.

The PEP index is our natural knowledge base for managing Python standards, governance, designs, architectures and changes to all these.

Breaking this up into separate silos would not help in clarifying where Python is heading. Well, at least IMO.

2 Likes
18

This is new but we have already this for packaging, release and typing PEPs, and can add more:

It’s linked to in the intro of the PEP 0 homepage.

19

Excellent start :slight_smile:

I would make it a bit more prominent, though, and put the topic listing right before the category listing (if possible):

image
image880×379 30.7 KB

2 Likes
20

For others’ reference, @hugovk has implemented @malemburg 's suggestion in

3 Likes