From ee4b7b74f989b306b7cec9c61f4d43ffb06590c1 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Thu, 19 Feb 2026 19:27:12 +0000 Subject: [PATCH 1/7] Restructure index --- index.rst | 227 ++++++++++++++++++++++-------------------------------- 1 file changed, 93 insertions(+), 134 deletions(-) diff --git a/index.rst b/index.rst index 997f59932..e586c1cf1 100644 --- a/index.rst +++ b/index.rst @@ -15,16 +15,53 @@ Python Developer's Guide .. highlight:: bash This guide is a comprehensive resource for :ref:`contributing ` -to Python_ -- for both new and experienced contributors. It is +to various areas of Python_ -- for both new and experienced contributors. It is :ref:`maintained ` by the same -community that maintains Python. We welcome your contributions to Python! +community that maintains Python. We welcome your contributions! + + +.. _contributing: + +Contributing +------------ + +We encourage everyone to contribute to Python and that's why we have put up this +developer's guide. If you still have questions after reviewing the material in +this guide, then the `Core Python Mentorship`_ group is available to help guide new +contributors through the process. + +Guide for contributing to Python: + +======================== =================== +Code Documentation +======================== =================== +:ref:`setup` :ref:`docquality` +:ref:`help` :ref:`documenting` +:ref:`pullrequest` :ref:`style-guide` +:ref:`runtests` :ref:`rst-primer` +:ref:`fixingissues` :ref:`translating` +:ref:`communication` :ref:`devguide` +:ref:`gitbootcamp` +:ref:`devcycle` +======================== =================== + +We **recommend** that the documents in this guide be read as needed. You +can stop where you feel comfortable and begin contributing immediately without +reading and understanding these documents all at once. If you do choose to skip +around within the documentation, be aware that it is written assuming preceding +documentation has been read so you may find it necessary to backtrack to fill in +missing concepts and terminology. + +A number of individuals from the Python community have contributed to a series +of excellent guides at `Open Source Guides `__. + .. _quick-reference: -Quick reference ---------------- +CPython contribution quick reference +------------------------------------ -Here are the basic steps needed to get set up and contribute a pull request. +Here are the basic steps needed to get set up and open a pull request. This is meant as a checklist, once you know the basics. For complete instructions please see the :ref:`setup guide `. @@ -76,9 +113,10 @@ instructions please see the :ref:`setup guide `. ./python.exe -m test -j8 - Note: :ref:`Most ` macOS systems use - :file:`./python.exe` in order to avoid filename conflicts with - the ``Python`` directory. + .. note:: + :ref:`Most ` macOS systems use + :file:`./python.exe` in order to avoid filename conflicts with + the ``Python`` directory. .. tab:: Windows @@ -91,40 +129,27 @@ instructions please see the :ref:`setup guide `. git checkout -b fix-issue-12345 main If an issue does not already exist, please `create it - `__. Trivial issues (for example, typo fixes) do - not require any issue to be created. - -6. Once you fixed the issue, run the tests, and the patchcheck: - - .. tab:: Unix - - .. code-block:: shell - - make patchcheck + `__. Trivial issues (for example, typos) do + not require an issue. - .. tab:: macOS +6. Once you fix the issue, run the tests and `pre-commit `__: - .. code-block:: shell + .. code-block:: shell - make patchcheck + pre-commit install + pre-commit run - .. tab:: Windows - - .. code-block:: dosbatch - - .\python.bat Tools\patchcheck\patchcheck.py - - If everything is ok, commit. + See :ref:`install-pre-commit` for more details. If everything is ok, commit. 7. Push the branch on your fork on GitHub and :ref:`create a pull request - `. Include the issue number using ``gh-NNNN`` in the - pull request description. For example: + `. Include the issue number using ``gh-NNNNNN`` in the + pull request title. For example: .. code-block:: text gh-12345: Fix some bug in spam module -8. Add a News entry into the ``Misc/NEWS.d`` directory as individual file. The +8. Add a News entry into the ``Misc/NEWS.d/`` directory as individual file. The news entry can be created by using `blurb-it `__, or the :pypi:`blurb` tool and its ``blurb add`` command. Please read more about ``blurb`` in its @@ -136,58 +161,6 @@ instructions please see the :ref:`setup guide `. Agreement (CLA) as described in the :ref:`Licensing ` section of this guide. -Quick links ------------ - -Here are some links that you probably will reference frequently while -contributing to Python: - -* `Issue tracker`_ -* `Buildbot status`_ -* :ref:`help` -* PEPs_ (Python Enhancement Proposals) -* :ref:`gitbootcamp` - -.. _contributing: - -Contributing ------------- - -We encourage everyone to contribute to Python and that's why we have put up this -developer's guide. If you still have questions after reviewing the material in -this guide, then the `Core Python Mentorship`_ group is available to help guide new -contributors through the process. - -A number of individuals from the Python community have contributed to a series -of excellent guides at `Open Source Guides `__. - -Core developers and contributors alike will find the following guides useful: - -* `How to Contribute to Open Source `__ -* `Building Welcoming Communities `__ - -Guide for contributing to Python: - -======================== =================== ======================= ======================= -Contributors Documentarians Triagers Core team -======================== =================== ======================= ======================= -:ref:`setup` :ref:`docquality` :ref:`tracker` :ref:`responsibilities` -:ref:`help` :ref:`documenting` :ref:`triaging` :ref:`developers` -:ref:`pullrequest` :ref:`style-guide` :ref:`helptriage` :ref:`committing` -:ref:`runtests` :ref:`rst-primer` :ref:`experts` :ref:`devcycle` -:ref:`fixingissues` :ref:`translating` :ref:`labels` :ref:`motivations` -:ref:`communication` :ref:`devguide` :ref:`gh-faq` :ref:`experts` -:ref:`gitbootcamp` :ref:`triage-team` -:ref:`devcycle` -======================== =================== ======================= ======================= - -We **recommend** that the documents in this guide be read as needed. You -can stop where you feel comfortable and begin contributing immediately without -reading and understanding these documents all at once. If you do choose to skip -around within the documentation, be aware that it is written assuming preceding -documentation has been read so you may find it necessary to backtrack to fill in -missing concepts and terminology. - Proposing changes to Python itself ---------------------------------- @@ -206,36 +179,6 @@ happen and that process is also described as part of this guide: * :ref:`langchanges` -Other interpreter implementations ---------------------------------- - -This guide is specifically for contributing to the Python reference interpreter, -also known as CPython (while most of the standard library is written in Python, -the interpreter core is written in C and integrates most easily with the C and -C++ ecosystems). - -There are other Python implementations, each with a different focus. Like -CPython, they always have more things they would like to do than they have -developers to work on them. Some major examples that may be of interest are: - -* PyPy_: A Python interpreter focused on high speed (JIT-compiled) operation - on major platforms. -* GraalPy_: A Python interpreter which has first-class support for - embedding in Java, built on GraalVM. -* Jython_: A Python interpreter focused on good integration with the Java - Virtual Machine (JVM) environment. -* IronPython_: A Python interpreter focused on good integration with the - Common Language Runtime (CLR) provided by .NET and Mono. -* Stackless_: A Python interpreter focused on providing lightweight - microthreads while remaining largely compatible with CPython specific - extension modules. -* MicroPython_: A tiny Python interpreter with small subset of the Python - standard library that is optimised to run on microcontrollers and in - constrained environments. -* CircuitPython_: A fork of MicroPython designed to simplify experimenting - and learning to code on low-cost microcontroller boards. - - Key resources ------------- @@ -252,11 +195,12 @@ Key resources * Source code * `Browse online `__ - * `Snapshot of the *main* branch `__ + * `Download a snapshot of the 'main' branch `__ -* PEPs_ (Python Enhancement Proposals) +* :pep:`PEPs <0>` (Python Enhancement Proposals) * :ref:`help` * :ref:`developers` +* :ref:`gitbootcamp` .. _resources: @@ -270,16 +214,14 @@ Additional resources * :ref:`internals` * :ref:`grammar` -* Tool support +* Tool support: * :ref:`gdb` * :ref:`clang` - * Various tools with configuration files as found in the `Misc directory`_ - * Information about editors and their configurations can be found in the - `wiki `__ + * Various tools with configuration files as found in the + :cpy-file:`Misc/` directory * `python.org maintenance`_ -* :ref:`Search this guide ` Code of conduct @@ -290,21 +232,13 @@ infrastructure is `covered `__ by the `PSF Code of Conduct `__, which includes all infrastructure used in the development of Python itself -(for example, mailing lists, issue trackers, GitHub, etc.). +(for example, Discourse, issue trackers, GitHub, and so on). In general this means everyone is expected to be open, considerate, and respectful of others no matter what their position is within the project. -Status of Python branches -------------------------- - -Moved to :ref:`versions` - -.. _contents: - -Full table of contents ----------------------- .. toctree:: + :hidden: :maxdepth: 3 getting-started/index @@ -318,9 +252,35 @@ Full table of contents versions contrib/index -.. _Buildbot status: https://www.python.org/dev/buildbot/ -.. _Misc directory: https://github.com/python/cpython/tree/main/Misc -.. _PEPs: https://peps.python.org/ + +Other interpreter implementations +--------------------------------- + +This guide is specifically for contributing to the Python reference interpreter, +also known as CPython (while most of the standard library is written in Python, +the interpreter core is written in C and integrates most easily with the C and +C++ ecosystems). + +There are other Python implementations, each with a different focus. Like +CPython, they always have more things they would like to do than they have +developers to work on them. Some major examples that may be of interest are: + +* PyPy_: A Python interpreter focused on high speed (JIT-compiled) operation + on major platforms. +* GraalPy_: A Python interpreter which has first-class support for + embedding in Java, built on GraalVM. +* Jython_: A Python interpreter focused on good integration with the Java + Virtual Machine (JVM) environment. +* IronPython_: A Python interpreter focused on good integration with the + Common Language Runtime (CLR) provided by .NET and Mono. +* MicroPython_: A tiny Python interpreter with small subset of the Python + standard library that is optimised to run on microcontrollers and in + constrained environments. +* CircuitPython_: A fork of MicroPython designed to simplify experimenting + and learning to code on low-cost microcontroller boards. + + +.. _Buildbot status: https://buildbot.python.org/#/ .. _python.org maintenance: https://pythondotorg.readthedocs.io/ .. _Python: https://www.python.org/ .. _Core Python Mentorship: https://www.python.org/dev/core-mentorship/ @@ -328,7 +288,6 @@ Full table of contents .. _GraalPy: https://www.graalvm.org/python/ .. _Jython: https://www.jython.org/ .. _IronPython: https://ironpython.net/ -.. _Stackless: https://github.com/stackless-dev/stackless/wiki/ .. _MicroPython: https://micropython.org/ .. _CircuitPython: https://circuitpython.org/ .. _Issue tracker: https://github.com/python/cpython/issues From 6cd0e1d039e0897ce97e3b032b355ca42e5a3ede Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Thu, 19 Feb 2026 19:31:04 +0000 Subject: [PATCH 2/7] Fixup --- index.rst | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/index.rst b/index.rst index e586c1cf1..6cf509945 100644 --- a/index.rst +++ b/index.rst @@ -237,22 +237,6 @@ In general this means everyone is expected to be open, considerate, and respectful of others no matter what their position is within the project. -.. toctree:: - :hidden: - :maxdepth: 3 - - getting-started/index - developer-workflow/index - triage/index - documentation/index - testing/index - development-tools/index - core-team/index - internals - versions - contrib/index - - Other interpreter implementations --------------------------------- @@ -280,6 +264,22 @@ developers to work on them. Some major examples that may be of interest are: and learning to code on low-cost microcontroller boards. +.. toctree:: + :hidden: + :maxdepth: 3 + + getting-started/index + developer-workflow/index + triage/index + documentation/index + testing/index + development-tools/index + core-team/index + internals + versions + contrib/index + + .. _Buildbot status: https://buildbot.python.org/#/ .. _python.org maintenance: https://pythondotorg.readthedocs.io/ .. _Python: https://www.python.org/ From 54a817ca699b28d2a5671bb5669ec4ca81a8972e Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Mon, 2 Mar 2026 16:38:40 +0000 Subject: [PATCH 3/7] Ned's suggestion for table --- index.rst | 43 +++++++++++++++++++++++++++++++------------ 1 file changed, 31 insertions(+), 12 deletions(-) diff --git a/index.rst b/index.rst index 6cf509945..57a9293ac 100644 --- a/index.rst +++ b/index.rst @@ -32,18 +32,37 @@ contributors through the process. Guide for contributing to Python: -======================== =================== -Code Documentation -======================== =================== -:ref:`setup` :ref:`docquality` -:ref:`help` :ref:`documenting` -:ref:`pullrequest` :ref:`style-guide` -:ref:`runtests` :ref:`rst-primer` -:ref:`fixingissues` :ref:`translating` -:ref:`communication` :ref:`devguide` -:ref:`gitbootcamp` -:ref:`devcycle` -======================== =================== +.. list-table:: + :widths: 10 10 10 + :header-rows: 1 + + * - Documentation + - Code + - Triage + * - + * :ref:`docquality` + * :ref:`documenting` + * :ref:`style-guide` + * :ref:`rst-primer` + * :ref:`translating` + * :ref:`devguide` + - + * :ref:`setup` + * :ref:`help` + * :ref:`pullrequest` + * :ref:`runtests` + * :ref:`fixingissues` + * :ref:`communication` + * :ref:`gitbootcamp` + * :ref:`devcycle` + - + * :ref:`tracker` + * :ref:`triaging` + * :ref:`helptriage` + * :ref:`experts` + * :ref:`labels` + * :ref:`gh-faq` + * :ref:`triage-team` We **recommend** that the documents in this guide be read as needed. You can stop where you feel comfortable and begin contributing immediately without From a41054c1d6bc4d8793a749951b19f8bed4cb97d5 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> Date: Mon, 2 Mar 2026 17:32:01 +0000 Subject: [PATCH 4/7] Apply suggestions from code review Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> --- index.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/index.rst b/index.rst index 57a9293ac..886d16595 100644 --- a/index.rst +++ b/index.rst @@ -15,7 +15,7 @@ Python Developer's Guide .. highlight:: bash This guide is a comprehensive resource for :ref:`contributing ` -to various areas of Python_ -- for both new and experienced contributors. It is +to Python_ -- for both new and experienced contributors. It is :ref:`maintained ` by the same community that maintains Python. We welcome your contributions! @@ -77,8 +77,8 @@ of excellent guides at `Open Source Guides `__. .. _quick-reference: -CPython contribution quick reference ------------------------------------- +Quick reference +--------------- Here are the basic steps needed to get set up and open a pull request. This is meant as a checklist, once you know the basics. For complete @@ -233,7 +233,7 @@ Additional resources * :ref:`internals` * :ref:`grammar` -* Tool support: +* Tool support * :ref:`gdb` * :ref:`clang` From 4e639e30217cfccfc1dd8bdc6441bf05c9385d69 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Mon, 2 Mar 2026 17:35:41 +0000 Subject: [PATCH 5/7] Hugo's other suggestions --- index.rst | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/index.rst b/index.rst index 886d16595..6098951c7 100644 --- a/index.rst +++ b/index.rst @@ -156,7 +156,7 @@ instructions please see the :ref:`setup guide `. .. code-block:: shell pre-commit install - pre-commit run + pre-commit run --all-files See :ref:`install-pre-commit` for more details. If everything is ok, commit. @@ -216,7 +216,7 @@ Key resources * `Browse online `__ * `Download a snapshot of the 'main' branch `__ -* :pep:`PEPs <0>` (Python Enhancement Proposals) +* PEPs_ (Python Enhancement Proposals) * :ref:`help` * :ref:`developers` * :ref:`gitbootcamp` @@ -283,8 +283,10 @@ developers to work on them. Some major examples that may be of interest are: and learning to code on low-cost microcontroller boards. +Full table of contents +---------------------- + .. toctree:: - :hidden: :maxdepth: 3 getting-started/index @@ -300,6 +302,7 @@ developers to work on them. Some major examples that may be of interest are: .. _Buildbot status: https://buildbot.python.org/#/ +.. _PEPs: https://peps.python.org/ .. _python.org maintenance: https://pythondotorg.readthedocs.io/ .. _Python: https://www.python.org/ .. _Core Python Mentorship: https://www.python.org/dev/core-mentorship/ From 391f0e914574120d04f0113b916553af37d14333 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Mon, 2 Mar 2026 17:50:31 +0000 Subject: [PATCH 6/7] Hugo's other other suggestion --- index.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/index.rst b/index.rst index 6098951c7..be264f2de 100644 --- a/index.rst +++ b/index.rst @@ -214,7 +214,8 @@ Key resources * Source code * `Browse online `__ - * `Download a snapshot of the 'main' branch `__ + * `Download a snapshot `__ + of the ``main`` branch * PEPs_ (Python Enhancement Proposals) * :ref:`help` From 8f530ef759ce33e34637a56525f788121c189bd1 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> Date: Mon, 2 Mar 2026 18:55:23 +0000 Subject: [PATCH 7/7] Apply suggestions from code review Co-authored-by: Ned Batchelder --- index.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/index.rst b/index.rst index be264f2de..1a1a6486f 100644 --- a/index.rst +++ b/index.rst @@ -25,7 +25,7 @@ community that maintains Python. We welcome your contributions! Contributing ------------ -We encourage everyone to contribute to Python and that's why we have put up this +We encourage everyone to contribute to Python. To help you, we have put up this developer's guide. If you still have questions after reviewing the material in this guide, then the `Core Python Mentorship`_ group is available to help guide new contributors through the process. @@ -64,11 +64,11 @@ Guide for contributing to Python: * :ref:`gh-faq` * :ref:`triage-team` -We **recommend** that the documents in this guide be read as needed. You +We **recommend** that sections of this guide be read as needed. You can stop where you feel comfortable and begin contributing immediately without -reading and understanding these documents all at once. If you do choose to skip -around within the documentation, be aware that it is written assuming preceding -documentation has been read so you may find it necessary to backtrack to fill in +reading and understanding everything. If you do choose to skip +around within the guide, be aware that sections build on each other, +so you may find it necessary to backtrack to fill in missing concepts and terminology. A number of individuals from the Python community have contributed to a series