In the recent years, there’s been a new phenomenon in CPython development: core developers who work on Python full-time, including whole teams of them.
Overall, this is great: things can be improved and fixed much faster than before. On the other hand, since a few people can now move much faster than most of the others, we’re starting to get issues in coordination – ensuring that all relevant people can follow changes, review them, and suggest better alternatives. One of the strengths of a large open-source team is that we can represent many different use-cases and viewpoints, and we run the risk of losing some of that.
How can we improve the situation, without losing the advantages that dedicated teams and individuals bring? I want to suggest a few rules of thumb to keep in mind when contributing to the Python project. It applies to everyone, but if you have more time than the rest of us, consider spending more time than usual following them. These aren’t final; suggestions are welcome.
(This is based on discussions in the Steering Council, but as it grew in scope, I realized – perhaps too late – that it would work much better if I just propose it myself and gather community input, than gather SC agreement and then publish a document out of the blue.)
This is also available as a Google doc, anyone with a Google account may comment there.
Be prepared to revert or fix
Be prepared to revert your change if it has unexpected consequences. Think twice before making large-scale, complex changes: you should ensure you’ll have time to fix any follow-up issues.
It helps to communicate your changes ahead of time and ensure there are other people who understand the issue and changes.
Don’t run experiments in the main branch
If you have a major change that’s not ready to go in, do not make preparatory commits in main.
Such changes should either be part of your bigger change (outside the main repo), or have their own valid reason to be merged – and they should have tests, docs, or even a PEP, as appropriate.
We want to avoid two things:
- Code for failed experiments being kept as additional baggage
- Preparing a specific solution to a problem that might have a better solution
Examples of planned changes where this applies are:
- GIL removal
- subinterpreter support
- moving C state to the heap
Respect others’ time
If you can dedicate time to Python every day, keep in mind that there are others who can’t, and who can nevertheless have good input. If a change isn’t blocking or time-sensitive, wait a week (or more) for feedback on pull requests or discussions. Especially if you ask for such feedback.
Keep a roadmap
If you have a long-term project, keep a roadmap document so others can see the “big picture” and suggest high-level ideas. Currently, a “whitepaper PEP” like PEP-659, PEP-620, PR-2212 is the way to do this. A PEP might not be the best format for such a roadmap (the SC is discussing potential alternatives), but it’s better to publish something that’ll move later than to keep the planned steps and goals as a surprise.
Note that Informational PEPs do not necessarily represent a Python community consensus or recommendation: you don’t need any sort of approval to publish one. But since they can’t be approved, they’re not enough to make PEP-sized changes to Python.
If it ain’t broken, don’t fix it.
It is too easy to introduce unwanted bugs when refactoring. Only do refactoring or code clean-up if you’re touching the relevant code for a different, better reason. (Or the refactoring is part of an accepted PEP.)
You almost certainly need a PEP for:
- Changing the syntax
- (except e.g. changing the error message for an existing SyntaxError)
- Adding/removing/changing a new builtin
- Adding or removing a stdlib module
- A change that will introduce a visible, measurable performance regression
When you should open a project-wide heads-up or discussion:
A thread on Python-dev or Discourse is in order for:
- changes that affect many different modules
- breaking backwards compatibility (i.e. breaking users’ working code)
- any change with which others will likely disagree
Be prepared to write a PEP: if you start an extended discussion, it should be summarized in a document.
An issue or PR is probably fine for:
- Obvious bugs with straightforward or backwards-compatible fixes
- Implementing an approved PEP, or a change with SC approval*
- Adding API that you are ready to support for several decades
- Documentation clarifications/typos