Skip to content

Restructure index page #1748

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
StanFromIreland wants to merge 9 commits into
base: main
Choose a base branch
from
+105 −126
Open

Restructure index page #1748

Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
ee4b7b7
Restructure index
StanFromIreland Feb 19, 2026
6cd0e1d
Fixup
StanFromIreland Feb 19, 2026
54a817c
Ned's suggestion for table
StanFromIreland Mar 2, 2026
a41054c
Apply suggestions from code review
StanFromIreland Mar 2, 2026
4e639e3
Hugo's other suggestions
StanFromIreland Mar 2, 2026
391f0e9
Hugo's other other suggestion
StanFromIreland Mar 2, 2026
8f530ef
Apply suggestions from code review
StanFromIreland Mar 2, 2026
cc71bfa
Petr's review
StanFromIreland Mar 4, 2026
6e18fd9
Remove pre-commit (for now)
StanFromIreland Mar 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
231 changes: 105 additions & 126 deletions index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,14 +17,72 @@ Python Developer's Guide
This guide is a comprehensive resource for :ref:`contributing <contributing>`
to Python_ -- for both new and experienced contributors. It is
:ref:`maintained <devguide>` 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. 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.

Guide for contributing to Python:

.. 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 sections of this guide be read as needed. You
can stop where you feel comfortable and begin contributing immediately without
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
of excellent guides at `Open Source Guides <https://opensource.guide/>`__.
For example,
`How to Contribute to Open Source <https://opensource.guide/how-to-contribute/>`__.


.. _quick-reference:

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 <setup>`.

Expand Down Expand Up @@ -76,9 +134,10 @@ instructions please see the :ref:`setup guide <setup>`.

./python.exe -m test -j8

Note: :ref:`Most <mac-python.exe>` macOS systems use
:file:`./python.exe` in order to avoid filename conflicts with
the ``Python`` directory.
.. note::
:ref:`Most <mac-python.exe>` macOS systems use
:file:`./python.exe` in order to avoid filename conflicts with
the ``Python`` directory.

.. tab:: Windows

Expand All @@ -91,40 +150,18 @@ instructions please see the :ref:`setup guide <setup>`.
git checkout -b fix-issue-12345 main

If an issue does not already exist, please `create it
<https://github.com/python/cpython/issues>`__.?target=https://github.com 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

.. tab:: macOS

.. code-block:: shell

make patchcheck

.. tab:: Windows

.. code-block:: dosbatch

.\python.bat Tools\patchcheck\patchcheck.py

If everything is ok, commit.
<https://github.com/python/cpython/issues>`__.?target=https://github.com Trivial issues (for example, typos) do
not require an issue.

7. Push the branch on your fork on GitHub and :ref:`create a pull request
<pullrequest>`. Include the issue number using ``gh-NNNN`` in the
pull request description. For example:
<pullrequest>`. 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 <https://blurb-it.herokuapp.com/>`__,
or the :pypi:`blurb` tool and its ``blurb add``
command. Please read more about ``blurb`` in its
Expand All @@ -136,58 +173,6 @@ instructions please see the :ref:`setup guide <setup>`.
Agreement (CLA) as described in the :ref:`Licensing <cla>` 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 <https://opensource.guide/>`__.

Core developers and contributors alike will find the following guides useful:

* `How to Contribute to Open Source <https://opensource.guide/how-to-contribute/>`__
* `Building Welcoming Communities <https://opensource.guide/building-community/>`__

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
----------------------------------
Expand All @@ -206,36 +191,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
-------------

Expand All @@ -252,11 +207,14 @@ Key resources
* Source code

* `Browse online <https://github.com/python/cpython/>`__?target=https://github.com
* `Snapshot of the *main* branch <https://github.com/python/cpython/archive/main.zip>`__
* `Download a snapshot <https://github.com/python/cpython/archive/main.zip>`__
of the ``main`` branch

* PEPs_ (Python Enhancement Proposals)
* `The Python Discourse <https://discuss.python.org/>`__
* :ref:`help`
* :ref:`developers`
* :ref:`gitbootcamp`


.. _resources:
Expand All @@ -274,30 +232,52 @@ Additional resources

* :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 <https://wiki.python.org/moin/PythonEditors>`__
* Various tools with configuration files as found in the
:cpy-file:`Misc/` directory

* `python.org maintenance`_
* :ref:`Search this guide <search>`


Code of conduct
---------------

Please note that all interactions on
`Python Software Foundation <https://www.python.org/psf-landing/>`__-supported
infrastructure is `covered
<https://www.python.org/psf/records/board/minutes/2014-01-06/#management-of-the-psfs-web-properties>`__
by the `PSF Code of Conduct <https://policies.python.org/python.org/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
-------------------------
Comment on lines -291 to -292
Copy link
Member

@encukou encukou Mar 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a “soft redirect” for people who have #status-of-python-branches bookmarked. Can we keep it?

Copy link
Member

@hugovk hugovk Mar 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think ~4 years is long enough.

Thinking of the old flow:

If someone has still been going through all that rigmarole for 4 years and hasn't updated their bookmarks, I think removing this is a good prompt.

Copy link
Member Author

@StanFromIreland StanFromIreland Mar 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree with Hugo, I'll remove it unless you feel strongly about keeping it.

We could add a redirect, but it would be quite messy, as such I don't think its worth it.


Moved to :ref:`versions`
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.


.. _contents:

Expand All @@ -318,8 +298,8 @@ 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

.. _Buildbot status: https://buildbot.python.org/
.. _PEPs: https://peps.python.org/
.. _python.org maintenance: https://pythondotorg.readthedocs.io/
.. _Python: https://www.python.org/
Expand All @@ -328,7 +308,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/?target=https://github.com
.. _MicroPython: https://micropython.org/
.. _CircuitPython: https://circuitpython.org/
.. _Issue tracker: https://github.com/python/cpython/issues?target=https://github.com
Loading