diff --git a/developer-workflow/index.rst b/developer-workflow/index.rst index e73927f1d..9919398e6 100644 --- a/developer-workflow/index.rst +++ b/developer-workflow/index.rst @@ -8,11 +8,11 @@ Development workflow :maxdepth: 5 communication-channels + lang-changes development-cycle stdlib extension-modules c-api - lang-changes grammar porting sbom diff --git a/developer-workflow/lang-changes.rst b/developer-workflow/lang-changes.rst index 52aabb15d..0b2c613fa 100644 --- a/developer-workflow/lang-changes.rst +++ b/developer-workflow/lang-changes.rst @@ -1,37 +1,43 @@ .. _lang-changes: .. _langchanges: -Changing the Python language -============================ -On occasion people come up with an idea on how to change or improve Python as a -programming language. This document is meant to explain exactly what changes -have a reasonable chance of being considered and what the process is to propose -changes to the language. +Changing Python +=============== +On occasion people come up with an idea for changing or improving the Python +language or standard library. +This page explains how to propose changes and what to expect during the +process. -What qualifies + +Considerations -------------- -First and foremost, it must be understood that changes to the Python -programming language are difficult to make. When the language changes, -**every** Python programmer already in existence and all Python programmers to + +First, understand that changes to Python +are difficult to make. When the language changes, +**every** Python programmer and all Python programmers to come will end up eventually learning about the change you want to propose. Books will need updating, code will be changed, and a new way to do things will -need to be learned. Changes to the Python programming language are never taken +need to be learned. Changes to Python are never taken lightly. -Because of the seriousness that language changes carry, any change must be -beneficial to a large proportion of Python users. If the change only benefits a -small percentage of Python developers then the change will not be made. A good -way to see if your idea would work for a large portion of the Python community -is to ask in the `Ideas Discourse category`_. You can also -go through Python's stdlib and find examples of code which would benefit from -your proposed change (which helps communicate the usefulness of your change to -others). For further guidance, see :ref:`suggesting-changes`. +Backward compatibility is a significant concern. Existing Python code has to +continue to work. There are exceptions to this rule, but they are very rare +and are only allowed when the benefits of the change greatly outweigh the costs +of breaking existing code. -Your proposed change also needs to be *Pythonic*. While only the Steering -Council can truly classify something as Pythonic, you can read the -:pep:`Zen of Python <20>` for guidance. +Because of the seriousness of changing the language, any change must be +beneficial to many Python users. If the change only helps a small percentage of +Python developers then the change will not be made. A good way to see if your +idea would work for a large portion of the Python community is to discuss it in +the `Ideas category in Discourse `_. You can also look in Python's standard +library to find examples of code which would benefit from your proposed change. +.. important:: + For all of these reasons, most proposed changes to Python are rejected. This + doesn't mean you shouldn't suggest them. It can be useful to explore + alternatives and to get feedback from the community. Just be aware that + getting a change accepted is difficult. Don't take it personally. .. index:: single: PEP process @@ -41,25 +47,107 @@ Council can truly classify something as Pythonic, you can read the Suggesting new features and language changes -------------------------------------------- -The `Ideas Discourse category`_ -is specifically intended for discussion of new features and language changes. -Please don't be disappointed if your idea isn't met with universal approval: -as the :pep:`long list of Withdrawn and Rejected PEPs -<0#rejected-superseded-and-withdrawn-peps>` -in the :pep:`PEP Index <0>` attests, -and as befits a reasonably mature programming language, -getting significant changes into Python isn't a simple task. +Proposing a change involves the following steps: + +- Describe your idea in detail. + +- Engage in discussion about the idea. + +- Rarely, the idea will advance to a formal proposal stage. + + +Describe your idea +^^^^^^^^^^^^^^^^^^ + +The `Ideas category in Discourse `_ is specifically intended for discussion +of new features and language changes. Make your proposal as a `new topic +`_ there. + +Your proposal needs to be **detailed**. Describe the change you want to make, +why you want to make it, and what benefits it will bring to Python users. Be +specific. Show that you have considered the effect of the change on existing +code. + +Some things you should **not** do: + +- **Don't** format your idea as a Python Enhancement Proposal (PEP). + It's good to use the PEP template as a guide for what information to include, + but don't try to write a full PEP until the idea has been accepted for + further consideration. + +- **Don't** create a list of proposed changes. Each idea needs its own + discussion. Proposing a change is significant work. You will need to spend + time on each proposal. A tossed-off list will not be taken seriously. + +When justifying your idea, these are **not good reasons** to make a change: + +- "Other languages work this way." Languages are different. What works well + in one language may not work well in Python, or Python may already have a + way to do a similar thing. + +- "It would be nice." This is too vague. Be specific about the benefits + your change will bring, and consider the costs as well. + +Some things you **should** do: + +- Research whether your idea has been proposed before. There are many + suggestions that have been made and rejected in the past. If your idea has a + history, read the discussion to see why it was rejected. Previously rejected + ideas are especially unlikely to get accepted. If you can address the + concerns raised in the previous discussion, mention that in your proposal. + +- Read other ideas to see how they are presented. This will help you flesh out + your proposal. + +- Read other ideas to understand the kinds of concerns that are raised and + objections that must be answered. Your proposal will be stronger if you can + address these concerns up front. + +- Provide enough detail to fully explain your idea, and to show that you have + considered all the implications of the change. Strike the right balance + between brevity and completeness. A shorter proposal will be easier to + discuss, so long as it includes all the necessary information. + + +Engage in discussion +^^^^^^^^^^^^^^^^^^^^ + +Once you post your proposal, people will respond. You need to continue +the discussion, answer questions, and address objections. This is an important +part of the process. Other people's perspectives will help explore the full +impact of the idea and find strengths or weaknesses you may not have +considered. + +You will almost always get at least some push-back. Don't be disappointed, +and don't take it personally. +As the long list of :pep:`Withdrawn and Rejected PEPs +<0#rejected-superseded-and-withdrawn-peps>` in the :pep:`PEP Index <0>` +attests, and as befits a mature programming language, getting significant +changes into Python isn't a simple task. + +Engage in good faith. The goal of the discussion is to find the best balance +between competing concerns. If your idea has merit, the discussion will help +refine it and make it stronger. If your idea has flaws, the discussion will +help identify them so you can address them or move on. Keep the discussion +productive and focused on the issues, not on personalities. + +It is especially useful to discuss with core team members since +they know the language and design considerations well. +If your proposal makes it to the PEP stage, +you'll need a core team member as a sponsor. +Sometimes they will differ in opinion, or merely be unconvinced. When there +isn't a clear positive sentiment, the `Status Quo Wins a Stalemate`_. + +Even if your idea is not accepted, the discussion can help you and others +understand the design of Python better, and help inform future proposals. -If the idea is reasonable, someone will suggest posting it as a feature -request on the `issue tracker`_, or, for larger changes, -writing it up as PEP following the :ref:`lang-changes-pep-process`. -Sometimes core developers will differ in opinion, -or merely be collectively unconvinced. -When there isn't an obvious victor, then the `Status Quo Wins a Stalemate`_. +Formal proposal +^^^^^^^^^^^^^^^ -For some examples on language changes that were accepted, -see `Justifying Python Language Changes`_. +If the idea gets positive discussion, someone will suggest posting it as a +feature request on the `issue tracker`_, or, for larger changes, writing it up +as PEP following the :ref:`lang-changes-pep-process`. Congratulations! .. index:: PEP process @@ -69,20 +157,20 @@ see `Justifying Python Language Changes`_. PEP process ----------- -Once you are certain you have a language change proposal -which will appeal to the general Python community, -you can begin the :abbr:`PEP (Python enhancement proposal)` process -to officially propose the change. -See :pep:`1` for information on PEPs and the PEP process, -and the :pep:`PEP Index <0>` for examples. +Once you have a proposal which will appeal to +the general Python community, you can begin the PEP +process to officially propose the change. +This starts with finding a sponsor from the core team. +See :pep:`1` for +information on PEPs and the PEP process, and the :pep:`PEP Index <0>` for +examples. -If the PEP is accepted, then your proposed language change will be introduced -in the next release of Python. -Otherwise, your PEP will be recorded as rejected along with an explanation, -to inform others who may propose a similar language change in the future. +If the PEP is accepted, then your language change will be introduced in a +future release of Python. Otherwise, your PEP will be recorded as rejected +along with an explanation, to inform others who may propose a similar language +change in the future. .. _issue tracker: https://github.com/python/cpython/issues -.. _Ideas Discourse category: https://discuss.python.org/c/ideas/6 -.. _Status Quo Wins a Stalemate: https://www.curiousefficiency.org/posts/2011/02/status-quo-wins-stalemate.html -.. _Justifying Python Language Changes: https://www.curiousefficiency.org/posts/2011/02/justifying-python-language-changes.html +.. _ideas: https://discuss.python.org/c/ideas/6 +.. _Status Quo Wins a Stalemate: https://www.curiousefficiency.org/posts/2011/02/status-quo-wins-stalemate/