This post is about shortcomings in the python packaging PEP process. With a process to make governance decisions, i'm writing this to start a discussion about how we can improve the process. This post is intentionally light on suggestions and focuses on the problems instead.

Editing comes first To propose a PEP, you need to follow the template outlined in PEP 1. Before you get to propose the PEP, you have to pass an editing step. It means spending a significant amount of time polishing a text that will change during the discussion (or get rejected entirely). For every update, you need to go through the editing process again. Once your PEP is accepted, you have to take the normative part and create a PR to packaging.python.org, which comes with a second editorial pass. I'd argue that for most packaging PEPs, the artifact and object of discussion is a new or updated page on packaging.python.org.

Media break Activity is split between the peps repo, DPO and the packaging.python.org repo, each with different responsible maintainers and editors. Tying in with the editorial review, PEPs are written restructured text. To start a discussion on discord, github or DPO, you have to write markdown, convert the outcome back to the restructured text PEP-specific format, only to eventually go back to markdown for packaging.python.org.

Forum threads DPO's single-threaded format makes it hard to have multi-facetted discussions: Two users arguing about a minor detail can drown out everything else. Threads tend to either be quiet, or have one comment that causes a lot of subsequent noise. DPO lacks basic review features such as inline annotations, check-off lists and change tracking. When someone flags a problem, this easily gets lost, overwhelmed by bikeshedding discussions that get more engagement. There is no tracking for concerns that need to be addressed for the PEP to be accepted.

Unclear status of PEPs There is no way to follow just major PEP updates, and there's no way to know how close a PEP is to acceptance. As a tool maintainer, all those 200+ comment threads have way too much volume to follow. Even just reading and understanding all PEP iterations relevant to a general purpose tool is a task beyond most people's open source time. It can easily happen that you read a PEP and think it's fine, only to later find out that it was accepted with a change that makes it unusable for your case. Or the other way around, you may think a PEP will surely go through some iterations, only to find out it has now been accepted. If you're not actively involved in the standards processes, you have no visibility into the process, and package maintainer participation is rare.

Timelines and waiting periods Conversely, from the perspective of an author, it's also not clear how far a PEP is from acceptance. You may wait a customary 1 - 2 weeks and get no comments, so you submit a PEP, only for that to start the discussion you thought just concluded. It's not possible to plan an implementation or other work around this process and allocate time appropriately. Especially for volunteers it's hard to sustain motivation when nothing happens and you are waiting.

DPO is a hostile environment Discussions on DPO tend to attract a lot of unproductive comments. The site lacks moderation against disruptive users for all but the most extreme cases. This has gotten so bad that many of the relevant maintainers do not follow DPO. Several actively refuse participation because of this. There is no way to stop bikeshedding. The cost of going through DPO makes many improvements not worth doing, or has people burn out halfway through the process.1 If you want to get the relevant feedback or have productive discussions, you have to use side channels. You're incentivized to make PEPs worse just so that DPO complains less.

Trust in implementations There's a pattern where the PEP itself has agreement, but there are lots of comments with various suggestions that translate to SHOULDs and MAYs in the spec, e.g. when to show warnings or which party has to validate what. This leads to bikeshedding, verbose PEPs and extra discussions. I believe packaging PEPs should be interoperability standards defining the minimum that two sides need to agree upon to work together.2 While a PEP's motivation section must make a convincing case that it allows building great tools, PEPs are not design docs for implementations. Historically, specs trying to specify the behavior of the implementation rather than the meaning of the subject would either deny innovation in tools (you're stuck with what we knew when writing the spec) or cause tools to ignore the spec. Requirements change over time, and the less is in a PEP, the fewer mistakes we can make.3 In my experience, tool authors and pypi maintainers are the best experts in handling guardrails and failure paths.

Lack of process for small changes We're lacking a process for making adjustments below the level of a full PEP. For example, removing a feature that nobody has implemented for a decade and that is broken by design requires a PEP: It's technically a breaking change. For other changes, it's unclear when the required consensus is reached. PRs to the packaging or packaging.python.org repos alone on the other hand lack visibility (there's a lot more than just spec changes in the packaging.python.org repo).

Prior Art This post is meant to focus on problems and not specific changes, but i'm familiar with the rust RFC process, so i'll include it as prior art. There, a team member (the equivalent to council members) can raise concerns, which are tracked in a comment for acceptance and need to be resolved before the RFC gets merged. The rust process also has a final comment period: Once the team member thinks an RFC looks good, everybody gets 10 days to read the RFC and register their concerns, knowing that this is the final version and it's worth reading and engaging. The technical discussion happens in github PRs or on zulip. The rust project has a burnout problem too, and process has been struggling also struggling with comment volume (Thoughts on RFC/stabilization reform in 2019, Pre-meta-RFC: rate limiting the firehose, How can we, as a community, make the RFC process less draining?, Rust 2020 Roadmap: Make design discussions more productive and less exhausting). Some changes were implemented as part of Planning the 2021 Roadmap, adopting Two kinds of decisions and a Backlog Bonanza.

  1. It's hard to get data for non-participation, but i wonder how many people we've lost from the python packaging community due to DPO. How much less diversity do we have in the community because people are driven out this way? ↩

  2. This is unlike python core, where a PEP represents an agreement between the core developers. They are artifacts of consensus, rather than transitioning into (living) standards. ↩

  3. That is not to say that there haven't historically been PEPs that are underspecified. ↩