From 6c418284cf253a2a586ae2aa7f2f12d108df1d87 Mon Sep 17 00:00:00 2001 From: Tam Nguyen Duc <1218621+tamnd@users.noreply.github.com> Date: Tue, 21 Apr 2026 00:21:27 +0700 Subject: [PATCH 01/85] Add Vietnamese translation details (#1789) Co-authored-by: Stan Ulbrych --- documentation/translations/translating.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/documentation/translations/translating.rst b/documentation/translations/translating.rst index e8e3dc32f4..eb3eb164a9 100644 --- a/documentation/translations/translating.rst +++ b/documentation/translations/translating.rst @@ -118,6 +118,10 @@ For more details about translations and their progress, see - Dmytro Kazanzhy (:github-user:`kazanzhy`, `email `__) - :github:`GitHub `, `Transifex `_ + * - Vietnamese (vi) + - Duc-Tam Nguyen (:github-user:`tamnd`) + - :github:`GitHub `, + `Transifex `_ How to get help From f67335b3f26b53da1b1dabaa02632a3c64240aeb Mon Sep 17 00:00:00 2001 From: Hood Chatham Date: Thu, 23 Apr 2026 07:17:46 -0700 Subject: [PATCH 02/85] Minor improvements to the Emscripten instructions (#1795) * Minor improvements to the Emscripten instructions * Remove incorrect statement about ccache * Add note about nvm * link to nvm * Document `--host-runner` argument as alternative to nvm * lint --- getting-started/setup-building.rst | 61 +++++++++++++++++++----------- 1 file changed, 38 insertions(+), 23 deletions(-) diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index 6acc7ee578..f1a309f58c 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -522,39 +522,52 @@ The simplest way to build Emscripten is to run: .. code-block:: sh - python3 Platforms/emscripten build all --emsdk-cache=./cross-build/emsdk + export EMSDK_CACHE=$PWD/cross-build/emsdk + python3 Platforms/emscripten install-emscripten + python3 Platforms/emscripten build all -This will: +``install-emscripten`` downloads and installs the version of the Emscripten SDK +required, placing it in the ``EMSDK_CACHE`` directory. +``build all`` will: 1. Build a copy of Python that can run on the host machine (the "build" python); -2. Download a copy of the Emscripten SDK matching the version required by the - version of Python being compiled; -3. Ensure that a required version of Node is installed; -4. Download the code for all the binary dependencies of Python (such as - ``libFFI`` and ``xz``), and compile them for Emscripten; and -5. Build a copy of Python that can run on Emscripten (the "host" python). - -If you omit the ``--emsdk-cache`` environment variable, the build script will +2. Use nvm_ to ensure that the needed version of Node is installed; +3. Download the code for all the binary dependencies of Python (such as + ``libffi`` and ``mpdecimal``), and compile them for Emscripten; and +4. Build a copy of Python that can run on Emscripten (the "host" python). + +The built binary dependencies are cached inside the Emscripten cache directory. +Once built for a given Emscripten version, they will not be rebuilt on +subsequent runs unless there is a change in the version or build script for the +dependency. + +It is assumed that nvm_ is installed in ``${HOME}/.nvm``. If you don't have nvm +installed or don't want to use it, you can pass ``--host-runner node`` to the +``build`` command. The argument should either be the name of an executable that +can be found on the ``PATH`` or a relative or absolute path to an executable. + +If you omit the ``EMSDK_CACHE`` environment variable, the build script will assume that the current environment has the Emscripten tools available. You are responsible for downloading and activating those tools in your environment. The version of Emscripten and Node that is required to build Python is defined in the :cpy-file:`Platforms/emscripten/config.toml` configuration file. -There are three environment variables that can be used to control the operation of +There are two environment variables that can be used to control the operation of the ``Platforms/emscripten`` build script: -* ``EMSDK_CACHE`` controls the location of the emscripten SDK. You can use this instead - environment variable instead of passing the ``--emsdk-cache`` flag. -* ``CACHE_DIR`` defines the location where downloaded artefacts, such - as precompiled ``libFFI`` and ``xz`` binaries, will be stored. -* ``CROSS_BUILD_DIR`` defines the name of the ``cross-build`` directory - that will be used for builds. This can be useful if you need to maintain - builds of multiple versions of Python. +* ``EMSDK_CACHE`` (or the ``--emsdk-cache`` flag) controls the location of the + Emscripten SDK cache directory. You can use this environment variable instead + of passing the ``--emsdk-cache`` flag. When set, the build script will + validate that the required Emscripten version is present in the cache and will + exit with an error if it is not; run ``install-emscripten`` to populate the + cache. +* ``CROSS_BUILD_DIR`` (or the ``--cross-build-dir`` flag) defines the location + of the ``cross-build`` directory that will be used for builds. This can be + useful if you need to maintain builds of multiple versions of Python + side by side. It is possible (but not necessary) to enable ``ccache`` for Emscripten builds -by setting the ``EM_COMPILER_WRAPPER`` environment, but this step will only -take effect if it is done **after** ``emsdk_env.sh`` is sourced (otherwise, the -sourced script removes the environment variable): +by setting the ``EM_COMPILER_WRAPPER`` environment variable: .. code-block:: sh @@ -571,8 +584,9 @@ Emscripten build in ``cross-build/build`` and ``cross-build/wasm32-emscripten/build/python/``, respectively. The ``Platforms/emscripten`` script has a number of other entry points that allow for -fine-grained execution of each part of an iOS build; run ``python3 -Platforms/emscripten --help`` for more details. +fine-grained execution of each part of an Emscripten build; run +``python3 Platforms/emscripten --help`` for more details. + Once the build is complete, you can run Python code using: @@ -592,6 +606,7 @@ through web browsers) are available in the CPython repository at .. _Emscripten: https://emscripten.org/ .. _WebAssembly: https://webassembly.org +.. _nvm: https://github.com/nvm-sh/nvm#intro Android ------- From f9c78a9cb84f47d98560325de8be381f9b5f34f7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bartosz=20S=C5=82awecki?= Date: Sat, 25 Apr 2026 20:34:15 +0200 Subject: [PATCH 03/85] Add multicultural communication guidelines (#1788) * gh-1447: Add multicultural communication guidelines Add a new section covering good-faith assumptions, use of translation and language tools, collaborative phrasing, and patience/mentoring for contributors communicating across cultural and linguistic backgrounds. * Apply suggestions from review Co-authored-by: Carol Willing * Fix caps, wrap at ~80 Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --------- Co-authored-by: Carol Willing Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> --- developer-workflow/communication-channels.rst | 32 +++++++++++++++++++ triage/issue-tracker.rst | 3 +- 2 files changed, 34 insertions(+), 1 deletion(-) diff --git a/developer-workflow/communication-channels.rst b/developer-workflow/communication-channels.rst index 78fbf21dff..a45003c783 100644 --- a/developer-workflow/communication-channels.rst +++ b/developer-workflow/communication-channels.rst @@ -22,6 +22,38 @@ in return. .. _Diversity Statement: https://www.python.org/psf/diversity/ +.. _multicultural-communication: + +Communicating across cultures and languages +=========================================== + +Not every contributor writes English as a first language, and phrasing that +feels neutral in one culture can read as blunt or rude in another. + +**Practice active listening.** Try to focus on understanding the message before reacting. + +**Confirm understanding.** Ask open-ended questions and paraphrase to avoid +misunderstandings. If you're unsure what someone meant, ask: "I want to make +sure I understand: are you saying X?" + +**Use translation tools freely.** If English isn't your first language, +translation software or AI tools may help you check that your message has the +tone you intend. Getting the phrasing wrong can make a reasonable point sound +more aggressive than it is. + +**Watch out for rhetorical questions.** They read as hostile in text even when +that's not the intent at all: + +* Instead of "Why do you think it is wrong?!", try "That doesn't sound right + to me. Here's why: …" +* Instead of "Did you even read the docs?", try "The relevant documentation + is at …" + +**Be patient with newcomers.** If someone doesn't know how things work here, +point them to the right docs or give them the context they need. Criticism +without guidance isn't helpful. + + .. _mailinglists: Mailing lists diff --git a/triage/issue-tracker.rst b/triage/issue-tracker.rst index 4dd0815e4c..31673d9435 100644 --- a/triage/issue-tracker.rst +++ b/triage/issue-tracker.rst @@ -124,7 +124,8 @@ Disagreement with a resolution on the issue tracker As humans, we will have differences of opinions from time to time. First and foremost, please be respectful that care, thought, and volunteer time went into -the resolution. +the resolution. Keep in mind that contributors come from many different cultural +and linguistic backgrounds; see :ref:`multicultural-communication`. With this in mind, take some time to consider any comments made in association with the resolution of the issue. On reflection, the resolution steps may seem From abdd4c6903977f38f3efe94789598344019770ed Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bartosz=20S=C5=82awecki?= Date: Sat, 25 Apr 2026 20:36:13 +0200 Subject: [PATCH 04/85] Recommend `--config-cache` for `./configure` (#1794) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * gh-1547: Recommend --config-cache for configure Add ``--config-cache`` to all relevant ``./configure`` invocations in the front page and setup-building guide, matching what the WASM commands already do. Add a brief explanation noting that ``config.cache`` should be deleted when switching compilers or significantly changing the build environment. * gh-1547: Also mention --cache-file=config.cache alias * gh-1547: Remove --config-cache from platform-specific configure commands * gh-1547: Restructure --config-cache as optional speedup tip * gh-1547: Use tip admonition for --config-cache * gh-1547: Add --config-cache to macOS platform-specific configure commands * Apply suggestions from review Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Co-authored-by: Bartosz Sławecki --------- Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> --- getting-started/setup-building.rst | 21 +++++++++++++++++---- index.rst | 4 ++-- 2 files changed, 19 insertions(+), 6 deletions(-) diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index f1a309f58c..11915e3e58 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -191,6 +191,15 @@ Configuration is typically:: More flags are available to ``configure``, but this is the minimum you should do to get a pydebug build of CPython. +.. tip:: + To speed up repeated ``configure`` runs, use ``--config-cache`` (equivalent to ``--cache-file=config.cache``, short: ``-C``):: + + $ ./configure --config-cache --with-pydebug + + This caches results in a :file:`config.cache` file. If you switch compilers or + significantly change your build environment, delete :file:`config.cache` before + re-running ``configure``. + .. note:: You might need to run ``make clean`` before or after re-running ``configure`` in a particular build directory. @@ -856,7 +865,8 @@ some of CPython's modules (for example, ``zlib``). $ GDBM_CFLAGS="-I$(brew --prefix gdbm)/include" \ GDBM_LIBS="-L$(brew --prefix gdbm)/lib -lgdbm" \ - ./configure --with-pydebug \ + ./configure --config-cache \ + --with-pydebug \ --with-openssl="$(brew --prefix openssl@3)" .. tab:: Python 3.10 @@ -865,7 +875,8 @@ some of CPython's modules (for example, ``zlib``). $ CPPFLAGS="-I$(brew --prefix gdbm)/include -I$(brew --prefix xz)/include" \ LDFLAGS="-L$(brew --prefix gdbm)/lib -L$(brew --prefix xz)/lib" \ - ./configure --with-pydebug \ + ./configure --config-cache \ + --with-pydebug \ --with-openssl="$(brew --prefix openssl@3)" \ --with-tcltk-libs="$(pkg-config --libs tcl tk)" \ --with-tcltk-includes="$(pkg-config --cflags tcl tk)" \ @@ -887,7 +898,8 @@ some of CPython's modules (for example, ``zlib``). $ GDBM_CFLAGS="-I$(dirname $(dirname $(which port)))/include" \ GDBM_LIBS="-L$(dirname $(dirname $(which port)))/lib -lgdbm" \ - ./configure --with-pydebug \ + ./configure --config-cache \ + --with-pydebug \ --with-system-libmpdec .. tab:: Python 3.11-3.12 @@ -896,7 +908,8 @@ some of CPython's modules (for example, ``zlib``). $ GDBM_CFLAGS="-I$(dirname $(dirname $(which port)))/include" \ GDBM_LIBS="-L$(dirname $(dirname $(which port)))/lib -lgdbm" \ - ./configure --with-pydebug + ./configure --config-cache \ + --with-pydebug And finally, run ``make``:: diff --git a/index.rst b/index.rst index 18aca244e1..4a478e7cc1 100644 --- a/index.rst +++ b/index.rst @@ -95,13 +95,13 @@ instructions please see the :ref:`setup guide `. .. code-block:: shell - ./configure --with-pydebug && make -j $(nproc) + ./configure --config-cache --with-pydebug && make -j $(nproc) .. tab:: macOS .. code-block:: shell - ./configure --with-pydebug && make -j8 + ./configure --config-cache --with-pydebug && make -j8 .. tab:: Windows From 4f8cdf35158ee256b7df468051429c9db8a41891 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Wed, 29 Apr 2026 22:53:22 +0300 Subject: [PATCH 05/85] PSRT: Add link to report security issues (#1796) --- developer-workflow/psrt.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/developer-workflow/psrt.rst b/developer-workflow/psrt.rst index c2501e44b7..6b53700d89 100644 --- a/developer-workflow/psrt.rst +++ b/developer-workflow/psrt.rst @@ -4,6 +4,8 @@ Python Security Response Team (PSRT) The Python Security Response Team (PSRT) is responsible for handling vulnerability reports for CPython and pip. +To report security issues: https://www.python.org/dev/security/ + Members ------- From d8483e5e416242a7f4cb966ee82ac28e28145770 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Sat, 2 May 2026 20:57:49 +0800 Subject: [PATCH 06/85] Bump the pip group with 6 updates (#1798) Updates the requirements on [furo](https://github.com/pradyunsg/furo), [sphinx-autobuild](https://github.com/sphinx-doc/sphinx-autobuild), [sphinx-inline-tabs](https://github.com/pradyunsg/sphinx-inline-tabs), [sphinx-notfound-page](https://github.com/readthedocs/sphinx-notfound-page), [sphinx-copybutton](https://github.com/executablebooks/sphinx-copybutton) and [sphinx](https://github.com/sphinx-doc/sphinx) to permit the latest version. Updates `furo` to 2025.12.19 - [Release notes](https://github.com/pradyunsg/furo/releases) - [Changelog](https://github.com/pradyunsg/furo/blob/main/docs/changelog.md) - [Commits](https://github.com/pradyunsg/furo/compare/2022.06.04...2025.12.19) Updates `sphinx-autobuild` to 2025.8.25 - [Release notes](https://github.com/sphinx-doc/sphinx-autobuild/releases) - [Changelog](https://github.com/sphinx-doc/sphinx-autobuild/blob/main/NEWS.rst) - [Commits](https://github.com/sphinx-doc/sphinx-autobuild/compare/2024.09.19...2025.08.25) Updates `sphinx-inline-tabs` to 2025.12.21.14 - [Commits](https://github.com/pradyunsg/sphinx-inline-tabs/compare/2023.04.21...2025.12.21.14) Updates `sphinx-notfound-page` to 1.1.0 - [Changelog](https://github.com/readthedocs/sphinx-notfound-page/blob/main/CHANGELOG.rst) - [Commits](https://github.com/readthedocs/sphinx-notfound-page/compare/1.0.0...1.1.0) Updates `sphinx-copybutton` to 0.5.2 - [Release notes](https://github.com/executablebooks/sphinx-copybutton/releases) - [Changelog](https://github.com/executablebooks/sphinx-copybutton/blob/master/CHANGELOG.md) - [Commits](https://github.com/executablebooks/sphinx-copybutton/compare/v0.3.3...v0.5.2) Updates `sphinx` to 9.1.0 - [Release notes](https://github.com/sphinx-doc/sphinx/releases) - [Changelog](https://github.com/sphinx-doc/sphinx/blob/master/CHANGES.rst) - [Commits](https://github.com/sphinx-doc/sphinx/compare/v8.2.3...v9.1.0) --- updated-dependencies: - dependency-name: furo dependency-version: 2025.12.19 dependency-type: direct:production dependency-group: pip - dependency-name: sphinx-autobuild dependency-version: 2025.8.25 dependency-type: direct:production dependency-group: pip - dependency-name: sphinx-inline-tabs dependency-version: 2025.12.21.14 dependency-type: direct:production dependency-group: pip - dependency-name: sphinx-notfound-page dependency-version: 1.1.0 dependency-type: direct:production dependency-group: pip - dependency-name: sphinx-copybutton dependency-version: 0.5.2 dependency-type: direct:production dependency-group: pip - dependency-name: sphinx dependency-version: 9.1.0 dependency-type: direct:production dependency-group: pip ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- requirements.txt | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/requirements.txt b/requirements.txt index 3b40508f67..09d13a3fec 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,11 +1,11 @@ -furo>=2022.6.4 +furo>=2025.12.19 jinja2 linklint -sphinx-autobuild>=2024.9.19 -sphinx-inline-tabs>=2023.4.21 +sphinx-autobuild>=2025.8.25 +sphinx-inline-tabs>=2025.12.21.14 sphinx-lint==1.0.2 -sphinx-notfound-page>=1.0.0 -sphinx_copybutton>=0.3.3 +sphinx-notfound-page>=1.1.0 +sphinx_copybutton>=0.5.2 sphinxext-opengraph>=0.13.0 sphinxext-rediraffe -Sphinx>=8.2.3 +Sphinx>=9.1.0 From 271fc3edb6cbf5eefb8fb20a5183fae38dca4778 Mon Sep 17 00:00:00 2001 From: Krishna Chaitanya <141550576+XChaitanyaX@users.noreply.github.com> Date: Thu, 7 May 2026 22:55:33 +0530 Subject: [PATCH 07/85] Add powershell example for 'git pr' alias (#1666) --- getting-started/git-boot-camp.rst | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/getting-started/git-boot-camp.rst b/getting-started/git-boot-camp.rst index 6376a190ca..47f49f3d69 100644 --- a/getting-started/git-boot-camp.rst +++ b/getting-started/git-boot-camp.rst @@ -462,12 +462,19 @@ Or set up a Git alias: git config --global alias.pr '!sh -c "git fetch upstream pull/${1}/head:pr_${1} && git switch pr_${1}" -' -.. tab:: Windows +.. tab:: Windows cmd .. code-block:: dosbatch git config --global alias.pr "!sh -c 'git fetch upstream pull/${1}/head:pr_${1} && git switch pr_${1}' -" +.. tab:: Windows Powershell + + .. code-block:: shell + + git config --global alias.pr '!f() { git fetch upstream pull/$1/head:pr_$1 && git checkout pr_$1; }; f' + + The alias only needs to be done once. After the alias is set up, you can get a local copy of a pull request as follows:: From a0526fd95139cbd8c16c194ae6e1d7cfd8f08bfb Mon Sep 17 00:00:00 2001 From: Chris Eibl <138194463+chris-eibl@users.noreply.github.com> Date: Tue, 12 May 2026 09:05:12 +0200 Subject: [PATCH 08/85] add Chris Eibl to core-team.csv (#1799) --- core-team/core-team.csv | 1 + 1 file changed, 1 insertion(+) diff --git a/core-team/core-team.csv b/core-team/core-team.csv index 46dfd81530..b7f25e1618 100644 --- a/core-team/core-team.csv +++ b/core-team/core-team.csv @@ -1,3 +1,4 @@ +Chris Eibl,chris-eibl,2026-05-10,, Stan Ulbrych,StanFromIreland,2026-03-26,, Itamar Oren,itamaro,2026-02-16,, Emma Smith,emmatyping,2025-07-31,, From e8183172bba909c1b4af6e0dbb01d8775b1e7716 Mon Sep 17 00:00:00 2001 From: Seth Larson Date: Wed, 13 May 2026 14:31:23 -0500 Subject: [PATCH 09/85] Add Kirill Podoprigora and Damian Shaw to the PSRT (#1800) --- developer-workflow/psrt.csv | 2 ++ 1 file changed, 2 insertions(+) diff --git a/developer-workflow/psrt.csv b/developer-workflow/psrt.csv index da67432d9b..d794029825 100644 --- a/developer-workflow/psrt.csv +++ b/developer-workflow/psrt.csv @@ -2,6 +2,7 @@ Adam Turner,AA-Turner, Barry Warsaw,warsaw,Admin Bénédikt Tran,picnixz, Benjamin Peterson,benjaminp, +Damian Shaw,notatallshaw, Donald Stufft,dstufft, Dustin Ingram,di, Ee Durbin,ewdurbin,Admin @@ -10,6 +11,7 @@ Glyph Lefkowitz,glyph, Gregory P. Smith,gpshead, Hugo van Kemenade,hugovk,Release Manager Jacob Coffee,JacobCoffee, +Kirill Podoprigora,eclips4, Larry Hastings,larryhastings, Łukasz Langa,ambv,Release Manager Ned Deily,ned-deily,"Admin, Release Manager" From 2a14b3a5483b06cba4696ec2eced07ae455b1e00 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Fri, 15 May 2026 18:10:19 +0300 Subject: [PATCH 10/85] Install Homebrew dependencies via Brewfile (#1802) --- getting-started/setup-building.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index 11915e3e58..04e9a2143c 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -857,7 +857,7 @@ some of CPython's modules (for example, ``zlib``). For **Homebrew**, install dependencies using ``brew``:: - $ brew install pkg-config openssl@3 xz gdbm tcl-tk mpdecimal zstd + $ brew bundle --file=Misc/Brewfile .. tab:: Python 3.11+ From f890063d279a53b5f51e282e4a51d243193b8798 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Sat, 16 May 2026 11:43:28 +0100 Subject: [PATCH 11/85] Add an 'OSS-Fuzz for CPython' overview (#1801) Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> --- testing/index.rst | 1 + testing/oss-fuzz.rst | 55 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 56 insertions(+) create mode 100644 testing/oss-fuzz.rst diff --git a/testing/index.rst b/testing/index.rst index 55bdd3d08b..6e65c5fdf9 100644 --- a/testing/index.rst +++ b/testing/index.rst @@ -10,5 +10,6 @@ Testing and buildbots run-write-tests silence-warnings coverage + oss-fuzz buildbots new-buildbot-worker diff --git a/testing/oss-fuzz.rst b/testing/oss-fuzz.rst new file mode 100644 index 0000000000..ec2449a4fd --- /dev/null +++ b/testing/oss-fuzz.rst @@ -0,0 +1,55 @@ +OSS-Fuzz for CPython +==================== + +CPython uses `OSS-Fuzz `__, Google's +continuous fuzzing service for open-source projects, to find bugs and +security vulnerabilities by feeding semi-random data to various APIs. + +CPython has two OSS-Fuzz projects: + +* `cpython3 `__: + The fuzz targets, seed corpora, and dictionaries can be found in the + :cpy-file:`Modules/_xxtestfuzz/` directory of CPython. This project + is maintained for existing fuzz targets; add new targets to + ``python3-libraries``. + +* `python3-libraries `__: + The fuzz targets, seed corpora, and dictionaries can be found in the + :github:`python/library-fuzzers` repository. Access to the repository is + managed through the `@python/fuzzers + `__ team on GitHub. + +OSS-Fuzz bug reports are private when filed, so access to crash details and +reproducer test cases is limited to those listed in the ``auto_ccs`` fields of +the OSS-Fuzz project configuration files. Those listed can log into +https://oss-fuzz.com/ with their Google account to view crash details, +reproducer test cases, and project statistics. +If you need access, contact the ``@python/fuzzers`` team. +Completed issues, and issues that remain unresolved after 90 days, are publicly +visible in the `OSS-Fuzz issue tracker +`__. + +Coverage and target statistics are available in the OSS-Fuzz Introspector +project profiles for `cpython3 `__ and +`python3-libraries `__. + +In addition, `CIFuzz `__ +runs the fuzz targets on GitHub Actions for PRs to the ``main`` branch changing +relevant files. + +.. seealso:: + + The `libFuzzer `__ documentation for + details about the fuzzing engine used by OSS-Fuzz. + + +Adding new targets +------------------ + +Add new targets to the ``python3-libraries`` project. For more +information, see the documentation in the :github:`python/library-fuzzers` +repository. + +If the new target covers a standard library module, update the relevant CIFuzz +path configuration so pull requests touching that module trigger fuzzing. See +the ``LIBRARY_FUZZER_PATHS`` set in :cpy-file:`Tools/build/compute-changes.py`. From 42d2e0f2f971c467a98ee09f0773538928f8e72d Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Wed, 20 May 2026 18:05:02 +0300 Subject: [PATCH 12/85] Create 'Security' section and move the PSRT and SBOM pages there (#1805) --- .github/CODEOWNERS | 2 +- conf.py | 3 +++ developer-workflow/index.rst | 2 -- index.rst | 1 + security/index.rst | 11 +++++++++++ {developer-workflow => security}/psrt-emeritus.csv | 0 {developer-workflow => security}/psrt.csv | 0 {developer-workflow => security}/psrt.rst | 0 {developer-workflow => security}/sbom.rst | 0 9 files changed, 16 insertions(+), 3 deletions(-) create mode 100644 security/index.rst rename {developer-workflow => security}/psrt-emeritus.csv (100%) rename {developer-workflow => security}/psrt.csv (100%) rename {developer-workflow => security}/psrt.rst (100%) rename {developer-workflow => security}/sbom.rst (100%) diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 06213bdf40..9c2d9d9e4a 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -5,4 +5,4 @@ # https://git-scm.com/docs/gitignore#_pattern_format # PSRT member list owned by PSRT admins. -developer-workflow/psrt*.csv @warsaw @ewdurbin @ned-deily @sethmlarson +security/psrt*.csv @warsaw @ewdurbin @ned-deily @sethmlarson diff --git a/conf.py b/conf.py index 1d88937227..7cf2e98d4d 100644 --- a/conf.py +++ b/conf.py @@ -147,6 +147,9 @@ "langchanges.rst": "developer-workflow/lang-changes.rst", "porting.rst": "developer-workflow/porting.rst", "stdlibchanges.rst": "developer-workflow/stdlib.rst", + # Security + "developer-workflow/psrt.rst": "security/psrt.rst", + "developer-workflow/sbom.rst": "security/sbom.rst", # Documentation "docquality.rst": "documentation/help-documenting.rst", "documenting.rst": "documentation/start-documenting.rst", diff --git a/developer-workflow/index.rst b/developer-workflow/index.rst index 9919398e62..e04fc8a8b3 100644 --- a/developer-workflow/index.rst +++ b/developer-workflow/index.rst @@ -15,5 +15,3 @@ Development workflow c-api grammar porting - sbom - psrt diff --git a/index.rst b/index.rst index 4a478e7cc1..a7f1ff016a 100644 --- a/index.rst +++ b/index.rst @@ -288,6 +288,7 @@ Full table of contents testing/index development-tools/index core-team/index + security/index internals versions diff --git a/security/index.rst b/security/index.rst new file mode 100644 index 0000000000..cbc1eb4e46 --- /dev/null +++ b/security/index.rst @@ -0,0 +1,11 @@ +.. _security: + +======== +Security +======== + +.. toctree:: + :maxdepth: 5 + + psrt + sbom diff --git a/developer-workflow/psrt-emeritus.csv b/security/psrt-emeritus.csv similarity index 100% rename from developer-workflow/psrt-emeritus.csv rename to security/psrt-emeritus.csv diff --git a/developer-workflow/psrt.csv b/security/psrt.csv similarity index 100% rename from developer-workflow/psrt.csv rename to security/psrt.csv diff --git a/developer-workflow/psrt.rst b/security/psrt.rst similarity index 100% rename from developer-workflow/psrt.rst rename to security/psrt.rst diff --git a/developer-workflow/sbom.rst b/security/sbom.rst similarity index 100% rename from developer-workflow/sbom.rst rename to security/sbom.rst From 0ee1a984f1b0bbe588e103650f6d7b9523ae9ac6 Mon Sep 17 00:00:00 2001 From: Mariatta Date: Wed, 20 May 2026 20:22:02 -0700 Subject: [PATCH 13/85] Update guidelines on using GenAI (#1778) * Update guidelines on using GenAI * Update the title to clarify the purpose of this doc is to provide guidelines. * Add the Guidelines to the contributing table. * Fix the markup in rendering the table * Soften the wording about AI tool disclosure. * Moved the considerations to be earlier in the page. * Apply suggestions from code review * Add more explicit in the beginning that the person submitting issue or pr is responsible for its content. * adjust wording about being disrespectful and about reviewing the output always. * Rename the file to ai-tools.rst * Reformat to 80 chars max Co-authored-by: Gregory P. Smith Co-authored-by: Donghee Na Co-authored-by: devdanzin <74280297+devdanzin@users.noreply.github.com> Co-authored-by: Jacob Coffee Co-authored-by: Savannah Ostrowski Co-authored-by: Carol Willing --- conf.py | 2 +- getting-started/ai-tools.rst | 63 +++++++++++++++++++++++++++++++ getting-started/generative-ai.rst | 40 -------------------- getting-started/index.rst | 2 +- index.rst | 2 + 5 files changed, 67 insertions(+), 42 deletions(-) create mode 100644 getting-started/ai-tools.rst delete mode 100644 getting-started/generative-ai.rst diff --git a/conf.py b/conf.py index 7cf2e98d4d..2758938fe9 100644 --- a/conf.py +++ b/conf.py @@ -205,7 +205,7 @@ "contrib/project/github.rst": "index.rst", "contrib/project/governance.rst": "index.rst", "contrib/project/roles.rst": "index.rst", - "contrib/project/generative-ai.rst": "getting-started/generative-ai.rst", + "contrib/project/ai-tools.rst": "getting-started/ai-tools.rst", "contrib/project/outreach.rst": "index.rst", "contrib/project/directory-structure.rst": "getting-started/setup-building.rst", "contrib/project/index.rst": "index.rst", diff --git a/getting-started/ai-tools.rst b/getting-started/ai-tools.rst new file mode 100644 index 0000000000..ba92ea9e13 --- /dev/null +++ b/getting-started/ai-tools.rst @@ -0,0 +1,63 @@ +.. _ai-tools: + +============================= +Guidelines for using AI tools +============================= + +The person submitting an issue or PR is responsible for its content, +regardless of whether AI tools were used in its creation. Generative AI +tools can produce output quickly, but discretion, good judgment, and +critical thinking are the foundation of all good contributions. We value +good code, concise accurate documentation, and well scoped PRs without +unneeded code churn. + +Considerations for success +========================== + +Authors must review the work done by AI tooling in detail to ensure it +actually makes sense before proposing it as a PR or filing it as an issue. + +We expect PR authors and those filing issues to be able to explain their +proposed changes in their own words. + +Disclosure of the use of AI tools in the PR description is appreciated, +while not required. Be prepared to explain how the tool was used and what +changes it made. + +Whether you are using AI tools or not, keep the following principles in +mind for the quality of your contribution: + +- Consider whether the change is necessary +- Make minimal, focused changes +- Follow existing coding style and patterns +- Write tests that exercise the change +- Keep backwards compatibility with prior releases in mind. Existing + tests may be ensuring specific API behaviors are maintained. + +Pay close attention to AI generated recommendations for testing changes. +Provide input about Python's testing principles when guiding an AI model. +Always review the output before opening a pull request or issue, +including proposed PR or issue titles and descriptions. + +Acceptable uses +=============== + +Some of the acceptable uses of generative AI include: + +- Assistance with writing comments, especially in a non-native language +- Gaining understanding of existing code +- Supplementing contributor knowledge for code, tests, and documentation + +Unacceptable uses +================= + +Maintainers may close issues and PRs that are not useful or productive, +regardless of whether AI tools were used or not. + +If a contributor repeatedly opens unproductive issues or PRs, they may be +blocked from contributing to the project because it is disruptive and +disrespectful of the maintainers time. + +It is not acceptable to alter or bypass existing tests, or remove desired +functionality, in order to make a failing test pass. Such changes are not +a real fix. diff --git a/getting-started/generative-ai.rst b/getting-started/generative-ai.rst deleted file mode 100644 index e4aa3e7586..0000000000 --- a/getting-started/generative-ai.rst +++ /dev/null @@ -1,40 +0,0 @@ -.. _generative-ai: - -============= -Generative AI -============= - -Generative AI tools have evolved rapidly, and their suggested results can be helpful. As with using any tool, the resulting contribution is -the responsibility of the contributor. We value good code, concise accurate documentation, and avoiding unneeded code -churn. Discretion, good judgment, and critical thinking are the foundation of all good contributions, regardless of the -tools used in their creation. - -Acceptable uses -=============== - -Some of the acceptable uses of generative AI include: - -- Assistance with writing comments, especially in a non-native language -- Gaining understanding of existing code -- Supplementing contributor knowledge for code, tests, and documentation - -Unacceptable uses -================= - -Maintainers may close issues and PRs that are not useful or productive, including -those that are fully generated by AI. If a contributor repeatedly opens unproductive -issues or PRs, they may be blocked. - -Considerations for success -========================== -- While AI assisted tools such as autocompletion can enhance productivity, they sometimes rewrite entire code blocks instead of making small, focused edits. - This can make it more difficult to review changes and to fully understand both the original intent of the code and the rationale behind the new modifications. - Maintaining consistency with the original code helps preserve clarity, traceability, and meaningful reviews and also helps us avoid unnecessary code churn. -- Sometimes AI assisted tools make failing unit tests pass by altering or bypassing the tests rather than addressing the underlying problem in the code. - Such changes do not represent a real fix. Authors must review the work done by AI tooling in detail to ensure it actually makes sense before proposing it as a PR. -- Keep the following principles for the quality of your contributions in mind whether you use generative AI or not: - - - Consider whether the change is necessary - - Make minimal, focused changes - - Follow existing coding style and patterns - - Write tests that exercise the change diff --git a/getting-started/index.rst b/getting-started/index.rst index 05ee67a3bc..48037ad38d 100644 --- a/getting-started/index.rst +++ b/getting-started/index.rst @@ -12,4 +12,4 @@ Getting started git-boot-camp pull-request-lifecycle getting-help - generative-ai + ai-tools diff --git a/index.rst b/index.rst index a7f1ff016a..23ed08e151 100644 --- a/index.rst +++ b/index.rst @@ -40,6 +40,7 @@ Guide for contributing to Python: * :ref:`rst-primer` * :ref:`translating` * :ref:`devguide` + * :ref:`ai-tools` - * :ref:`setup` * :ref:`help` @@ -49,6 +50,7 @@ Guide for contributing to Python: * :ref:`communication` * :ref:`gitbootcamp` * :ref:`devcycle` + * :ref:`ai-tools` - * :ref:`tracker` * :ref:`triaging` From 1a89c098cb8265b265cc5f529cf0920dd4e18756 Mon Sep 17 00:00:00 2001 From: Mariatta Date: Thu, 21 May 2026 08:08:43 -0700 Subject: [PATCH 14/85] Fix the redirect to the new ai usage guidelines. (#1806) * Fix the redirect to the new ai usage guidelines. Co-authored-by: Stan Ulbrych --- conf.py | 3 ++- getting-started/ai-tools.rst | 1 + 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/conf.py b/conf.py index 2758938fe9..dce6184480 100644 --- a/conf.py +++ b/conf.py @@ -163,6 +163,7 @@ "gitbootcamp.rst": "getting-started/git-boot-camp.rst", "pullrequest.rst": "getting-started/pull-request-lifecycle.rst", "setup.rst": "getting-started/setup-building.rst", + "getting-started/generative-ai.rst": "getting-started/ai-tools.rst", # CPython Internals "compiler.rst": "internals.rst", "exploring.rst": "internals.rst", @@ -205,7 +206,7 @@ "contrib/project/github.rst": "index.rst", "contrib/project/governance.rst": "index.rst", "contrib/project/roles.rst": "index.rst", - "contrib/project/ai-tools.rst": "getting-started/ai-tools.rst", + "contrib/project/generative-ai": "getting-started/ai-tools.rst", "contrib/project/outreach.rst": "index.rst", "contrib/project/directory-structure.rst": "getting-started/setup-building.rst", "contrib/project/index.rst": "index.rst", diff --git a/getting-started/ai-tools.rst b/getting-started/ai-tools.rst index ba92ea9e13..e7d94d3517 100644 --- a/getting-started/ai-tools.rst +++ b/getting-started/ai-tools.rst @@ -1,4 +1,5 @@ .. _ai-tools: +.. _generative-ai: ============================= Guidelines for using AI tools From 109d6d0f644f7927fa6d1c8d25ac8f0e3c7da702 Mon Sep 17 00:00:00 2001 From: Mariatta Date: Fri, 22 May 2026 11:26:53 -0700 Subject: [PATCH 15/85] Add sphinx-last-updated-by-git extenstion. (#1807) * Add sphinx-last-updated-by-git extenstion. Show the last time the page was updated. Useful for docs like AI tools guidelines. Migrate to RTD jobs because we cannot have both command and jobs in rtd. --- .readthedocs.yml | 17 +++++++++++------ conf.py | 3 +++ requirements.txt | 1 + 3 files changed, 15 insertions(+), 6 deletions(-) diff --git a/.readthedocs.yml b/.readthedocs.yml index 26e5be9672..3e13033540 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -13,9 +13,14 @@ build: tools: python: "3" - commands: - - asdf plugin add uv - - asdf install uv latest - - asdf global uv latest - - make dirhtml BUILDDIR=_readthedocs - - mv _readthedocs/dirhtml _readthedocs/html + jobs: + post_checkout: + - git fetch --unshallow || true + build: + html: + - asdf plugin add uv + - asdf install uv latest + - asdf global uv latest + - make dirhtml BUILDDIR=_readthedocs + - mkdir -p $READTHEDOCS_OUTPUT + - mv _readthedocs/dirhtml $READTHEDOCS_OUTPUT/html diff --git a/conf.py b/conf.py index dce6184480..fb032b895c 100644 --- a/conf.py +++ b/conf.py @@ -10,10 +10,13 @@ 'sphinx.ext.todo', 'sphinx_copybutton', 'sphinx_inline_tabs', + 'sphinx_last_updated_by_git', 'sphinxext.opengraph', 'sphinxext.rediraffe', ] +html_last_updated_fmt = '%b %d, %Y' + # The master toctree document. master_doc = 'index' diff --git a/requirements.txt b/requirements.txt index 09d13a3fec..5dfb12f146 100644 --- a/requirements.txt +++ b/requirements.txt @@ -3,6 +3,7 @@ jinja2 linklint sphinx-autobuild>=2025.8.25 sphinx-inline-tabs>=2025.12.21.14 +sphinx-last-updated-by-git>=0.3.8 sphinx-lint==1.0.2 sphinx-notfound-page>=1.1.0 sphinx_copybutton>=0.5.2 From 87de3503bd9b1fb94a868181ef28a2169d3a9e7a Mon Sep 17 00:00:00 2001 From: Ned Batchelder Date: Sat, 23 May 2026 12:56:51 -0400 Subject: [PATCH 16/85] Add details about merging pull requests (#1808) --- core-team/committing.rst | 27 ++++++++++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/core-team/committing.rst b/core-team/committing.rst index c606df3839..1209d6ae1e 100644 --- a/core-team/committing.rst +++ b/core-team/committing.rst @@ -35,7 +35,7 @@ to enter the public source tree. Ask yourself the following questions: Check :ref:`pull-request-lifecycle` and :ref:`helptriage` to review what is expected of a pull request. -* **Does the change break backwards-compatibility without a strong reason?** +* **Does the change break backwards compatibility without a strong reason?** :ref:`Run the entire test suite ` to make sure that everything still passes. If there is a change to the semantics, then there needs to be a strong reason, because it will cause some peoples' code to break. @@ -79,6 +79,31 @@ to enter the public source tree. Ask yourself the following questions: :ref:`what-s-new-and-news-entries` +Merging the pull request +------------------------ + +Once the pull request is ready, you (the core team member) can merge it. +If other people have been substantially involved in the review, it can be good +to wait for their approval even if a core team member has already approved the +pull request. + +The CPython repo is configured to only accept squashes. You will squash the +pull request. + +Commit message +^^^^^^^^^^^^^^ + +GitHub defaults the squashed commit message to a combined list of all of the +individual commit messages in the pull request. Do not leave those. They often +are too noisy and provide little context, especially since devs know their +work will be eventually squashed, so intermediate commit messages while +working on the pull request are not interesting. + +If you think it is important, you can summarize the collaborative work that +went into the pull request, but it is not necessary. The pull request and/or +original issue are still available for detailed investigations of history. + + Working with Git_ ----------------- From 45e3338d511352ef76bb7d5d37d92d3d1570c1bd Mon Sep 17 00:00:00 2001 From: Ned Batchelder Date: Sun, 24 May 2026 10:19:26 -0400 Subject: [PATCH 17/85] Minor grammar fixes and a glossary entry for "open source" (#1809) --- core-team/motivations.rst | 12 ++++++------ core-team/responsibilities.rst | 2 +- developer-workflow/communication-channels.rst | 2 +- developer-workflow/extension-modules.rst | 2 +- developer-workflow/stdlib.rst | 2 +- development-tools/warnings.rst | 4 ++-- documentation/markup.rst | 2 +- documentation/style-guide.rst | 7 ++++++- getting-started/setup-building.rst | 2 +- 9 files changed, 20 insertions(+), 15 deletions(-) diff --git a/core-team/motivations.rst b/core-team/motivations.rst index d0e5a0cc18..7babb5f7da 100644 --- a/core-team/motivations.rst +++ b/core-team/motivations.rst @@ -115,7 +115,7 @@ participating in the CPython core development process: As a core team member, she is primarily interested in helping to ensure Python's continued suitability for educational, testing and data analysis use cases, as well as in encouraging good architectural practices when assembling Python - applications and test harnesses from open source components. + applications and test harnesses from open-source components. Note: prior to August 2023, Alyssa used her birth name (Nick Coghlan). Some records (for example, mailing list archives, version control history) will still reference that name. @@ -175,14 +175,14 @@ participating in the CPython core development process: available, working on the infrastructure that supports CPython development, specifically the Roundup-based bug tracker and the buildbot system. - David currently does both proprietary and open source development work, + David currently does both proprietary and open-source development work, primarily in Python, through the company in which he is a partner, `Murray & Walker, Inc `__. He has done contract work focused specifically on CPython development both through the PSF (the kickstart of the email Unicode API development) and directly funded by interested corporations (additional development work on email funded by QNX, and work on CPython ICC support funded by Intel). He would like to - spend more of his (and his company's) time on open source work, and so is + spend more of his (and his company's) time on open-source work, and so is actively seeking additional such contract opportunities. .. topic:: Antoine Pitrou (France) @@ -202,7 +202,7 @@ participating in the CPython core development process: concurrent programming. As a professional, Antoine has been first specializing in network - programming, and more lately in open source data science infrastructure. + programming, and more lately in open-source data science infrastructure. He has made numerous contributions to Numba, Dask and is currently working full time on Apache Arrow as a technical leader at QuantStack. @@ -269,7 +269,7 @@ participating in the CPython core development process: Carol is focused on Python's usage in education and scientific research. She is interested in distributed computing, organizational development, - operational workflows, and sustainability of open source projects. + operational workflows, and sustainability of open-source projects. .. _goals-of-the-motivations-page: @@ -282,7 +282,7 @@ strongly suggest that the current core development process is bottlenecked on core team time. This is most clearly indicated in the first metrics graph, which shows both the number of open issues and the number of pull requests awaiting review growing steadily over time, despite CPython being one of the most -active open source projects in the world. This bottleneck then impacts not only +active open-source projects in the world. This bottleneck then impacts not only resolving open issues and accepting submitted pull requests, but also the process of identifying, nominating and mentoring new core team members. diff --git a/core-team/responsibilities.rst b/core-team/responsibilities.rst index 9f5c62b728..130e763d56 100644 --- a/core-team/responsibilities.rst +++ b/core-team/responsibilities.rst @@ -123,7 +123,7 @@ to better assess the sustainability of current contributions to CPython core development, and also serves as a referral list for organisations seeking commercial Python support from the core development community. -And finally, enjoy yourself! Contributing to open source software should be fun +And finally, enjoy yourself! Contributing to open-source software should be fun (overall). If you find yourself no longer enjoying the work then either take a break or figure out what you need to do to make it enjoyable again. diff --git a/developer-workflow/communication-channels.rst b/developer-workflow/communication-channels.rst index a45003c783..101bb06122 100644 --- a/developer-workflow/communication-channels.rst +++ b/developer-workflow/communication-channels.rst @@ -270,7 +270,7 @@ that way. You can find their blogs (and various other developers who use Python) at `Planet Python `__. -Setting expectations for open source participation +Setting expectations for open-source participation ================================================== Burn-out is common in open source due to a misunderstanding of what users, contributors, diff --git a/developer-workflow/extension-modules.rst b/developer-workflow/extension-modules.rst index 4d8c0ffca1..cab46c834b 100644 --- a/developer-workflow/extension-modules.rst +++ b/developer-workflow/extension-modules.rst @@ -547,7 +547,7 @@ Now that the configuration is in place, it remains to compile the project: .. tip:: - Use ``make -jN`` to speed-up compilation by utilizing as many CPU cores + Use ``make -jN`` to speed up compilation by utilizing as many CPU cores as possible, where *N* is as many CPU cores you want to spare (and have memory for). Be careful using ``make -j`` with no argument, as this puts no limit on the number of jobs, and compilation can sometimes use up a diff --git a/developer-workflow/stdlib.rst b/developer-workflow/stdlib.rst index b683e55e96..ec10977221 100644 --- a/developer-workflow/stdlib.rst +++ b/developer-workflow/stdlib.rst @@ -126,7 +126,7 @@ If the module you want to propose adding to the stdlib meets the requirements, you may propose its inclusion by following the :abbr:`PEP (Python Enhancement Proposal)` process. See :pep:`1` for details, -and the :pep:`PEP index <0>` for previously-accepted PEPs +and the :pep:`PEP index <0>` for previously accepted PEPs that have proposed a module for inclusion. If the PEP is accepted, then the module will be added to the stdlib diff --git a/development-tools/warnings.rst b/development-tools/warnings.rst index b30d811311..1026082528 100644 --- a/development-tools/warnings.rst +++ b/development-tools/warnings.rst @@ -29,7 +29,7 @@ What to do if a warning check fails GitHub CI --------------------------------------------- The :cpy-file:`Tools/build/check_warnings.py` tool will fail if the compiler generates -more or less warnings than expected for a given source file as defined in the +more or fewer warnings than expected for a given source file as defined in the platform-specific warning ignore file. The warning ignore file is either :cpy-file:`Tools/build/.warningignore_ubuntu` or :cpy-file:`Tools/build/.warningignore_macos` depending on the platform. @@ -44,7 +44,7 @@ If a warning check fails with: warning ignore file. If the file exists in the warning ignore file increment the count by the number of newly introduced warnings. -* Unexpected improvements (less warnings) +* Unexpected improvements (fewer warnings) * Document in the PR that the change reduces the number of compiler warnings. Decrement the count in the platform-specific warning diff --git a/documentation/markup.rst b/documentation/markup.rst index 5ba8e4c7af..282b80f911 100644 --- a/documentation/markup.rst +++ b/documentation/markup.rst @@ -225,7 +225,7 @@ Explicit markup --------------- "Explicit markup" is used in reST for most constructs that need special -handling, such as footnotes, specially-highlighted paragraphs, comments, and +handling, such as footnotes, specially highlighted paragraphs, comments, and generic directives. An explicit markup block begins with a line starting with ``..`` followed by diff --git a/documentation/style-guide.rst b/documentation/style-guide.rst index 28e4f21682..73618f9aec 100644 --- a/documentation/style-guide.rst +++ b/documentation/style-guide.rst @@ -84,6 +84,11 @@ free-threaded lock (GIL) optional (per :pep:`703`). Avoid using "No-GIL" to avoid double negatives (for example, "non-no-GIL"). +open source + Follow the usual English rules for compound words. When used as an + adjective, hyphenate: "open-source software". When used as a noun, don't use + a hypen: "open source is a collaboration model.." + POSIX The name assigned to a particular group of standards. This is always uppercase. @@ -92,7 +97,7 @@ Python The name of our favorite programming language is always capitalized. reST - For "reStructuredText," an easy to read, plaintext markup syntax + For "reStructuredText," an easy to read, plain-text markup syntax used to produce Python documentation. When spelled out, it is always one word and both forms start with a lowercase 'r'. diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index 04e9a2143c..3590e09c3f 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -83,7 +83,7 @@ You will only need to execute these steps once per machine: (You can use both SSH-based or HTTPS-based URLs.) -.. Step 6 and 7 are are duplicated in bootcamp as well. +.. Step 6 and 7 are duplicated in bootcamp as well. Please update these steps in both places. 6. Add an ``upstream`` remote, then configure ``git`` From c2b831f95f852fe0330a24a12bdbb97b4c0b5cb0 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Mon, 25 May 2026 15:57:58 +0100 Subject: [PATCH 18/85] PSRT: Add template for rejecting duplicate reports (#1810) --- security/psrt.rst | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/security/psrt.rst b/security/psrt.rst index 6b53700d89..ce26f1138d 100644 --- a/security/psrt.rst +++ b/security/psrt.rst @@ -333,6 +333,15 @@ Rejecting a vulnerability report If you are interested in working on this further, you can optionally open a public issue on GitHub. +Rejecting a duplicate report +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + Thanks for your report. We've determined that this submission is a duplicate + of an issue that is already being tracked internally. Please refrain from + public disclosure until the issue has been resolved. + Advisory email ~~~~~~~~~~~~~~ From 35a435a8ccfb3459c0967b2181bb89d3c4f43b9e Mon Sep 17 00:00:00 2001 From: Arpit Jain <3242828+arpitjain099@users.noreply.github.com> Date: Wed, 27 May 2026 05:17:50 +0900 Subject: [PATCH 19/85] CI: declare workflow-level `permissions: {}` (#1811) Signed-off-by: Arpit Jain --- .github/workflows/ci.yml | 2 ++ .github/workflows/lint.yml | 2 ++ 2 files changed, 4 insertions(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index b85a45c1bb..723151d189 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -5,6 +5,8 @@ on: [pull_request, push, workflow_dispatch] env: FORCE_COLOR: 1 +permissions: {} + jobs: test: name: Check build, markup, and links diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index 4622f995aa..6519953670 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/lint.yml @@ -2,6 +2,8 @@ name: Lint on: [push, pull_request, workflow_dispatch] +permissions: {} + jobs: lint: runs-on: ubuntu-latest From 999633216399256b6ce5376c9287f07efd6c9a65 Mon Sep 17 00:00:00 2001 From: Seth Larson Date: Wed, 27 May 2026 06:42:06 -0700 Subject: [PATCH 20/85] Initial draft of Python 'Security Policy' (#1804) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Jelle Zijlstra Co-authored-by: Stan Ulbrych Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Co-authored-by: Emma Smith Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com> Co-authored-by: Savannah Ostrowski Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> --- security/index.rst | 1 + security/policy.rst | 168 ++++++++++++++++++++++++++++++++++++++++++++ security/psrt.rst | 4 ++ versions.rst | 1 + 4 files changed, 174 insertions(+) create mode 100644 security/policy.rst diff --git a/security/index.rst b/security/index.rst index cbc1eb4e46..dd084b9eb0 100644 --- a/security/index.rst +++ b/security/index.rst @@ -7,5 +7,6 @@ Security .. toctree:: :maxdepth: 5 + policy psrt sbom diff --git a/security/policy.rst b/security/policy.rst new file mode 100644 index 0000000000..e9b145220b --- /dev/null +++ b/security/policy.rst @@ -0,0 +1,168 @@ +=============== +Security policy +=============== + +.. important:: + + :ref:`Python Security Response Team ` (PSRT) members balance this work + against many other responsibilities. Please be thoughtful about the time and + attention your report requires. Repeated failure to respect the security policy + will result in future reports being rejected, or the reporter being banned + from the ``python`` GitHub organization, regardless of technical merit. + +What types of bugs are vulnerabilities? +--------------------------------------- + +**Not all bugs are vulnerabilities.** + +To avoid causing duplicate work for PSRT members, **all potential** reports +must be evaluated against the relevant threat models +prior to being submitted to the PSRT. +Where possible, cite the relevant threat model to show that +the latter has been considered while determining whether +to report a bug as a vulnerability. + +Vulnerabilities must be exploitable from code, configurations, +pre-conditions, or deployments that may exist in the real world. +A vulnerability that only affecting code +unlikely to be used in a production program +will not be accepted. + +Documented functionality is not considered a vulnerability. +For example, :mod:`pickle`, :mod:`marshal`, :mod:`shelve`, :func:`eval`, +and :func:`exec` are documented to execute arbitrary Python code that is +supplied as data. The :mod:`ctypes` module is documented to enable modifying +arbitrary locations in memory. + +Vulnerabilities must not depend on malicious control of Python's launch +conditions, including (but not limited to) command line arguments, environment variables, or +modifications to files on the target system. We assume that, at the time Python +is executed, the environment is as intended by the legitimate user, and any +malicious variation from this cannot be mitigated by Python itself. + +Vulnerabilities that affect availability (such as DoS, ReDoS, crashes, +dead-locks, and resource exhaustion) must be +triggerable with data inputs that are reasonably sized for the use case. +Availability vulnerabilities must also demonstrate an "upward" change in posture +for the attacker, rather than a "lateral" one. +This is to avoid handling performance improvements as security vulnerabilities. + +Vulnerabilities in dependencies of Python (such as zlib, Tcl/Tk, or OpenSSL) +are not vulnerabilities in Python unless Python's use of the dependency +interferes with secure use of the dependency. +For example, a vulnerability in the bundled copy of zlib in Python is a +vulnerability in zlib, not Python. + +What versions of Python accept reports? +--------------------------------------- + +Python accepts vulnerability reports and will +assign CVE IDs for :ref:`supported Python versions ` that have a +status of :ref:`"bugfix" or "security" `. Versions that are +not yet stable (status of :ref:`"feature" or "prerelease" `) +are not eligible for CVE IDs. If the vulnerability only exists in prerelease +versions (alphas, betas, release candidates), then the issue should be reported +as a regular bug. +Prior to submitting a report, check whether the issue has already been +resolved on the ``main`` branch and only requires backporting. + +Sometimes features may be marked as +"experimental" in Python, even in a stable Python version. +These features are not eligible for security vulnerabilities. +Instead, open a public GitHub issue. + +If a vulnerability is platform-dependent, check if the platform is +supported per :pep:`11`. +Vulnerabilities that exclusively affect unsupported platforms +are not treated as vulnerabilities in Python. + +As per the :pep:`Unsupported Platforms section of PEP 11 <11#unsupported-platforms>`, +porting Python to an unsupported platform is treated as a third-party project. +If you choose to report such a vulnerability to Python, please follow the +requirements of this guide. Note that these reports may be shared with +parties who expressed interested in the relevant platforms and will +generally be handled according to the relevant maintainers' security +policies. These reports may closed if the maintainers are unknown or +unresponsive. + +What to include and how to structure a vulnerability report? +------------------------------------------------------------ + +For your vulnerability report to be handled efficiently by +the PSRT, the report must include certain information and +be formatted correctly: + +* For the initial report and follow-up communications, avoid + overly long, verbose, or excessive structure (such as headers or tables). + Reports should be a few sentences describing the vulnerability. Ideally include + a proof-of-concept script that reproduces the issue and provides a clear + indication of whether the vulnerability is still present (such as exiting with + ``1`` if vulnerable and ``0`` if not vulnerable). +* When reporting large numbers or "batches" of vulnerabilities or + searching for potential vulnerabilities using an LLM, you as a reporter must + verify the factual validity (such as whether APIs have been hallucinated) + of the content in all reports prior to submission to the PSRT. +* Do not include severity or CVSS information in your initial report, + this information will be determined by the PSRT. +* Ideally, include a minimal patch with the mitigation for the report. +* Always include the versions of Python that were tested, + and indicate which were found to be vulnerable. +* Submit reports as plain-text only, including attachments. + No PDFs, binaries, notebooks, or other files that cannot be safely reviewed. + If your proof-of-concept depends on a specially constructed binary file, + please include a script to construct it rather than the file itself. +* Proof-of-concept scripts longer than a few lines should be wrapped with a + `collapsed section`_ using ``
`` for better readability. +* Reports that do not contain a potential security vulnerability (such as spam + or requesting compliance or due-diligence work) + will be discarded without a reply. + +.. _collapsed section: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-collapsed-sections + +How to submit a vulnerability report? +------------------------------------- + +Submit all potential security vulnerability reports for CPython +by `opening a new ticket `__. +Do not open a public GitHub issue to report a security vulnerability. +For all other projects (such as pip, python.org and tools) or if you're +not sure where to send your report, send an email to +`security@python.org `__. + +Here's what to expect for how a vulnerability report will be handled: + +* Reporter reports the vulnerability privately to the PSRT. +* If the PSRT determines the report isn't a vulnerability, the reporter + may open a public issue. +* If the PSRT determines the report is a vulnerability, the PSRT will + accept the report and a CVE ID will be assigned by the PSF CNA. +* Once a public pull request containing a fix is merged to CPython, + the advisory and CVE record will be published with attribution. + +For more information about how the PSRT handles vulnerabilities, +see :ref:`psrt-vulnerability-process`. + +Code of conduct +--------------- + +Well-being and safety of the Python Security Response Team members is +prioritized over the technical merit of vulnerability reports. +Despite communications being private, vulnerability reporting is subject +to the `PSF Code of Conduct`_. Violations will be reported to the Code of +Conduct team with undisclosed vulnerability information removed, if applicable. + +.. _GHSA: https://github.com/python/cpython/security/advisories/new +.. _PSF Code of Conduct: https://policies.python.org/python.org/code-of-conduct/ + +CVE Numbering Authority (CNA) +----------------------------- + +The Python and pip projects are scoped under the +`Python Software Foundation CVE Numbering Authority `__ +(CNA). This means you must submit all security +vulnerability reports to the PSRT for a CVE ID +to be issued for Python or pip. To reach the PSF +CNA contact directly, send an email to +`cna@python.org `__. + +.. _CNA: https://www.python.org/cve-numbering-authority/ diff --git a/security/psrt.rst b/security/psrt.rst index ce26f1138d..04dd891b3a 100644 --- a/security/psrt.rst +++ b/security/psrt.rst @@ -1,3 +1,5 @@ +.. _psrt: + Python Security Response Team (PSRT) ==================================== @@ -84,6 +86,8 @@ following additional responsibilities: * Running nomination elections, including counting final votes and giving the Steering Council an opportunity to veto nominations via email. +.. _psrt-vulnerability-process: + Triaging a vulnerability report ------------------------------- diff --git a/versions.rst b/versions.rst index 58d56b3e0a..228b445d97 100644 --- a/versions.rst +++ b/versions.rst @@ -45,6 +45,7 @@ Full chart .. raw:: html :file: _static/release-cycle-all.svg +.. _version-status-key: Status key ========== From 3d4d64a7c190291235c7676985940d87e91fed67 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Fri, 29 May 2026 20:22:36 +0100 Subject: [PATCH 21/85] PSRT: Add link to policy to 'Submit using GitHub Security Advisories' template (#1816) --- security/psrt.rst | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/security/psrt.rst b/security/psrt.rst index 04dd891b3a..6a869de6ad 100644 --- a/security/psrt.rst +++ b/security/psrt.rst @@ -236,13 +236,13 @@ This patch can then be applied and pushed to the public GitHub repository: git apply ./ghsa-abcd-efgh-ijkl.patch git push origin branch-name -.. warning:: **IMPORTANT:** CPython's backport infrastructure +.. important:: CPython's backport infrastructure is used for tracking backported patches. Use **one GitHub issue per CVE** to accurately track backports of vulnerability fixes. For new CVEs, even when related to a previous issue, **open a new GitHub issue** to accurately track fixed versions. -.. warning:: **IMPORTANT:** Don't select the green 'Merge pull request' +.. important:: Don't select the green 'Merge pull request' or 'Publish advisory' buttons within GHSA. Advisories are published to the mailing list, and the 'Merge pull request' button within GHSA bypasses all continuous integration and branch protection @@ -323,7 +323,11 @@ Submit using GitHub Security Advisories Thanks for submitting this report. We use GitHub Security Advisories for triaging vulnerability reports, - please submit your report here: + please review our security policy before submitting: + + https://devguide.python.org/security/policy/ + + Then submit your report here: https://github.com/python/cpython/security/advisories/new From 23780ed148182f824fc2c920173db103425a6093 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Sat, 30 May 2026 09:55:57 +0200 Subject: [PATCH 22/85] Add zizmor to pre-commit and fix findings (#1812) --- .github/dependabot.yml | 7 +++++++ .github/workflows/ci.yml | 8 +++++--- .github/workflows/lint.yml | 12 +++++++++--- .pre-commit-config.yaml | 11 ++++++++--- 4 files changed, 29 insertions(+), 9 deletions(-) diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 23f03616cf..1c0343afa3 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -10,6 +10,11 @@ updates: actions: patterns: - "*" + cooldown: + # https://blog.yossarian.net/2025/11/21/We-should-all-be-using-dependency-cooldowns + # Cooldowns protect against supply chain attacks by avoiding the + # highest-risk window immediately after new releases. + default-days: 14 - package-ecosystem: pip directory: "/" @@ -21,3 +26,5 @@ updates: pip: patterns: - "*" + cooldown: + default-days: 14 diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 723151d189..e60db2ddca 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -14,12 +14,14 @@ jobs: timeout-minutes: 10 steps: - - uses: actions/checkout@v6 - - uses: actions/setup-python@v6 + - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + with: + persist-credentials: false + - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0 with: python-version: "3" - name: Install uv - uses: hynek/setup-cached-uv@v2 + uses: hynek/setup-cached-uv@4300ec2180bc77d705e626a34e381b81a4772c51 # v2.5.0 - name: Build docs run: make html - name: Link check diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index 6519953670..ab3911a36d 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/lint.yml @@ -4,14 +4,20 @@ on: [push, pull_request, workflow_dispatch] permissions: {} +env: + FORCE_COLOR: 1 + RUFF_OUTPUT_FORMAT: github + jobs: lint: runs-on: ubuntu-latest timeout-minutes: 10 steps: - - uses: actions/checkout@v6 - - uses: actions/setup-python@v6 + - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + with: + persist-credentials: false + - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0 with: python-version: "3.x" - - uses: pre-commit/action@v3.0.1 + - uses: j178/prek-action@cbc2f23eb5539cf20d82d1aabd0d0ecbcc56f4e3 # v2.0.2 diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index c5beee4a37..07fdda903c 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -1,6 +1,6 @@ repos: - repo: https://github.com/astral-sh/ruff-pre-commit - rev: v0.5.7 + rev: v0.15.14 hooks: - id: ruff name: Run Ruff (lint) @@ -9,7 +9,7 @@ repos: name: Run Ruff (format) - repo: https://github.com/pre-commit/pre-commit-hooks - rev: v4.5.0 + rev: v6.0.0 hooks: - id: check-case-conflict - id: check-merge-conflict @@ -18,8 +18,13 @@ repos: - id: end-of-file-fixer - id: trailing-whitespace + - repo: https://github.com/zizmorcore/zizmor-pre-commit + rev: v1.25.2 + hooks: + - id: zizmor + - repo: https://github.com/sphinx-contrib/sphinx-lint - rev: v0.9.1 + rev: v1.0.2 hooks: - id: sphinx-lint args: [--enable=default-role] From 58019a5226cb29ef4256aaa17026dc7da6781375 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Sat, 30 May 2026 11:09:24 +0300 Subject: [PATCH 23/85] Bump j178/prek-action from 2.0.2 to 2.0.4 in the actions group (#1817) Signed-off-by: dependabot[bot] --- .github/workflows/lint.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index ab3911a36d..a3972b812a 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/lint.yml @@ -20,4 +20,4 @@ jobs: - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0 with: python-version: "3.x" - - uses: j178/prek-action@cbc2f23eb5539cf20d82d1aabd0d0ecbcc56f4e3 # v2.0.2 + - uses: j178/prek-action@bdca6f102f98e2b4c7029491a53dfd366469e33d # v2.0.4 From ae70947211d25a7b73db3986c2995e6a894332fb Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Sat, 30 May 2026 21:02:07 +0100 Subject: [PATCH 24/85] Security Policy: Fix two typos (#1813) --- security/policy.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/security/policy.rst b/security/policy.rst index e9b145220b..e798451213 100644 --- a/security/policy.rst +++ b/security/policy.rst @@ -24,9 +24,8 @@ to report a bug as a vulnerability. Vulnerabilities must be exploitable from code, configurations, pre-conditions, or deployments that may exist in the real world. -A vulnerability that only affecting code -unlikely to be used in a production program -will not be accepted. +A vulnerability that only affects code unlikely to be used +in a production program will not be accepted. Documented functionality is not considered a vulnerability. For example, :mod:`pickle`, :mod:`marshal`, :mod:`shelve`, :func:`eval`, @@ -133,7 +132,7 @@ Here's what to expect for how a vulnerability report will be handled: * Reporter reports the vulnerability privately to the PSRT. * If the PSRT determines the report isn't a vulnerability, the reporter - may open a public issue. + may open a public issue. * If the PSRT determines the report is a vulnerability, the PSRT will accept the report and a CVE ID will be assigned by the PSF CNA. * Once a public pull request containing a fix is merged to CPython, From 96e4d9667bd77ca4f68a92c3be8924f390b262cb Mon Sep 17 00:00:00 2001 From: Murugan Santhosh Date: Sun, 31 May 2026 23:35:47 +0530 Subject: [PATCH 25/85] Update link to Tamil docs translation Discord (#1818) --- documentation/translations/translating.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/translations/translating.rst b/documentation/translations/translating.rst index eb3eb164a9..820e2dd694 100644 --- a/documentation/translations/translating.rst +++ b/documentation/translations/translating.rst @@ -105,7 +105,7 @@ For more details about translations and their progress, see - | Murugan Santhosh (:github-user:`terminaljoint`), | Hari (:github-user:`nammahari`) - :github:`GitHub `, - `Discord `__ + `Discord `__ * - `Traditional Chinese (zh-tw) `__ - | 王威翔 Matt Wang (:github-user:`mattwang44`), | Josix Wang (:github-user:`josix`) From aeb99bd3a1bdcc324eaf27a4f05bea4518fa017c Mon Sep 17 00:00:00 2001 From: Seth Larson Date: Tue, 2 Jun 2026 11:14:56 -0700 Subject: [PATCH 26/85] Add Jelle Zijlstra to the PSRT (#1820) --- security/psrt.csv | 1 + 1 file changed, 1 insertion(+) diff --git a/security/psrt.csv b/security/psrt.csv index d794029825..46391d296c 100644 --- a/security/psrt.csv +++ b/security/psrt.csv @@ -11,6 +11,7 @@ Glyph Lefkowitz,glyph, Gregory P. Smith,gpshead, Hugo van Kemenade,hugovk,Release Manager Jacob Coffee,JacobCoffee, +Jelle Zijlstra,JelleZijlstra, Kirill Podoprigora,eclips4, Larry Hastings,larryhastings, Łukasz Langa,ambv,Release Manager From 7277209ad0c44ed1c325e24fb24c9908f96af48e Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Sat, 6 Jun 2026 10:48:19 +0100 Subject: [PATCH 27/85] Simplify the landing for new contributors (#1827) Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> --- _static/devguide_overrides.css | 6 ++++++ conf.py | 1 + index.rst | 31 ++++++++++++++++--------------- requirements.txt | 1 + 4 files changed, 24 insertions(+), 15 deletions(-) diff --git a/_static/devguide_overrides.css b/_static/devguide_overrides.css index 625a9dda2d..abe61bcdcd 100644 --- a/_static/devguide_overrides.css +++ b/_static/devguide_overrides.css @@ -27,3 +27,9 @@ table.docutils td { vertical-align: top; } + +/* For the video in index.rst */ +[role="main"] .compact-video { + max-width: 500px; + margin-inline: auto; +} diff --git a/conf.py b/conf.py index fb032b895c..020e6bf6af 100644 --- a/conf.py +++ b/conf.py @@ -11,6 +11,7 @@ 'sphinx_copybutton', 'sphinx_inline_tabs', 'sphinx_last_updated_by_git', + 'sphinxcontrib.youtube', 'sphinxext.opengraph', 'sphinxext.rediraffe', ] diff --git a/index.rst b/index.rst index 23ed08e151..f6bd875f06 100644 --- a/index.rst +++ b/index.rst @@ -1,4 +1,5 @@ .. _devguide-main: +.. _contributing: ======================== Python Developer's Guide @@ -8,24 +9,16 @@ Python Developer's Guide .. highlight:: bash -This guide is a comprehensive resource for :ref:`contributing ` +This guide is a comprehensive resource for contributing to Python_ -- for both new and experienced contributors. It is :ref:`maintained ` by the same 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 +Start with the area that best matches what you want to do. +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 @@ -63,15 +56,23 @@ Guide for contributing to Python: 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. +around within the guide, be aware that some sections build on each other, +so you may need to backtrack for missing concepts or terminology. -A number of individuals from the Python community have contributed to a series +For broader open-source contribution advice, a number of individuals from the +Python community have contributed to a series of excellent guides at `Open Source Guides `__. For example, `How to Contribute to Open Source `__. +.. admonition:: You don't have to be a compiler engineer to work on Python -- Savannah Ostrowski + + .. container:: compact-video + + .. youtube:: WGXXxGLBVF4 + :privacy_mode: + :width: 100% + .. _quick-reference: diff --git a/requirements.txt b/requirements.txt index 5dfb12f146..789f9597a3 100644 --- a/requirements.txt +++ b/requirements.txt @@ -7,6 +7,7 @@ sphinx-last-updated-by-git>=0.3.8 sphinx-lint==1.0.2 sphinx-notfound-page>=1.1.0 sphinx_copybutton>=0.5.2 +sphinxcontrib-youtube>=1.5.0 sphinxext-opengraph>=0.13.0 sphinxext-rediraffe Sphinx>=9.1.0 From f72e3aafef9aea18c1731206dc1bcc794ce80cfe Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bern=C3=A1t=20G=C3=A1bor?= Date: Sun, 7 Jun 2026 14:46:35 -0700 Subject: [PATCH 28/85] Clarify that performance improvements are not backported (#1826) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 📝 docs: clarify optimizations are not backported A contributor proposed backporting a performance improvement to the maintenance branches, which prompted core developers to restate the long-standing practice: optimizations are not backported. An optimization can introduce a regression, and a regression in a bugfix release is costly to find and undo. Add this to the maintenance-branch rules so the expectation is explicit, and describe the narrow exception (a clear, no-risk, high-impact change agreed in discussion). Discussion: https://discuss.python.org/t/performance-improvements-and-backports/107625 * 📝 docs: fold performance note into existing rule Sergey noted the maintenance-branch sentence already reads clearly, so a separate paragraph restates it. Move the performance point into that sentence as one clause and let the existing "rare exceptions ... must be discussed first" line cover the narrow case. * 🔧 chore: re-trigger Read the Docs build * 📝 docs: group maintenance backports by risk --- developer-workflow/development-cycle.rst | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/developer-workflow/development-cycle.rst b/developer-workflow/development-cycle.rst index af198a4007..ea46c2405f 100644 --- a/developer-workflow/development-cycle.rst +++ b/developer-workflow/development-cycle.rst @@ -74,12 +74,15 @@ produced from a maintenance branch are called **bugfix** or **maintenance** releases; the terms are used interchangeably. These releases have a **micro version** number greater than zero. -The only changes allowed to occur in a maintenance branch without debate are -bug fixes, test improvements, and edits to the documentation. +Changes backported to a maintenance branch fall into two groups. *Low-risk* +changes (bug fixes, test improvements, and documentation edits) may be +backported without debate. *Higher-risk* changes (new features, semantic +changes, and performance improvements) can introduce regressions, so they are +not backported as a matter of course. Also, a general rule for maintenance branches is that compatibility must not be broken at any point between sibling micro releases (3.12.1, 3.12.2, -etc.). For both rules, only rare exceptions are accepted and **must** be -discussed first. +etc.). For both rules, only rare exceptions are accepted, and each requires a +strong case agreed upon in discussion beforehand. Backporting changes reduces the risk of future conflicts. For documentation, it increases the visibility of improvements, From c5b434589fb84157a2472f23b096b776d056fbbd Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Mon, 8 Jun 2026 09:45:20 -0700 Subject: [PATCH 29/85] Removing myself from experts (#1829) --- core-team/experts.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/core-team/experts.rst b/core-team/experts.rst index 47e1d76107..a5fd9c9358 100644 --- a/core-team/experts.rst +++ b/core-team/experts.rst @@ -53,7 +53,7 @@ __main__ gvanrossum, ncoghlan annotationlib JelleZijlstra* argparse savannahostrowski*, serhiy-storchaka* ast benjaminp, pablogsal, isidentical, JelleZijlstra, eclips4 -asyncio 1st1, asvetlov, gvanrossum, graingert, kumaraditya303, willingc +asyncio 1st1, asvetlov, gvanrossum, graingert, kumaraditya303 bisect rhettinger* codecs malemburg collections rhettinger* @@ -145,7 +145,6 @@ tomllib hauntsaninja* traceback iritkatriel tracemalloc vstinner tty Yhg1s* -turtle willingc turtledemo terryjreedy* types 1st1 typing gvanrossum, JelleZijlstra*, AlexWaygood*, carljm, sobolevn* @@ -217,9 +216,9 @@ context managers ncoghlan core workflow Mariatta, ezio-melotti, hugovk, AA-Turner cryptography gpshead, dstufft, picnixz database malemburg -devguide merwok, ezio-melotti, willingc, Mariatta, hugovk, +devguide merwok, ezio-melotti, Mariatta, hugovk, AA-Turner, StanFromIreland -documentation ezio-melotti, merwok, JulienPalard, willingc, hugovk, +documentation ezio-melotti, merwok, JulienPalard, hugovk, AA-Turner, AlexWaygood*, StanFromIreland emoji Mariatta extension modules encukou, ncoghlan, FFY00 From 3d4cf26008be783299e3e999bfdeb0a40490171b Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Mon, 8 Jun 2026 23:27:42 +0100 Subject: [PATCH 30/85] Fix link to GHSAs in Security Policy (#1830) --- security/policy.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/security/policy.rst b/security/policy.rst index e798451213..8dc736d24c 100644 --- a/security/policy.rst +++ b/security/policy.rst @@ -122,7 +122,7 @@ How to submit a vulnerability report? ------------------------------------- Submit all potential security vulnerability reports for CPython -by `opening a new ticket `__. +by `opening a new ticket `_. Do not open a public GitHub issue to report a security vulnerability. For all other projects (such as pip, python.org and tools) or if you're not sure where to send your report, send an email to From 856b971c91054a659ce6ec6216c4d656cb1b60a8 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Wed, 10 Jun 2026 12:09:25 +0100 Subject: [PATCH 31/85] Clarify the role PSRT has in handling vulnerability reports for unsupported platforms (GH-1822) Co-authored-by: Jacob Coffee Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> --- security/policy.rst | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/security/policy.rst b/security/policy.rst index 8dc736d24c..d2e15f98aa 100644 --- a/security/policy.rst +++ b/security/policy.rst @@ -77,12 +77,13 @@ are not treated as vulnerabilities in Python. As per the :pep:`Unsupported Platforms section of PEP 11 <11#unsupported-platforms>`, porting Python to an unsupported platform is treated as a third-party project. -If you choose to report such a vulnerability to Python, please follow the -requirements of this guide. Note that these reports may be shared with -parties who expressed interested in the relevant platforms and will -generally be handled according to the relevant maintainers' security -policies. These reports may closed if the maintainers are unknown or -unresponsive. +For these reports, the PSRT treats them as vulnerability reports for a third-party +port, not as Python vulnerabilities. +If you choose to report such an issue to Python, follow the requirements +of this guide and include the relevant platform and maintainer context. +The PSRT forwards these reports to platform maintainers (or other interested +parties) and they are usually handled under the relevant maintainers' security +policies. These reports will be closed if the maintainers are unknown or unresponsive. What to include and how to structure a vulnerability report? ------------------------------------------------------------ From cfd01cf5ed365abf663fe698a2ecab6bcbaf201a Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Thu, 11 Jun 2026 15:40:22 +0100 Subject: [PATCH 32/85] Revise the "Backporting merged changes" guide (GH-1819) --- core-team/committing.rst | 36 +-------------- getting-started/git-boot-camp.rst | 73 ++++++++++++++++++++----------- 2 files changed, 49 insertions(+), 60 deletions(-) diff --git a/core-team/committing.rst b/core-team/committing.rst index 1209d6ae1e..0a5380e0fa 100644 --- a/core-team/committing.rst +++ b/core-team/committing.rst @@ -149,44 +149,10 @@ bug fixes or security fixes. In almost all cases the fixes should first originate on ``main`` and then be ported back to older branches. -.. _branch-merge: - Backporting changes to an older version ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -If it is determined that a pull request needs to be backported into one or -more of the maintenance branches, then a core team member can apply the label -``needs backport to X.Y`` to the pull request. - -After the pull request has been merged, miss-islington (bot) will first try to -do the backport automatically. If miss-islington is unable to do it, -then the pull request author or the core team member who merged it should look into -backporting it themselves, using the backport generated by cherry_picker.py_ -as a starting point. - -You can get the commit hash from the original pull request, or you can use -``git log`` on the ``main`` branch. To display the 10 most recent commit -hashes and their first line of the commit, use the following command:: - - git log -10 --oneline - -.. _backport-pr-title: - -You can prefix the backport pull request with the branch, and reference -the pull request number from ``main``. Here is an example:: - - [3.9] gh-12345: Fix the Spam Module (GH-NNNN) - -Here "gh-12345" is the GitHub *issue* number, and "GH-NNNN" is the -number of the original *pull request*. -Note that cherry_picker.py_ adds the branch prefix automatically. - -Once the backport pull request has been created, remove the -``needs backport to X.Y`` label from the original pull request. (Only -members of the core team and :ref:`Python Triage Team ` -can apply labels to GitHub pull requests). - -.. _cherry_picker.py: https://github.com/python/cherry-picker +This section has moved to :ref:`branch-merge`. Reverting a merged pull request diff --git a/getting-started/git-boot-camp.rst b/getting-started/git-boot-camp.rst index 47f49f3d69..95f6a94cab 100644 --- a/getting-started/git-boot-camp.rst +++ b/getting-started/git-boot-camp.rst @@ -557,60 +557,83 @@ dismissing your previous review that requested changes. Note that pushing new changes after the auto-merge flow was enabled does **NOT** stop it. + +.. _branch-merge: + Backporting merged changes -------------------------- -A pull request may need to be backported into one of the maintenance branches -after it has been accepted and merged into ``main``. It is usually indicated -by the label ``needs backport to X.Y`` on the pull request itself. +After a pull request has been merged into ``main``, it may need to be backported +to one or more :ref:`maintenance ` or :ref:`security ` +branches. This is indicated by the :samp:`needs backport to {X.Y}` labels on +the pull request. -Use the utility script -`cherry_picker.py `__ -to backport the commit. +``miss-islington`` will automatically attempt to create backport PRs for the +versions indicated by these labels. If ``miss-islington`` cannot create a +backport PR due to conflicts, you can use the :pypi:`cherry-picker` tool to +create the backport and resolve the conflicts manually. -The commit hash for backporting is the squashed commit that was merged to -the ``main`` branch. On the merged pull request, scroll to the bottom of the -page. Find the event that says something like: +You need the commit hash of the squashed commit that was merged into +the ``main`` branch. ``miss-islington`` should post a comment when it is unable +to create the backport automatically, including the full command and commit hash. +If that comment is not posted, look for an event on the merged +pull request similar to: .. code-block:: text merged commit into python:main ago. -By following the link to ````, you will get the full commit hash. +By following the link to ````, you can get the full commit hash. -Alternatively, the commit hash can also be obtained by the following Git +Alternatively, the commit hash can also be obtained with the following Git commands:: $ git fetch upstream - $ git rev-parse ":/gh-12345" + $ git rev-parse ":/gh-" + +These commands print the hash of the commit whose message contains ``gh-``. -The above commands will print out the hash of the commit containing -``"gh-12345"`` as part of the commit message. +You can then use the commit hash and the :pypi:`cherry-picker` tool to create +the backport. In the following command, ```` is the target maintenance +branch (for example, ``3.12``): + +.. code-block:: text -When formatting the commit message for a backport commit: leave the original -one as is and delete the number of the backport pull request. + $ cherry_picker -✅ Example of good backport commit message: +Then, follow the instructions provided. You will have to identify the files +with conflicts, fix them, and build and run applicable tests if necessary. +When you are finished, ``git add`` all modified files and run +``cherry_picker --continue`` to push the backport. + +The tool usually generates the commit message automatically. If it does not, use +the following format: Keep the original commit message unchanged, except for +removing the backport pull request number (``(#XXXXX)``). At the end of the +message, append a ``(cherry picked from commit )`` line. + +The format of a correct backport commit message is: .. code-block:: text :class: good - gh-12345: Improve the spam module (GH-777) + [] gh-XXXXX: (GH-XXXXX) - * Add method A to the spam module - * Update the documentation of the spam module + - (cherry picked from commit 62adc55) + (cherry picked from commit ) -❌ Example of bad backport commit message: +An example of a bad backport commit message: .. code-block:: text :class: bad - gh-12345: Improve the spam module (GH-777) (#888) + gh-XXXXX: Custom title (GH-XXXXX) (#XXXXX) + + * Custom message + +After the backport PR is opened, ``miss-islington`` will link it to the original +PR and remove the corresponding backport label. - * Add method A to the spam module - * Update the documentation of the spam module Editing a pull request prior to merging --------------------------------------- From 24065f922d201228cd07d514367fecdbecaf29e7 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Thu, 11 Jun 2026 16:00:43 +0100 Subject: [PATCH 33/85] Fix the documentation of our custom Sphinx roles (#1823) --- documentation/markup.rst | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/documentation/markup.rst b/documentation/markup.rst index 282b80f911..41bf5b39c6 100644 --- a/documentation/markup.rst +++ b/documentation/markup.rst @@ -707,10 +707,9 @@ where simpler markup should be used: In addition, the CPython documentation defines a few custom roles: -* ``:cve:`YYYY-NNNNN```: link to a Common Vulnerabilities and Exposures entry. -* ``:cwe:`NNN```: link to a Common Weakness Enumeration entry. * ``:gh:`ID```: link to a GitHub issue. * ``:issue:`ID```: link to a bugs.python.com issue. +* ``:oss-fuzz:`ID```: link to an OSS-Fuzz issue. * ``:pypi:`NAME```: link to a project on PyPI. * ``:source:`PATH```: link to a source file on GitHub. @@ -970,6 +969,16 @@ in a different style: The following roles generate external links: +.. describe:: cve + + Link to a `Common Vulnerabilities and Exposures `__ + entry. You can link to a specific section by using ``:cve:`number#anchor```. + +.. describe:: cwe + + Link to a `Common Weakness Enumeration `__ entry. + You can link to a specific section by using ``:cwe:`number#anchor```. + .. describe:: pep A reference to a Python Enhancement Proposal. This generates appropriate From 671cfe319a01b0f39fbc71bf6bd480ad0748a8cd Mon Sep 17 00:00:00 2001 From: Seth Michael Larson Date: Fri, 12 Jun 2026 09:22:56 -0500 Subject: [PATCH 34/85] Add myself to 'core-team.csv' --- core-team/core-team.csv | 1 + 1 file changed, 1 insertion(+) diff --git a/core-team/core-team.csv b/core-team/core-team.csv index b7f25e1618..01187a9ead 100644 --- a/core-team/core-team.csv +++ b/core-team/core-team.csv @@ -1,3 +1,4 @@ +Seth Larson,sethmlarson,2026-06-12,, Chris Eibl,chris-eibl,2026-05-10,, Stan Ulbrych,StanFromIreland,2026-03-26,, Itamar Oren,itamaro,2026-02-16,, From 2e9548298c8ecc0fa58602d416de7c3162e35061 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Mon, 15 Jun 2026 12:23:38 +0100 Subject: [PATCH 35/85] Use `sphinx-doc/github-problem-matcher` in CI (#1834) --- .github/workflows/ci.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index e60db2ddca..469092a3a4 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -22,6 +22,7 @@ jobs: python-version: "3" - name: Install uv uses: hynek/setup-cached-uv@4300ec2180bc77d705e626a34e381b81a4772c51 # v2.5.0 + - uses: sphinx-doc/github-problem-matcher@d521df655a8af22fcc69e4f4af8b1f25699ee754 # v1.0 - name: Build docs run: make html - name: Link check From a7c782cc1cdb3467a88857bfd0c245f1b502db50 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Mon, 15 Jun 2026 15:02:01 +0100 Subject: [PATCH 36/85] Add note on unexpected exceptions to CPython security policy (#1825) Co-authored-by: Seth Larson --- security/policy.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/security/policy.rst b/security/policy.rst index d2e15f98aa..941b485e22 100644 --- a/security/policy.rst +++ b/security/policy.rst @@ -45,6 +45,8 @@ triggerable with data inputs that are reasonably sized for the use case. Availability vulnerabilities must also demonstrate an "upward" change in posture for the attacker, rather than a "lateral" one. This is to avoid handling performance improvements as security vulnerabilities. +Exceptions are an expected part of control flow when processing inputs, +therefore crashes resulting from unhandled exceptions are not security vulnerabilities. Vulnerabilities in dependencies of Python (such as zlib, Tcl/Tk, or OpenSSL) are not vulnerabilities in Python unless Python's use of the dependency From 7944527ad6322dcfbff36fbfe417ff7b597c4cb8 Mon Sep 17 00:00:00 2001 From: Seth Larson Date: Mon, 15 Jun 2026 09:37:21 -0500 Subject: [PATCH 37/85] Add section on security fixes, backports, backwards-incompatible fixes Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> --- security/policy.rst | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/security/policy.rst b/security/policy.rst index 941b485e22..d1accf3c09 100644 --- a/security/policy.rst +++ b/security/policy.rst @@ -144,6 +144,32 @@ Here's what to expect for how a vulnerability report will be handled: For more information about how the PSRT handles vulnerabilities, see :ref:`psrt-vulnerability-process`. +When are security fixes released or backported? +----------------------------------------------- + +Advisories and CVE records are published after a security fix is first merged. +The CVE record contains information about the patch and will be kept up-to-date +as the patch is backported and released to Python versions. + +According to :pep:`602`, Python versions receive five years of security updates +after the new Python version is released. However, these security updates +are not published according to a fixed schedule or as a result of any security +fix being available. The schedule for security updates is determined by +the Release Manager. Users are encouraged to apply patches themselves ahead +of patches being merged and released if necessary. + +Security fixes that only affect binary installers (such as macOS and Windows) +will not be published to Python release streams that are +:ref:`source-only `. + +Some security fixes may require introducing backwards-incompatible behavior +changes. In these circumstances, the Python Steering Council +will decide with the relevant Release Managers whether to introduce +a backwards incompatible change to fix a security vulnerability +in a stable version. This may affect whether a security fix is backported +to all Python versions or enabled by default. See the CVE record for +more information. + Code of conduct --------------- From e0ecbef0fad11be66fd16858bf9835de7ce6107b Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Tue, 16 Jun 2026 12:06:36 +0100 Subject: [PATCH 38/85] =?UTF-8?q?Update=20=C5=81ukasz's=20and=20Petr's=20r?= =?UTF-8?q?oles=20(GH-1832)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- developer-workflow/development-cycle.rst | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/developer-workflow/development-cycle.rst b/developer-workflow/development-cycle.rst index ea46c2405f..5d9073ed3e 100644 --- a/developer-workflow/development-cycle.rst +++ b/developer-workflow/development-cycle.rst @@ -303,7 +303,9 @@ Current owners +----------------------+--------------------------------+-----------------+ | Jacob Coffee | PSF Infrastructure Engineer | JacobCoffee | +----------------------+--------------------------------+-----------------+ -| Łukasz Langa | CPython Developer in Residence | ambv | +| Petr Viktorin | CPython Developer in Residence | encukou | ++----------------------+--------------------------------+-----------------+ +| Łukasz Langa | | ambv | +----------------------+--------------------------------+-----------------+ Certain actions (blocking spam accounts, inviting new users, adjusting @@ -349,7 +351,7 @@ Current administrators | Pablo Galindo | Python 3.10 and 3.11 Release Manager, | pablogsal | | | Maintainer of buildbot.python.org | | +--------------------+----------------------------------------------------------+-------------------+ -| Łukasz Langa | PSF CPython Developer in Residence 2021-present | ambv | +| Łukasz Langa | | ambv | +--------------------+----------------------------------------------------------+-------------------+ | Brett Cannon | | brettcannon | +--------------------+----------------------------------------------------------+-------------------+ @@ -359,6 +361,8 @@ Current administrators +--------------------+----------------------------------------------------------+-------------------+ | Seth Larson | PSF Security Developer-in-Residence | sethmlarson | +--------------------+----------------------------------------------------------+-------------------+ +| Petr Viktorin | CPython Developer in Residence | encukou | ++--------------------+----------------------------------------------------------+-------------------+ Repository release manager role policy ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ From 97a689e980d34d68e97b77470800e29ec9d6cef3 Mon Sep 17 00:00:00 2001 From: Pranav Choudhary Date: Fri, 19 Jun 2026 01:52:03 +0530 Subject: [PATCH 39/85] Docs: Add tabs to Linux build dependencies (#1840) --- getting-started/setup-building.rst | 85 ++++++++++++++++-------------- 1 file changed, 44 insertions(+), 41 deletions(-) diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index 3590e09c3f..046e091d8b 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -768,64 +768,67 @@ some of CPython's modules (for example, ``zlib``). distribution, but the appropriate commands for some popular distributions are below. - On **Fedora**, **RHEL**, **CentOS** and other ``dnf``-based systems:: + .. tab:: dnf - $ sudo dnf install git pkg-config - $ sudo dnf install dnf-plugins-core # install this to use 'dnf builddep' - $ sudo dnf builddep python3 + On **Fedora**, **RHEL**, **CentOS** and other ``dnf``-based systems:: - Some optional development dependencies are not included in the above. - To install some additional dependencies for optional build and test components:: + $ sudo dnf install git pkg-config + $ sudo dnf install dnf-plugins-core # install this to use 'dnf builddep' + $ sudo dnf builddep python3 - $ sudo dnf install \ - gcc gcc-c++ gdb lzma glibc-devel libstdc++-devel openssl-devel \ - readline-devel zlib-devel libzstd-devel libffi-devel bzip2-devel \ - xz-devel sqlite sqlite-devel sqlite-libs libuuid-devel gdbm-libs \ - perf expat expat-devel mpdecimal python3-pip + Some optional development dependencies are not included in the above. + To install some additional dependencies for optional build and test components:: + $ sudo dnf install \ + gcc gcc-c++ gdb lzma glibc-devel libstdc++-devel openssl-devel \ + readline-devel zlib-devel libzstd-devel libffi-devel bzip2-devel \ + xz-devel sqlite sqlite-devel sqlite-libs libuuid-devel gdbm-libs \ + perf expat expat-devel mpdecimal python3-pip - On **Debian**, **Ubuntu**, and other ``apt``-based systems, try to get the - dependencies for the Python you're working on by using the ``apt`` command. + .. tab:: apt - First, make sure you have enabled the source packages in the sources list. - You can do this by adding the location of the source packages, including - URL, distribution name and component name, to ``/etc/apt/sources.list``. - Take Ubuntu 22.04 LTS (Jammy Jellyfish) for example:: + On **Debian**, **Ubuntu**, and other ``apt``-based systems, try to get the + dependencies for the Python you're working on by using the ``apt`` command. - $ deb-src http://archive.ubuntu.com/ubuntu/ jammy main + First, make sure you have enabled the source packages in the sources list. + You can do this by adding the location of the source packages, including + URL, distribution name and component name, to ``/etc/apt/sources.list``. + Take Ubuntu 22.04 LTS (Jammy Jellyfish) for example:: - Alternatively, uncomment lines with ``deb-src`` using an editor, for - example:: + $ deb-src http://archive.ubuntu.com/ubuntu/ jammy main - $ sudo nano /etc/apt/sources.list + Alternatively, uncomment lines with ``deb-src`` using an editor, for + example:: - For other distributions, like Debian, change the URL and names to correspond - with the specific distribution. + $ sudo nano /etc/apt/sources.list - Then you should update the packages index:: + For other distributions, like Debian, change the URL and names to correspond + with the specific distribution. - $ sudo apt-get update + Then you should update the packages index:: - Now you can install the build dependencies via ``apt``:: + $ sudo apt-get update - $ sudo apt-get build-dep python3 - $ sudo apt-get install pkg-config + Now you can install the build dependencies via ``apt``:: - If you want to build all optional modules, install the following packages and - their dependencies:: + $ sudo apt-get build-dep python3 + $ sudo apt-get install pkg-config - $ sudo apt-get install build-essential gdb lcov pkg-config \ - libbz2-dev libffi-dev libgdbm-dev libgdbm-compat-dev liblzma-dev \ - libncurses5-dev libreadline6-dev libsqlite3-dev libssl-dev \ - lzma lzma-dev tk-dev uuid-dev zlib1g-dev libmpdec-dev libzstd-dev \ - inetutils-inetd + If you want to build all optional modules, install the following packages and + their dependencies:: - Note that Debian 12 and Ubuntu 24.04 do not have the ``libmpdec-dev`` - package. You can safely remove it from the install list above and the - Python build will use a bundled version. But we recommend using the system - `libmpdec `__ library. - Either build it from sources or install this package from - https://deb.sury.org. + $ sudo apt-get install build-essential gdb lcov pkg-config \ + libbz2-dev libffi-dev libgdbm-dev libgdbm-compat-dev liblzma-dev \ + libncurses5-dev libreadline6-dev libsqlite3-dev libssl-dev \ + lzma lzma-dev tk-dev uuid-dev zlib1g-dev libmpdec-dev libzstd-dev \ + inetutils-inetd + + Note that Debian 12 and Ubuntu 24.04 do not have the ``libmpdec-dev`` + package. You can safely remove it from the install list above and the + Python build will use a bundled version. But we recommend using the system + `libmpdec `__ library. + Either build it from sources or install this package from + https://deb.sury.org. .. tab:: macOS From 726ddafd8d0c9862f645269bb6093b376e180d3b Mon Sep 17 00:00:00 2001 From: Pranav Choudhary Date: Mon, 22 Jun 2026 20:30:07 +0530 Subject: [PATCH 40/85] Linux build dependencies: use distro names, not package managers (GH-1841) --- getting-started/setup-building.rst | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index 046e091d8b..d653fd73a7 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -764,11 +764,10 @@ some of CPython's modules (for example, ``zlib``). For Unix-based systems, we try to use system libraries whenever available. This means optional components will only build if the relevant system headers - are available. The best way to obtain the appropriate headers will vary by - distribution, but the appropriate commands for some popular distributions - are below. + are available. The best way to obtain these headers varies by distribution, + but commands for some popular distributions are given below. - .. tab:: dnf + .. tab:: Fedora / RHEL / CentOS On **Fedora**, **RHEL**, **CentOS** and other ``dnf``-based systems:: @@ -785,7 +784,7 @@ some of CPython's modules (for example, ``zlib``). xz-devel sqlite sqlite-devel sqlite-libs libuuid-devel gdbm-libs \ perf expat expat-devel mpdecimal python3-pip - .. tab:: apt + .. tab:: Debian / Ubuntu On **Debian**, **Ubuntu**, and other ``apt``-based systems, try to get the dependencies for the Python you're working on by using the ``apt`` command. From bad7be50bb4c51aa92fd3a94e4534419ce828809 Mon Sep 17 00:00:00 2001 From: Bhuvansh Date: Wed, 24 Jun 2026 18:16:24 +0530 Subject: [PATCH 41/85] Add Punjabi translation team (#1843) Co-authored-by: Stan Ulbrych --- documentation/translations/translating.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/documentation/translations/translating.rst b/documentation/translations/translating.rst index 820e2dd694..d954004b9a 100644 --- a/documentation/translations/translating.rst +++ b/documentation/translations/translating.rst @@ -83,6 +83,10 @@ For more details about translations and their progress, see `guide `__, `Telegram `__, `article `__ + * - Punjabi (pa) + - Bhuvansh Kataria (:github-user:`BHUVANSH855`) + - :github:`GitHub `, + `Transifex `_ * - `Romanian (ro) `__ - Octavian Mustafa (:github-user:`octaG-M`, `email `__) - :github:`GitHub ` From 0164145f9992d85dbb9c60b0f1e3c4ad87922f5c Mon Sep 17 00:00:00 2001 From: Stephen Rosen Date: Thu, 25 Jun 2026 11:30:10 -0500 Subject: [PATCH 42/85] Move the "quick reference" to a dedicated page (#1838) Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Co-authored-by: Stan Ulbrych Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> Co-authored-by: Carol Willing <2680980+willingc@users.noreply.github.com> --- getting-started/index.rst | 1 + getting-started/pull-request-lifecycle.rst | 70 +++------ getting-started/quick-reference.rst | 171 +++++++++++++++++++++ index.rst | 93 +---------- 4 files changed, 193 insertions(+), 142 deletions(-) create mode 100644 getting-started/quick-reference.rst diff --git a/getting-started/index.rst b/getting-started/index.rst index 48037ad38d..c83de10a0e 100644 --- a/getting-started/index.rst +++ b/getting-started/index.rst @@ -7,6 +7,7 @@ Getting started .. toctree:: :maxdepth: 5 + quick-reference setup-building fixing-issues git-boot-camp diff --git a/getting-started/pull-request-lifecycle.rst b/getting-started/pull-request-lifecycle.rst index 78c8cfff06..47f1100c2b 100644 --- a/getting-started/pull-request-lifecycle.rst +++ b/getting-started/pull-request-lifecycle.rst @@ -16,58 +16,8 @@ that you create a branch in Git, make your changes, push those changes to your fork on GitHub (``origin``), and then create a pull request against the official CPython repository (``upstream``). - -.. _pullrequest-quickguide: - -Quick guide -=========== - -`Clear communication`_ is key to contributing to any project, especially an -`Open Source`_ project like CPython. - -Here is a quick overview of how you can contribute to CPython: - -#. `Create an issue`_ that describes your change. If it is trivial - (like :ref:`typo fixes `), or an issue already exists, - you can skip this step. - -#. :ref:`Create a new branch in Git ` from the - ``main`` branch - -#. Work on changes: fix a bug or add a new feature - -#. :ref:`Run tests ` and ``make patchcheck`` - -#. :ref:`Commit ` and :ref:`push ` - changes to your GitHub fork - -#. `Create Pull Request`_ on GitHub to merge a branch from your fork - -#. Make sure the :ref:`continuous integration checks on your Pull Request - are green ` (successful) - -#. Review and address `comments on your Pull Request`_ - -#. When your changes are merged, you can :ref:`delete the PR branch - ` - -#. Celebrate contributing to CPython! :) - -Don't force-push ----------------- - -In order to keep the commit history intact, please avoid squashing or amending -history and then force-pushing to the PR. Reviewers often want to look at -individual commits. -When the PR is merged, everything will be squashed into a single commit. - -.. _Clear communication: https://opensource.guide/how-to-contribute/#how-to-submit-a-contribution -.. _Open Source: https://opensource.guide/ -.. _create an issue: https://github.com/python/cpython/issues -.. _CPython: https://github.com/python/cpython -.. _use HTTPS: https://help.github.com/articles/which-remote-url-should-i-use/ -.. _Create Pull Request: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request -.. _comments on your Pull Request: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/commenting-on-a-pull-request +For a cheat-sheet reference, see the +:ref:`quick reference on creating pull requests `. .. _pullrequest-steps: @@ -185,6 +135,15 @@ message. It is usually okay to leave that as-is and close the editor. See `the merge command's documentation `__ for a detailed technical explanation. +Don't force-push +---------------- + +In order to keep the commit history intact, avoid squashing or amending +history and then force-pushing to the PR. +Reviewers often want to look at individual commits. + +CPython uses squash merges, so PRs will end up as single commits when merged. + .. _good-prs: @@ -290,6 +249,8 @@ in the "What's New in Python" entry. A change that needs an entry in "What's New in Python" is very likely not suitable for inclusion in a maintenance release. +.. _news-entry-howto: + How to add a NEWS entry ----------------------- @@ -297,6 +258,11 @@ How to add a NEWS entry ``NEWS`` entry can be created by using `blurb-it `_, or the :pypi:`blurb` tool and its ``blurb add`` command. +.. tip:: + + You can read more about ``blurb`` in its + :github:`repository `. + If you are unable to use the tool, then you can create the ``NEWS`` entry file manually. The ``Misc/NEWS.d`` directory contains a sub-directory named ``next``, which contains various sub-directories representing classifications diff --git a/getting-started/quick-reference.rst b/getting-started/quick-reference.rst new file mode 100644 index 0000000000..909e2f41a8 --- /dev/null +++ b/getting-started/quick-reference.rst @@ -0,0 +1,171 @@ +.. _quick-reference: + +=============== +Quick reference +=============== + +.. include:: /include/activate-tab.rst + +Here are the basic steps needed to get set up and open a pull request. + +This is meant as a checklist and cheat-sheet, not a comprehensive guide. +For complete instructions see the :ref:`setup guide ` and the +:ref:`pull request guide `. + + +Set up Git +========== + +Install and set up ``Git``. + +For detailed setup information, see :ref:`"Install Git" `. +There is also a more detailed :ref:`Git guide and cheat sheet `. + +Fork and clone the repo +----------------------- + +Fork `the CPython repository `__ +to your GitHub account and clone the repo using:: + + git clone https://github.com//cpython + cd cpython + +For detailed information, see :ref:`"Get the source code" `. + + +Build Python +============ + +.. tab:: Unix + + .. code-block:: shell + + ./configure --config-cache --with-pydebug && make -j $(nproc) + +.. tab:: macOS + + .. code-block:: shell + + ./configure --config-cache --with-pydebug && make -j$(sysctl -n hw.logicalcpu) + +.. tab:: Windows + + .. code-block:: dosbatch + + PCbuild\build.bat -e -d + +See also :ref:`more detailed instructions `, +:ref:`how to install and build dependencies `, +and the platform-specific pages for :ref:`Unix `, +:ref:`macOS `, and :ref:`Windows `. + + +Run the tests +============= + +.. tab:: Unix + + .. code-block:: shell + + ./python -m test -j0 + +.. tab:: macOS + + .. code-block:: shell + + ./python.exe -m test -j0 + + .. note:: + :ref:`Most ` macOS systems use + :file:`./python.exe` in order to avoid filename conflicts with + the ``Python`` directory. + +.. tab:: Windows + + .. code-block:: dosbatch + + .\python.bat -m test -j0 + + +See also :ref:`how to write and run tests `. + + +.. _pullrequest-quickguide: + +Create issues and pull requests +=============================== + +Create issues for nontrivial changes +------------------------------------ + +For most changes, `create an issue `__ +before submitting a pull request. +Trivial changes like typo fixes do not need issues. + +Create work branches +-------------------- + +Work on a feature or fix in a new branch in Git from the ``main`` branch:: + + git checkout -b fix-issue-12345 main + +Make changes, then :ref:`commit ` and +:ref:`push to your fork `. + +Document your changes +--------------------- + +Many changes deserve a NEWS entry which documents what changed. +For more information on how and when to write news entries, +see :ref:`"Updating NEWS and What's New in Python" `. + +A news entry can be created locally with the :pypi:`blurb` tool +and its ``blurb add`` command or online after a pull request has +been opened with `blurb-it `__. + +For more information about how to create news entries, see +:ref:`"How to add a NEWS entry" `. + +Create pull requests +-------------------- + +Create pull requests on GitHub from your branches, on your fork, and make sure +to put the relevant issue number in ``gh-NNNNNN`` format in the pull request title. +For example: + +.. code-block:: text + + gh-12345: Fix some bug in spam module + +See also, GitHub's documentation on `creating pull requests`_. + +For more detailed guidance, follow the :ref:`step-by-step pull request guide `. + +.. note:: + + First time contributors will need to sign the Contributor Licensing + Agreement (CLA) as described in the :ref:`Licensing ` section of + this guide. + +.. _creating pull requests: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request + +Work on your pull request +------------------------- + +Make sure the :ref:`continuous integration checks on your pull +request are green ` (successful). + +Read and respond to reviewer comments on your pull request. + +See also, GitHub's documentation on `commenting on pull requests`_. + +.. _commenting on pull requests: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/commenting-on-a-pull-request + +Don't force-push +---------------- + +In order to keep the commit history intact, avoid squashing or amending +history and then force-pushing to the PR. +Reviewers often want to look at individual commits. + +CPython uses squash merges, so PRs will end up as single commits when merged. diff --git a/index.rst b/index.rst index f6bd875f06..9067b92031 100644 --- a/index.rst +++ b/index.rst @@ -74,102 +74,15 @@ For example, :width: 100% -.. _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 -instructions please see the :ref:`setup guide `. - -1. Install and set up :ref:`Git ` and other dependencies - (see the :ref:`Git Setup ` page for detailed information). - -2. Fork `the CPython repository `__ - to your GitHub account and :ref:`get the source code ` using:: - - git clone https://github.com//cpython - cd cpython - -3. Build Python: - - .. tab:: Unix - - .. code-block:: shell - - ./configure --config-cache --with-pydebug && make -j $(nproc) - - .. tab:: macOS - - .. code-block:: shell - - ./configure --config-cache --with-pydebug && make -j8 - - .. tab:: Windows - - .. code-block:: dosbatch - - PCbuild\build.bat -e -d - - See also :ref:`more detailed instructions `, - :ref:`how to install and build dependencies `, - and the platform-specific pages for :ref:`Unix `, - :ref:`macOS `, and :ref:`Windows `. - -4. :ref:`Run the tests `: - - .. tab:: Unix - - .. code-block:: shell - - ./python -m test -j3 - - .. tab:: macOS - - .. code-block:: shell - - ./python.exe -m test -j8 - - .. note:: - :ref:`Most ` macOS systems use - :file:`./python.exe` in order to avoid filename conflicts with - the ``Python`` directory. - - .. tab:: Windows - - .. code-block:: dosbatch - - .\python.bat -m test -j3 - -5. Create a new branch where your work for the issue will go, for example:: - - git checkout -b fix-issue-12345 main - - If an issue does not already exist, please `create it - `__. Trivial issues (for example, typos) do - not require an issue. - -6. Push the branch on your fork on GitHub and :ref:`create a pull request - `. 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 - -7. 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 - `repository `__. - .. note:: - First time contributors will need to sign the Contributor Licensing - Agreement (CLA) as described in the :ref:`Licensing ` section of - this guide. + The quick reference documentation has been moved to serve as a cheat-sheet and overview + in :ref:`Getting started `. +Go to :ref:`the new quick reference `. Proposing changes to Python itself ---------------------------------- From 323504382da8dc0e673688db02048b33c9668ee3 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Tue, 30 Jun 2026 09:53:16 +0200 Subject: [PATCH 43/85] Add note on referencing provisional CVE IDs to CPython Security Policy (#1847) --- security/policy.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/security/policy.rst b/security/policy.rst index d1accf3c09..d49f4dedb7 100644 --- a/security/policy.rst +++ b/security/policy.rst @@ -138,6 +138,8 @@ Here's what to expect for how a vulnerability report will be handled: may open a public issue. * If the PSRT determines the report is a vulnerability, the PSRT will accept the report and a CVE ID will be assigned by the PSF CNA. + Do not publicly reference the assigned CVE ID before its record is published, + as the report and ID remain provisional and may still be changed. * Once a public pull request containing a fix is merged to CPython, the advisory and CVE record will be published with attribution. From b958b900354ea6612b77851225ad254bd50c81bf Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Wed, 1 Jul 2026 04:10:57 +0200 Subject: [PATCH 44/85] Bump the actions group with 2 updates (#1852) Bumps the actions group with 2 updates: [actions/checkout](https://github.com/actions/checkout) and [sphinx-doc/github-problem-matcher](https://github.com/sphinx-doc/github-problem-matcher). Updates `actions/checkout` from 6.0.2 to 7.0.0 - [Release notes](https://github.com/actions/checkout/releases) - [Changelog](https://github.com/actions/checkout/blob/main/CHANGELOG.md) - [Commits](https://github.com/actions/checkout/compare/de0fac2e4500dabe0009e67214ff5f5447ce83dd...9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0) Updates `sphinx-doc/github-problem-matcher` from 1.0 to 1.1 - [Release notes](https://github.com/sphinx-doc/github-problem-matcher/releases) - [Commits](https://github.com/sphinx-doc/github-problem-matcher/compare/d521df655a8af22fcc69e4f4af8b1f25699ee754...1f74d6599f4a5e89a20d3c99aab4e6a70f7bda0f) --- updated-dependencies: - dependency-name: actions/checkout dependency-version: 7.0.0 dependency-type: direct:production update-type: version-update:semver-major dependency-group: actions - dependency-name: sphinx-doc/github-problem-matcher dependency-version: '1.1' dependency-type: direct:production update-type: version-update:semver-minor dependency-group: actions ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- .github/workflows/ci.yml | 4 ++-- .github/workflows/lint.yml | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 469092a3a4..84e4577733 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -14,7 +14,7 @@ jobs: timeout-minutes: 10 steps: - - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 with: persist-credentials: false - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0 @@ -22,7 +22,7 @@ jobs: python-version: "3" - name: Install uv uses: hynek/setup-cached-uv@4300ec2180bc77d705e626a34e381b81a4772c51 # v2.5.0 - - uses: sphinx-doc/github-problem-matcher@d521df655a8af22fcc69e4f4af8b1f25699ee754 # v1.0 + - uses: sphinx-doc/github-problem-matcher@1f74d6599f4a5e89a20d3c99aab4e6a70f7bda0f # v1.1 - name: Build docs run: make html - name: Link check diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index a3972b812a..0aa7faf8e3 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/lint.yml @@ -14,7 +14,7 @@ jobs: timeout-minutes: 10 steps: - - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 with: persist-credentials: false - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0 From 7f0ae09df6cf971ff0fb3240b4aaded172e4b02d Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Wed, 1 Jul 2026 07:53:03 +0200 Subject: [PATCH 45/85] Move `links.rst` to `includes/` (#1851) --- getting-started/setup-building.rst | 2 +- links.rst => include/links.rst | 0 2 files changed, 1 insertion(+), 1 deletion(-) rename links.rst => include/links.rst (100%) diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index d653fd73a7..c419c9cf72 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -1338,4 +1338,4 @@ also apply here. .. _cpython-devcontainers repo: https://github.com/python/cpython-devcontainers -.. include:: ../links.rst +.. include:: /include/links.rst diff --git a/links.rst b/include/links.rst similarity index 100% rename from links.rst rename to include/links.rst From 627b1ab94d43f3ae9b06716540d01406626f86fc Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Wed, 1 Jul 2026 13:21:34 +0200 Subject: [PATCH 46/85] Update Porting page, move platform experts list there (GH-1839) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Co-authored-by: Miro Hrončok --- conf.py | 1 + core-team/experts.rst | 18 +--- developer-workflow/porting.rst | 163 ++++++++++++++++++++++++++++++--- 3 files changed, 155 insertions(+), 27 deletions(-) diff --git a/conf.py b/conf.py index 020e6bf6af..27795dd484 100644 --- a/conf.py +++ b/conf.py @@ -276,6 +276,7 @@ "gh-label": (f"{_repo}/labels/%s", "%s"), "github": ("https://github.com/%s", "%s"), "github-user": ("https://github.com/%s", "@%s"), + "gh-python-team": ("https://github.com/orgs/python/teams/%s", "@python/%s"), "pypi": ("https://pypi.org/project/%s/", "%s"), "pypi-org": ("https://pypi.org/org/%s/", "%s"), } diff --git a/core-team/experts.rst b/core-team/experts.rst index a5fd9c9358..8152cb09e2 100644 --- a/core-team/experts.rst +++ b/core-team/experts.rst @@ -179,23 +179,9 @@ PEG Generator gvanrossum, pablogsal, lysnikolaou Platforms ========= -For official contacts for supported platforms, see :pep:`11`. +The **Platforms experts list** has moved to :ref:`ports`. -Platforms listed here are not necessarily supported by CPython. -Some of the experts listed here maintain and distribute Python -for “their” platform as a third-party project. - -=================== =========== -Platform Maintainers -=================== =========== -AIX ayappanec -Android mhsmith -Emscripten hoodmane, pmp-p, rdb, rth, ryanking13 -iOS freakboy3742, ned-deily -macOS ronaldoussoren, ned-deily, freakboy3742 -Solaris/OpenIndiana jcea, kulikjak -Windows tjguk, zooba, pfmoore -=================== =========== +For official contacts for supported platforms, see :pep:`11`. Miscellaneous diff --git a/developer-workflow/porting.rst b/developer-workflow/porting.rst index f308e6c14b..27eba0c5b9 100644 --- a/developer-workflow/porting.rst +++ b/developer-workflow/porting.rst @@ -1,9 +1,131 @@ .. _porting: -========================= +============================ +Porting and platform support +============================ + +The Python interpreter runs on an underlying *platform* -- the operating system +(for example, Linux, Windows or macOS), processor (like Intel/AMD, ARM), +C compiler and library, and other "lower level" details. + +CPython is *officially supported* on several platforms, on which the core team +has adequate knowledge and resources to test releases and fix bugs. +See :pep:`11` for details. + +Other platforms are unsupported *by the core team*, but might be supported +by others -- as a volunteer project, by a company that wants Python on "their" +system, or just as a one-off experiment. +See :pep:`PEP 11 <11#unsupported-platforms>` for the policy on merging code for +unsupported platforms into the main CPython repository. + + +.. _ports: + +Ports and contacts +================== + +The table below lists relevant third-party projects, +their maintainers, and links to information that's relevant when triaging +platform-specific issues. +Officially supported platforms are also included when there is relevant +information for them (beyond :pep:`11`), or to group similar platforms. + +It is OK to @mention the listed GitHub usernames to draw maintainers' attention +or request their opinion on platform-specific issues. +Maintainers must only be listed with their permission, and they may remove +themselves at any time. + +Third-party projects should only be listed if they benefit substantially +more people than the maintainers. + +Links should be for the port specifically (not the platform itself), +and relevant for porting work and fixing platform-specific issues +(no homepage/marketing links). + +.. list-table:: + :header-rows: 1 + + * - Platform + - Maintainers + - Information + * - **AIX** + - :github-user:`ayappanec` + - + * - **Android** [t3]_ + - :github-user:`mhsmith` + - `Usage `__, + `Limitations `__, + :cpy-file:`Platforms/Android` + * - **iOS** [t3]_ + - :github-user:`freakboy3742`, :github-user:`ned-deily` + - `Usage `__, + `Limitations `__, + :cpy-file:`Platforms/Apple` + * - **Linux** [t1]_ + - + - + * - \- Fedora + - :github-user:`hroncok`, :github-user:`befeleme` + - `Config & patches `_, + `Bugs `__, + `Maintenance guide `__ + * - \- Debian + - :github-user:`stefanor` + - `Config & patches `_, + `Bugs `__, + `Wiki `__ + * - \- Ubuntu + - :github-user:`stefanor` + - `Config & patches `_ (by version), + `Bugs `__ + * - \- Alpine + - + - `Config & patches `_ + * - **macOS** [t1]_ + - :gh-python-team:`macos-team`, :github-user:`freakboy3742` + - `Usage `__, + :cpy-file:`Platforms/Apple` + * - **Solaris**/OpenIndiana + - :github-user:`jcea`, :github-user:`kulikjak` + - + * - **WebAssembly** + - + - `Limitations `__ + * - \- WASI [t2]_ + - + - :cpy-file:`WASI ` + * - \- Emscripten [t3]_ + - :github-user:`pmp-p`, :github-user:`rdb`, :github-user:`hoodmane` + - :cpy-file:`emscripten ` + * - \- Pyodide + - :github-user:`ryanking13`, :github-user:`agriyakhetarpal` + - + * - **Windows** [t1]_ + - :gh-python-team:`windows-team`, :github-user:`pfmoore` + - `Usage `__, + :cpy-file:`PC`, + :cpy-file:`PCbuild` + * - **Cross-Platform** + - + - + * - \- conda-forge + - + - `Recipe `_ + +.. [t1] Specific variants have official :pep:`Tier 1 support <11#tier-1>` +.. [t2] Specific variants have official :pep:`Tier 2 support <11#tier-2>` +.. [t3] Specific variants have official :pep:`Tier 3 support <11#tier-3>` + + Porting to a new platform ========================= +Porting CPython to an entirely new platform is an adventure. +If you try it, consider keeping notes -- and updating this guide, if you +find something that might be relevant to others. +Since each platform is different, this guide can only give you a +few rough tips. + The first step is to familiarize yourself with the development toolchain on the platform in question, notably the C compiler. Make sure you can compile and run a hello-world program using the target compiler. @@ -12,23 +134,39 @@ Next, learn how to compile and run the Python interpreter on a platform to which it has already been ported; preferably Unix, but Windows will do, too. The build process for Python, in particular the ``Makefile`` in the source distribution, will give you a hint on which files to compile -for Python. Not all source files are relevant: some are platform-specific, -and others are only used in emergencies (for example, ``getopt.c``). +for Python. Not all source files are relevant: some are platform-specific, +and others are only used in emergencies (for example, +:cpy-file:`Python/getopt.c`). It is not recommended to start porting Python without at least a medium-level understanding of your target platform; how it is generally used, how to write platform-specific apps, and so on. Also, some Python knowledge is required, or you will be unable to verify that your port is working correctly. -You will need a ``pyconfig.h`` file tailored for your platform. You can -start with ``pyconfig.h.in``, read the comments, and turn on definitions that -apply to your platform. Also, you will need a ``config.c`` file, which lists -the built-in modules you support. Again, starting with -``Modules/config.c.in`` is recommended. +On systems with a UNIX shell, run the included :cpy-file:`configure` script. +This should generate all required files, including a :file:`Makefile`. +If it does not, you will need to debug it (or reimplement it). +Note that the script is generated from :cpy-file:`configure.ac` using GNU +Autotools. +(CPython pins a specific version for reproducibility, but other versions may +work fine.) + +The main files that ``configure`` generates -- and which you might want to +check -- are: -Finally, you will run into some things that are not supported on your -target platform. Forget about the ``posix`` module in the beginning. You can -simply comment it out of the ``config.c`` file. +* A :file:`pyconfig.h` file tailored for your platform. + If you need to create this manually, start with :cpy-file:`pyconfig.h.in`, + read the comments, and turn on definitions that apply to your platform. +* A :file:`config.c` file, which lists the built-in modules you support. + Until you get dynamic extension loading to work, all compiled modules + you need to import will need to be listed here. + The file is generated from :cpy-file:`Modules/config.c.in`. +* A :file:`Makefile` with instructions to put everything together. + If one isn't generated, try compiling all the ``*.c`` files, and fix the + errors -- or omit files that don't look important. + For example, forget about the ``posix`` module + (:cpy-file:`Modules/posixmodule.c`) in the beginning: don't compile it, + and comment it out of the :file:`config.c` file. Keep working on it until you get a ``>>>`` prompt. You may have to disable the importing of ``site.py`` by passing the ``-S`` option. When you have a prompt, @@ -38,6 +176,9 @@ At some point you will want to use the ``os`` module; this is the time to start thinking about what to do with the ``posix`` module. It is okay to simply comment out functions in the ``posix`` module that cause problems; the remaining ones will be quite useful. +You can use the same approach for other modules too, of course. Before you are done, it is highly recommended to run the Python regression test suite, as described in :ref:`runtests`. +You will probably need to skip tests that do not make sense; for inspiration +look at how that's done for the WASI platform. From 17ee1fd3e40ea64c1c2da9af15350d262ad84e8f Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Thu, 2 Jul 2026 11:31:00 +0300 Subject: [PATCH 47/85] Use the `gh-python-team` role (GH-1853) Co-authored-by: Stan Ulbrych --- core-team/team-log.rst | 4 +--- developer-workflow/development-cycle.rst | 2 +- documentation/help-documenting.rst | 4 ++-- documentation/translations/coordinating.rst | 2 +- documentation/translations/translating.rst | 2 +- testing/oss-fuzz.rst | 5 ++--- 6 files changed, 8 insertions(+), 11 deletions(-) diff --git a/core-team/team-log.rst b/core-team/team-log.rst index 77639ebf1d..3b438abc49 100644 --- a/core-team/team-log.rst +++ b/core-team/team-log.rst @@ -18,10 +18,8 @@ Procedure for granting or dropping access ----------------------------------------- To be granted the ability to manage who is a committer, you must be a -team maintainer of the `Python core team`_ on GitHub. Once you have +team maintainer of the :gh-python-team:`python-core` team on GitHub. Once you have that privilege you can add people to the team. They will be asked to accept the membership which they can do by visiting https://github.com/python and clicking on the appropriate button that will be displayed to them in the upper part of the page. - -.. _Python core team: https://github.com/orgs/python/teams/python-core diff --git a/developer-workflow/development-cycle.rst b/developer-workflow/development-cycle.rst index 5d9073ed3e..bcc78d842f 100644 --- a/developer-workflow/development-cycle.rst +++ b/developer-workflow/development-cycle.rst @@ -310,7 +310,7 @@ Current owners Certain actions (blocking spam accounts, inviting new users, adjusting organization-level settings) can only `be performed`_ by owners of the Python -organization on GitHub. The ``@python/organization-owners`` team can be +organization on GitHub. The :gh-python-team:`organization-owners` team can be mentioned to request assistance from an organization owner. .. _be performed: https://docs.github.com/en/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization#permissions-for-organization-roles diff --git a/documentation/help-documenting.rst b/documentation/help-documenting.rst index 23520375cb..d9894573cb 100644 --- a/documentation/help-documenting.rst +++ b/documentation/help-documenting.rst @@ -92,8 +92,8 @@ section containing multiple problems; instead, file several issues so that it is easier to break the work up for multiple people and more efficient review. For help with the finer points of English technical writing, mention the -`@python/proofreaders `__ -team in your issue or pull request in any `@python `__ +:gh-python-team:`proofreaders` +team in your issue or pull request in any :github:`python` repo. If you'd like to join the team, `open a core-workflow issue `__ similar to diff --git a/documentation/translations/coordinating.rst b/documentation/translations/coordinating.rst index 82cfce74fa..1936dbb7bb 100644 --- a/documentation/translations/coordinating.rst +++ b/documentation/translations/coordinating.rst @@ -15,7 +15,7 @@ Discussions about translations occur on the Python Docs Discord `#translations channel `__ and the `translations category `_ of the Python Discourse. -For administrative issues, ping ``@python/editorial-board``. +For administrative issues, ping :gh-python-team:`editorial-board`. Starting a new translation diff --git a/documentation/translations/translating.rst b/documentation/translations/translating.rst index d954004b9a..e75ccb93c0 100644 --- a/documentation/translations/translating.rst +++ b/documentation/translations/translating.rst @@ -371,7 +371,7 @@ The coordination team for my language is inactive, what do I do? If you would like to coordinate, open a pull request in the `devguide `__ adding yourself to the table -at the top of this page, and ping ``@python/editorial-board``. +at the top of this page, and ping :gh-python-team:`editorial-board`. How do I merge translations back in after docs are moved? diff --git a/testing/oss-fuzz.rst b/testing/oss-fuzz.rst index ec2449a4fd..4bf4a5b419 100644 --- a/testing/oss-fuzz.rst +++ b/testing/oss-fuzz.rst @@ -16,15 +16,14 @@ CPython has two OSS-Fuzz projects: * `python3-libraries `__: The fuzz targets, seed corpora, and dictionaries can be found in the :github:`python/library-fuzzers` repository. Access to the repository is - managed through the `@python/fuzzers - `__ team on GitHub. + managed through the :gh-python-team:`fuzzers` team on GitHub. OSS-Fuzz bug reports are private when filed, so access to crash details and reproducer test cases is limited to those listed in the ``auto_ccs`` fields of the OSS-Fuzz project configuration files. Those listed can log into https://oss-fuzz.com/ with their Google account to view crash details, reproducer test cases, and project statistics. -If you need access, contact the ``@python/fuzzers`` team. +If you need access, contact the :gh-python-team:`fuzzers` team. Completed issues, and issues that remain unresolved after 90 days, are publicly visible in the `OSS-Fuzz issue tracker `__. From 49331f5276c690f47eaf01424408153069cbfc88 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Sat, 4 Jul 2026 21:40:31 +0200 Subject: [PATCH 48/85] Disperse the 'GitHub issues for BPO users' page (#1850) Co-authored-by: Ned Batchelder --- triage/github-bpo-faq.rst | 97 ++------------------------------------- triage/index.rst | 1 - triage/issue-tracker.rst | 89 ++++++++++++++++++++++++++++------- 3 files changed, 77 insertions(+), 110 deletions(-) diff --git a/triage/github-bpo-faq.rst b/triage/github-bpo-faq.rst index f4f8b16dd4..383bd7d53e 100644 --- a/triage/github-bpo-faq.rst +++ b/triage/github-bpo-faq.rst @@ -1,3 +1,5 @@ +:orphan: + .. _github-bpo-faq: .. _gh-faq: @@ -5,97 +7,8 @@ GitHub issues for BPO users =========================== -Here are some frequently asked questions about how to do things in -GitHub issues that you used to be able to do on `bpo`_. - -Before you ask your own question, make sure you read :ref:`tracker` -and :ref:`triaging` (specifically including :ref:`gh-labels`) as those -pages include a lot of introductory material. - -How to format my comments nicely? -================================= - -There is a wonderful `beginner guide to writing and formatting on GitHub -`__. -Highly recommended. - -One pro-tip we can sell you right here is that if you want to paste -some longer log as a comment, attach a file instead (see how below). -If you still insist on pasting it in your comment, do it like this:: - -
- This is the summary text, click me to expand - - Here goes the long, long text. - It will be collapsed by default! -
- -How to attach files to an issue? -================================ - -Drag them into the comment field, wait until the file uploads, and GitHub -will automatically put a link to your file in your comment text. - -How to link to file paths in the repository when writing comments? -================================================================== - -Use Markdown links. If you link to the default GitHub path, the file -will link to the latest current version on the given branch. - -You can get a permanent link to a given revision of a given file by -`pressing "y" `__. - -How to do advanced searches? -============================ - -Use the `GitHub search syntax`_ or the interactive `advanced search`_ form -that generates search queries for you. - -Where is the "nosy list"? -========================= - -Subscribe another person to the issue by tagging them in the comment with -``@username``. - -If you want to subscribe yourself to an issue, click the -:guilabel:`🔔 Subscribe` button in the sidebar. - -Similarly, if you were tagged by somebody else but -decided this issue is not for you, you might click the -:guilabel:`🔕 Unsubscribe` button in the sidebar. - -There is no exact equivalent of the "nosy list" feature, so to preserve -this information during the transfer, we list the previous members of -this list in the first message on the migrated issue. - -How to add issue dependencies? -============================== - -Add a checkbox list like this in the issue description:: - - - [x] #739 - - [ ] https://github.com/octo-org/octo-repo/issues/740 - - [ ] Add delight to the experience when all tasks are complete :tada: - -then those will become sub-tasks on the given issue. Moreover, GitHub will -automatically mark a task as complete if the other referenced issue is -closed. More details in the `official GitHub documentation -`__. - -What on earth is a "mannequin"? -=============================== - -For issues migrated to GitHub from `bpo`_ where the authors or commenters -are not core developers, we opted not to link to their GitHub accounts -directly. Users not in the `python organization on GitHub -`__ might not like comments to -appear under their name from an automated import. Others never linked GitHub on -`bpo`_ in the first place so linking their account, if any, would be impossible. - -In those cases a "mannequin" account is present to help follow the conversation -that happened in the issue. In case the user did share their GitHub account -name in their `bpo`_ profile, we use that. Otherwise, their classic `bpo`_ -username is used instead. +Here are some frequently asked questions about things you used to be able +to do on `bpo`_ that work differently in GitHub issues. Where did the "resolution" field go? ==================================== @@ -120,5 +33,3 @@ particularly useful outside of the change log. .. _bpo: https://bugs.python.org/ -.. _GitHub search syntax: https://docs.github.com/en/search-github/getting-started-with-searching-on-github/understanding-the-search-syntax -.. _advanced search: https://github.com/search/advanced diff --git a/triage/index.rst b/triage/index.rst index a054ad62f2..495d93917f 100644 --- a/triage/index.rst +++ b/triage/index.rst @@ -8,5 +8,4 @@ Issues and triaging issue-tracker triaging labels - github-bpo-faq triage-team diff --git a/triage/issue-tracker.rst b/triage/issue-tracker.rst index 31673d9435..55fd81160d 100644 --- a/triage/issue-tracker.rst +++ b/triage/issue-tracker.rst @@ -5,7 +5,6 @@ Issue tracker ============= - Using the issue tracker ======================= @@ -13,8 +12,8 @@ If you think you have found a bug in Python, you can report it to the `issue tracker`_. The `issue tracker`_ is now hosted on GitHub, alongside the codebase and pull requests. Documentation bugs can also be reported there. -If you would like to file an issue about this devguide, please do so at the -`devguide repo`_. +If you would like to file an issue about this devguide, please do so in the +:github:`devguide repository `. .. note:: Prior to moving the issue tracker to GitHub, @@ -26,8 +25,7 @@ If you would like to file an issue about this devguide, please do so at the If you're familiar with ``bpo`` and would like to learn more about GitHub issues, please read this page, and the :ref:`triaging` page as they - provide good introductory material. There is also a :ref:`gh-faq` - document to answer some of the more popular questions. + provide good introductory material. Checking if a bug already exists -------------------------------- @@ -43,12 +41,22 @@ already been reported. Checking if the problem is an existing issue will: is needed To see if an issue already exists, search the bug database using the search box -above the list of bugs on the issues page. A form-based `advanced search`_ query -builder is also available on GitHub to help creating the text query you need. +above the list of bugs on the issues page. See :ref:`searching-gh-issues` +for more information. + +.. _searching-gh-issues: + +How to search issues? +--------------------- + +Use the `GitHub search syntax`_ or the interactive `advanced search`_ form +that generates search queries for you. Reporting an issue ------------------ +.. XXX: This section is slightly out of date after recent tracker changes. + If the problem you're reporting is not already in the `issue tracker`_, you can report it using the green :guilabel:`New issue` button on the right of the search box above the list of bugs. If you're not already signed in to GitHub, it @@ -89,6 +97,32 @@ and **Projects**. Those are filled by triagers and core developers and are covered in the :ref:`triaging` page. You don't need to worry about those when reporting issues as a Python user. +Formatting issues and comments +------------------------------ + +There is a wonderful `beginner guide to writing and formatting on GitHub +`__. +Highly recommended. + +One pro-tip we can sell you right here is that if you want to paste +some longer log as a comment, attach a file instead (see how below). +If you still insist on pasting it in your comment, do it like this:: + +
+ This is the summary text, click me to expand + + Here goes the long, long text. + It will be collapsed by default! +
+ + +How to attach files to an issue? +-------------------------------- + +Drag them into the comment field, wait until the file uploads, and GitHub +will automatically put a link to your file in your comment text. + + Adding special links -------------------- @@ -104,20 +138,48 @@ Following issues ---------------- If you want to subscribe yourself to an issue, click the :guilabel:`🔔 Subscribe` -button in the sidebar. Similarly, if you were tagged by somebody else but -decided this issue is not for you, click the :guilabel:`🔕 Unsubscribe` +button in the sidebar. Subscribe another person to the issue by tagging them +in a comment with ``@username``. If you were tagged by somebody else +but decided this issue is not for you, click the :guilabel:`🔕 Unsubscribe` button in the sidebar. Note that you are automatically subscribed to -issues you created. +issues you create or comment on. + + +How to link to file paths in the repository when writing comments? +------------------------------------------------------------------ + +Use Markdown links. If you link to the default GitHub path, the file +will link to the latest current version on the given branch. + +You can get a permanent link to a given revision of a given file by +`pressing "y" `__. Tracking dependencies and duplicates ------------------------------------ +.. XXX These no longer work, the feature has been retired. + It is possible to use `checklists`_ to track dependencies or, in case of meta-issues, to link to the other related issues. By writing :samp:`Duplicate of #{NNN}` in a comment, you can `mark issues and PRs as duplicates `_. +What on earth is a "mannequin"? +------------------------------- + +For old issues migrated to GitHub from bugs.python.org (BPO) where the authors or commenters +were not core team members, we opted not to link to their GitHub accounts +directly. Users not in the `python organization on GitHub +`__ might not like comments to +appear under their name from an automated import. Others never linked GitHub on +BPO in the first place so linking their account, if any, would be impossible. + +In those cases a "mannequin" account is present to help follow the conversation +that happened in the issue. In case the user did share their GitHub account +name in their BPO profile, we use that. Otherwise, their classic BPO +username is used instead. + Disagreement with a resolution on the issue tracker =================================================== @@ -141,15 +203,10 @@ As a reminder, issues closed by a core developer have already been carefully considered. Please do not reopen a closed issue. An issue can be closed with reason either as ``complete`` or ``not planned``. -.. seealso:: - - `The Python issue tracker `_ - Where to report issues about Python. - .. _issue tracker: https://github.com/python/cpython/issues .. _advanced search: https://github.com/search/advanced -.. _devguide repo: https://github.com/python/devguide/issues +.. _GitHub search syntax: https://docs.github.com/en/search-github/getting-started-with-searching-on-github/understanding-the-search-syntax .. _Roundup: https://www.roundup-tracker.org/ .. _Python Discourse: https://discuss.python.org/ .. _autolinks: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/autolinked-references-and-urls From 4ea73951538b7395daaa9a686f99834971d6b335 Mon Sep 17 00:00:00 2001 From: Stephen Rosen Date: Sun, 5 Jul 2026 10:00:00 -0500 Subject: [PATCH 49/85] Introduce "type names" section to the style guide (#1828) Co-authored-by: Stan Ulbrych Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> --- documentation/style-guide.rst | 72 ++++++++++++++++++++++++----------- 1 file changed, 50 insertions(+), 22 deletions(-) diff --git a/documentation/style-guide.rst b/documentation/style-guide.rst index 73618f9aec..9fcaefdf20 100644 --- a/documentation/style-guide.rst +++ b/documentation/style-guide.rst @@ -58,6 +58,35 @@ of these entities are not assigned any special markup, but the preferred spellings are given in :ref:`specific words` to aid authors in maintaining the consistency of presentation in the Python documentation. + +Use simple language +=================== + +Avoid esoteric phrasing where possible. Our audience is world-wide and may not +be native English speakers. + +Don't use Latin abbreviations like "e.g." or "i.e." where English words will do, +such as "for example" or "that is." + + +Charged terminology to avoid +============================ + +Avoid terminology that may be considered insensitive or exclusionary. + +.. list-table:: + :header-rows: 1 + + * - Avoid + - Instead + * - whitelist + - allowlist + * - blacklist + - blocklist, denylist + * - master/slave + - main, parent/child, server/client, primary/secondary + + .. _specific words: Specific words @@ -116,33 +145,30 @@ Unix 1970s. -Use simple language -=================== +Type names +========== -Avoid esoteric phrasing where possible. Our audience is world-wide and may not -be native English speakers. - -Don't use Latin abbreviations like "e.g." or "i.e." where English words will do, -such as "for example" or "that is." - - -Charged terminology to avoid -============================ +When writing the names of types in prose, indicate that the name is a type by +writing the name of the type exactly as it appears in source, styled as a class +reference or an unlinked class. For example, refer to dict as ``:class:`dict`‌`` +or ``:class:`!dict`‌``. -Avoid terminology that may be considered insensitive or exclusionary. +Links should be used according to the :ref:`guidance on links `. -.. list-table:: - :header-rows: 1 +Some type names are commonly understood ideas or nouns outside of Python. +For example, "tuples" are a general programming concept, as distinct from the +``tuple`` type. When referring to general ideas, do not style the relevant word +as a type. - * - Avoid - - Instead - * - whitelist - - allowlist - * - blacklist - - blocklist, denylist - * - master/slave - - main, parent/child, server/client, primary/secondary +Many types have descriptive names which may or may not exactly match their type +name. For example, "context variables" describes ``contextvars.ContextVar``, +and both "dict" and "dictonary" are used to describe ``dict``. Once it is clear +that the text refers to a specific type, use the naming which suits the context: +in the case of ``dict``, any of "dict", "dictionary", or "``:class:`dict```" may +be best. +Descriptive names should be written as common nouns, meaning they are lowercase +when not at the start of a sentence or phrase. .. index:: diataxis .. _diataxis: @@ -190,6 +216,8 @@ Please consult the `Diátaxis `__ guide for more detail. +.. _style-guide-links: + Links ===== From 784ccc2971ca9cd167f112b900284e5e2f5d0578 Mon Sep 17 00:00:00 2001 From: Pranav Choudhary Date: Thu, 9 Jul 2026 18:13:30 +0530 Subject: [PATCH 50/85] Docs: Clarify GitHub Actions re-run permissions for contributors (GH-1842) --- getting-started/pull-request-lifecycle.rst | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/getting-started/pull-request-lifecycle.rst b/getting-started/pull-request-lifecycle.rst index 47f1100c2b..351a99dbe5 100644 --- a/getting-started/pull-request-lifecycle.rst +++ b/getting-started/pull-request-lifecycle.rst @@ -667,10 +667,16 @@ list of executed checks. Clicking :guilabel:`Update branch` next to this message will merge in the latest changes from the base branch into the PR. If this still doesn't help with the failure on the PR, you can try -to re-run that particular failed check. Go to the red GitHub Action job, -click on the :guilabel:`Re-run jobs` button on the top right, and select -:guilabel:`Re-run failed jobs`. The button will only be present when all other -jobs finished running. +to re-run that particular failed check. Note that the :guilabel:`Re-run jobs` +button is only visible to members of the core and triage team. If you have those +permissions, go to the failed GitHub Action job, click :guilabel:`Re-run jobs` on +the top right, and select :guilabel:`Re-run failed jobs`. The button is only +present once all other jobs have finished. + +If don't have access to the button, ask a member of the teams to +re-run the jobs for you. Alternatively, you can re-trigger CI yourself by +pushing an empty commit, or by updating your branch with the +:guilabel:`Update branch` button. Re-running failed jobs shouldn't be your first instinct but it is occasionally helpful because distributed systems can have intermittent failures, and From 8996911bc6f85f589efc3dc0111ba19351271553 Mon Sep 17 00:00:00 2001 From: Seth Michael Larson Date: Thu, 9 Jul 2026 15:55:49 -0500 Subject: [PATCH 51/85] Add Stan Ulbrych as a PSRT admin --- .github/CODEOWNERS | 2 +- security/psrt.csv | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 9c2d9d9e4a..f04c167334 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -5,4 +5,4 @@ # https://git-scm.com/docs/gitignore#_pattern_format # PSRT member list owned by PSRT admins. -security/psrt*.csv @warsaw @ewdurbin @ned-deily @sethmlarson +security/psrt*.csv @warsaw @ewdurbin @ned-deily @sethmlarson @stanfromireland diff --git a/security/psrt.csv b/security/psrt.csv index 46391d296c..14eb5cea1f 100644 --- a/security/psrt.csv +++ b/security/psrt.csv @@ -23,7 +23,7 @@ Pradyun Gedam,pradyunsg, Savannah Ostrowski,savannahostrowski,Release Manager Serhiy Storchaka,serhiy-storchaka, Seth Larson,sethmlarson,Admin -Stan Ulbrych,StanFromIreland, +Stan Ulbrych,StanFromIreland,Admin Steve Dower,zooba,Release Manager Thomas Wouters,Yhg1s,Release Manager Tim Peters,tim-one, From 8c3e25a03018f5288e33a0b4c138de136d343055 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Sat, 11 Jul 2026 12:50:41 +0300 Subject: [PATCH 52/85] Reinstate `#backport-pr-title` anchor and add explicit backport PR title guidance (#1855) Co-authored-by: Stan Ulbrych --- core-team/committing.rst | 2 ++ getting-started/git-boot-camp.rst | 14 ++++++++++++++ 2 files changed, 16 insertions(+) diff --git a/core-team/committing.rst b/core-team/committing.rst index 0a5380e0fa..d782e7f25e 100644 --- a/core-team/committing.rst +++ b/core-team/committing.rst @@ -149,6 +149,8 @@ bug fixes or security fixes. In almost all cases the fixes should first originate on ``main`` and then be ported back to older branches. +.. _backport-pr-title: + Backporting changes to an older version ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/getting-started/git-boot-camp.rst b/getting-started/git-boot-camp.rst index 95f6a94cab..4d01a851e8 100644 --- a/getting-started/git-boot-camp.rst +++ b/getting-started/git-boot-camp.rst @@ -622,6 +622,9 @@ The format of a correct backport commit message is: (cherry picked from commit ) +Here ``gh-XXXXX`` is the GitHub *issue* number, and ``(GH-XXXXX)`` is the +original *pull request* number. + An example of a bad backport commit message: .. code-block:: text @@ -631,6 +634,17 @@ An example of a bad backport commit message: * Custom message +.. _backport-pr: + +When opening the backport PR, its title PR must follow the same format as the +commit title, beginning with the ``[]`` prefix and referencing the +original PR with a ``(GH-XXXXX)`` suffix. For example: + +.. code-block:: text + :class: good + + [3.15] gh-12345: Fix the spam module (GH-24680) + After the backport PR is opened, ``miss-islington`` will link it to the original PR and remove the corresponding backport label. From 70299de5d7f59a2262433a3b3acb88f1604f2212 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miro=20Hron=C4=8Dok?= Date: Tue, 14 Jul 2026 16:24:38 +0200 Subject: [PATCH 53/85] Fix Fedora bugs link (#1859) --- developer-workflow/porting.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/developer-workflow/porting.rst b/developer-workflow/porting.rst index 27eba0c5b9..63bb45cc7b 100644 --- a/developer-workflow/porting.rst +++ b/developer-workflow/porting.rst @@ -67,7 +67,7 @@ and relevant for porting work and fixing platform-specific issues * - \- Fedora - :github-user:`hroncok`, :github-user:`befeleme` - `Config & patches `_, - `Bugs `__, + `Bugs `__, `Maintenance guide `__ * - \- Debian - :github-user:`stefanor` From 4d14223b41283599e24dcad06b08d12762c92b45 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Wed, 15 Jul 2026 19:26:12 +0200 Subject: [PATCH 54/85] Reinstate `#updating-news-and-what-s-new-in-python` anchor (#1856) --- core-team/committing.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/core-team/committing.rst b/core-team/committing.rst index d782e7f25e..cf8b36b366 100644 --- a/core-team/committing.rst +++ b/core-team/committing.rst @@ -68,7 +68,9 @@ to enter the public source tree. Ask yourself the following questions: if they haven't. For further questions about the CLA process, write to contributors@python.org. -* **Were** ``What's New in Python`` **and** ``Misc/NEWS.d/next`` **updated?** +* .. _updating-news-and-what-s-new-in-python: + + **Were** ``What's New in Python`` **and** ``Misc/NEWS.d/next`` **updated?** If the change is particularly interesting for end users (for example, new features, significant improvements, or backwards-incompatible changes), then an entry in the ``What's New in Python`` document (in ``Doc/whatsnew/``) should From 1fa671ddd7027bc3a7104271a35fa39ee99d19bb Mon Sep 17 00:00:00 2001 From: Marta Date: Sat, 18 Jul 2026 12:50:58 +0200 Subject: [PATCH 55/85] Fix typo in word hypen to hyphen in the style guide (#1864) --- documentation/style-guide.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/style-guide.rst b/documentation/style-guide.rst index 9fcaefdf20..57da4d1263 100644 --- a/documentation/style-guide.rst +++ b/documentation/style-guide.rst @@ -116,7 +116,7 @@ free-threaded open source Follow the usual English rules for compound words. When used as an adjective, hyphenate: "open-source software". When used as a noun, don't use - a hypen: "open source is a collaboration model.." + a hyphen: "open source is a collaboration model.." POSIX The name assigned to a particular group of standards. This is always From 72bfe29abeaa05aa7ee12e8385eefaa066acc298 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ra=C3=BAl=20Santos=20Quir=C3=B3s?= <130504291+raul-sq@users.noreply.github.com> Date: Sat, 18 Jul 2026 14:15:02 +0200 Subject: [PATCH 56/85] Fix link to iOS README in setup-building.rst (GH-1865) Updated link to the iOS README for debugging test failures. --- getting-started/setup-building.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index c419c9cf72..d1616fa023 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -742,7 +742,7 @@ Platforms/Apple --help`` for more details. You can also run the test suite in Xcode itself. This is required if you want to run on a physical device. See the `iOS README -`__ +`__ for details. .. c_compile_and_build_end From 550cea59eaae6ffb79ea628d9c908bb21f67be98 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Tue, 21 Jul 2026 19:37:12 +0300 Subject: [PATCH 57/85] Add Kushal Das to the PSRT (#1866) --- security/psrt-emeritus.csv | 1 - security/psrt.csv | 1 + 2 files changed, 1 insertion(+), 1 deletion(-) diff --git a/security/psrt-emeritus.csv b/security/psrt-emeritus.csv index f9d26bfba4..6f5cb17665 100644 --- a/security/psrt-emeritus.csv +++ b/security/psrt-emeritus.csv @@ -3,7 +3,6 @@ Christian Heimes,tiran, Georg Brandl,birkenfeld, Huzaifa Sidhpurwala,, Jesse Noller,, -Kushal Das,kushaldas, Mark Hammond,mhammond, Nam Nguyen,, Neal Norwitz,, diff --git a/security/psrt.csv b/security/psrt.csv index 14eb5cea1f..169b1a7eac 100644 --- a/security/psrt.csv +++ b/security/psrt.csv @@ -12,6 +12,7 @@ Gregory P. Smith,gpshead, Hugo van Kemenade,hugovk,Release Manager Jacob Coffee,JacobCoffee, Jelle Zijlstra,JelleZijlstra, +Kushal Das,kushaldas, Kirill Podoprigora,eclips4, Larry Hastings,larryhastings, Łukasz Langa,ambv,Release Manager From 0d87d7ede987867f64a64053fdf41fd45b7a918d Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Tue, 21 Jul 2026 23:32:01 +0200 Subject: [PATCH 58/85] Clarify that maintainers may close unproductive PRs without explanation (#1860) --- getting-started/ai-tools.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/getting-started/ai-tools.rst b/getting-started/ai-tools.rst index e7d94d3517..cd69987ca2 100644 --- a/getting-started/ai-tools.rst +++ b/getting-started/ai-tools.rst @@ -53,7 +53,7 @@ Unacceptable uses ================= Maintainers may close issues and PRs that are not useful or productive, -regardless of whether AI tools were used or not. +without explanation, regardless of whether AI tools were used or not. If a contributor repeatedly opens unproductive issues or PRs, they may be blocked from contributing to the project because it is disruptive and From f4a01e7781909bb74d34c2f34efc80f1aca4ef14 Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Wed, 22 Jul 2026 19:50:25 +0200 Subject: [PATCH 59/85] Add Pieter Eendebak to core dev log (#1867) --- core-team/core-team.csv | 1 + 1 file changed, 1 insertion(+) diff --git a/core-team/core-team.csv b/core-team/core-team.csv index 01187a9ead..133a4e6273 100644 --- a/core-team/core-team.csv +++ b/core-team/core-team.csv @@ -1,3 +1,4 @@ +Pieter Eendebak,eendebakpt,2026-07-08,, Seth Larson,sethmlarson,2026-06-12,, Chris Eibl,chris-eibl,2026-05-10,, Stan Ulbrych,StanFromIreland,2026-03-26,, From 049b785dc995c507d1ef72639c928ad86324ca01 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Thu, 23 Jul 2026 10:18:29 +0200 Subject: [PATCH 60/85] Minor revisions to the PSRT process documentation --- security/psrt.rst | 79 +++++++++++++++++++++++++++++++++++------------ 1 file changed, 60 insertions(+), 19 deletions(-) diff --git a/security/psrt.rst b/security/psrt.rst index 6a869de6ad..c2a98eff2e 100644 --- a/security/psrt.rst +++ b/security/psrt.rst @@ -112,9 +112,11 @@ New report in GitHub Security Advisories (GHSA) Once a report is in GHSA, a "Coordinator" must be assigned to be responsible for moving the report through the process. The "Coordinator" role is assigned using a "Credit" in a GHSA ticket -(Select 'Edit' > 'Credit' > Add GitHub username and the role 'Coordinator'). +(Select :guilabel:`Edit` > :guilabel:`Credit` > Add a GitHub username and the +'Coordinator' role). + +.. important:: -.. warning:: Assigning the "Coordinator" role to each GHSA ticket is important, as this metadata records whether a PSRT member is `"active" according to PEP 811`_ to avoid being removed due to inactivity. @@ -122,9 +124,9 @@ The "Coordinator" role is assigned using a "Credit" in a GHSA ticket .. _"active" according to PEP 811: https://peps.python.org/pep-0811/#psrt-membership-policy If a GHSA ticket is idle for three days without a coordinator -assigned a PSRT member who is not a Release Manager +assigned, a PSRT member who is not a Release Manager or Steering Council member will be automatically assigned -as coordinator by the PSRT bot. +as coordinator by the :ref:`PSRT bot `. If a coordinator can't complete the process they must find a replacement coordinator in the PSRT and re-assign the GHSA ticket. @@ -141,20 +143,28 @@ vulnerability, or as a security vulnerability. If the Coordinator needs help from core team experts in making the determination, the experts may be added as 'Collaborators' to the GHSA ticket. Accepted security vulnerabilities will be moved to the 'Draft' state in GHSA. +Only repository admins can accept advisories; however, PSRT members may accept +reports through the PSRT bot by prepending ``[ACCEPTED]`` to the GHSA's +title. If the report isn't a vulnerability, coordinators close the GHSA ticket after optionally opening a public GitHub issue. Note that reporters often will not open a GitHub issue on their own, as there is no longer an incentive -for them to do so without a CVE being assigned. +for them to do so without a CVE being assigned. Similarly to accepting, +only repository admins can close advisories; however, PSRT members may close +reports through the PSRT bot by prepending ``[CLOSED]`` (for regular bugs), +``[INVALID]`` (for spam), ``[DUPLICATE]`` (for duplicates), or ``[COMPLETED]`` +(for completed tickets where an advisory has been issued) to the GHSA's title. Remediating a vulnerability report ---------------------------------- Once a report has been accepted as a vulnerability, the remediation development process begins. Coordinators move the GHSA ticket to a 'Draft' -state using the green 'Accept as Draft' button. Once in this state, +state using the green :guilabel:`Accept as Draft` button (repository admins) +or the PSRT bot's ``[ACCEPTED]`` title tag. Once in this state, the PSRT bot will automatically assign a CVE ID from the Python Software -Foundation CVE Numbering Authority. +Foundation CVE Numbering Authority and create a temporary private fork. Once a vulnerability has been accepted there are three things the Coordinator must prepare before sending an advisory and @@ -184,9 +194,11 @@ for help in calculating a severity from other PSRT members. Developing a patch privately ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Patch development can initially be done privately by selecting the -'Start a temporary private fork' button within the GHSA ticket. Note that -due to the size of Git repositories, this fork repository may +Patch development can begin once a report has been accepted, as the PSRT bot +will automatically create a temporary private fork for the advisory. +The fork can also be created earlier by repository admins or reporters by selecting +the :guilabel:`Start a temporary private fork` button within the GHSA ticket. +Note that due to the size of Git repositories, this fork repository may take several minutes to create. Once the fork has been created any PSRT member or GHSA collaborator can clone the fork and develop a fix and push a branch: @@ -236,15 +248,18 @@ This patch can then be applied and pushed to the public GitHub repository: git apply ./ghsa-abcd-efgh-ijkl.patch git push origin branch-name -.. important:: CPython's backport infrastructure - is used for tracking backported patches. Use **one GitHub issue - per CVE** to accurately track backports of vulnerability fixes. - For new CVEs, even when related to a previous issue, **open a +.. important:: + + CPython's backport infrastructure is used for tracking backported patches. + Use **one GitHub issue per CVE** to accurately track backports of vulnerability + fixes. For new CVEs, even when related to a previous issue, **open a new GitHub issue** to accurately track fixed versions. -.. important:: Don't select the green 'Merge pull request' - or 'Publish advisory' buttons within GHSA. Advisories are published - to the mailing list, and the 'Merge pull request' button within +.. important:: + + Repository admins should not select the green :guilabel:`Publish advisory` + or :guilabel:`Merge pull request` buttons within GHSA. Advisories are published + to the mailing list, and the :guilabel:`Merge pull request` button within GHSA bypasses all continuous integration and branch protection steps. Use a public pull request instead. @@ -263,14 +278,40 @@ if applying the patch isn't the only way to mitigate the vulnerability. * The advisory email will be received by PSF CVE Numbering Authority operators and used to publish a CVE record. * Begin the backporting process for all Python branches still receiving - security updates. Add the :gh-label:`type-security` and :gh-label:`release-blocker` labels - to each backport pull request so that release managers can find them prior + security updates. Add the :gh-label:`type-security` and :gh-label:`release-blocker` + labels to each backport pull request so that release managers can find them prior to releasing. After an advisory email is sent, the GHSA ticket can be closed. +As only repository admins can close advisories directly, PSRT members +can prepend ``[COMPLETED]`` to the GHSA's title and the PSRT bot +will close the ticket. .. _advisory template: #advisory-email +.. _psrt-bot: + +The PSRT bot +------------ + +The :github:`PSRT bot ` is a GitHub App +that automates parts of the GHSA workflow described above. GitHub only +allows repository admins to modify security advisories, so the bot enables +any PSRT member to move a report through the process using title tags. + +The bot runs hourly (or by manual dispatch) and for each open GHSA ticket: + +* Adds the PSRT GitHub team as collaborators, giving members access to new reports. +* Moves tickets from the 'Triage' to the 'Draft' state when the title contains + the ``[ACCEPTED]`` tag. +* Closes tickets when the title contains one of the closing tags + (``[CLOSED]``, ``[INVALID]``, ``[DUPLICATE]``, or ``[COMPLETED]``). +* For accepted ('Draft') tickets, creates the temporary private fork if one + doesn't already exist, and reserves a CVE ID. + +Tags are case-insensitive and can appear anywhere in the title, though for visibility +they are prepended. + Handling code signing certificate reports ----------------------------------------- From 5915c2ee7ee5a6456949d46f816540b023269df7 Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Fri, 24 Jul 2026 16:08:46 +0200 Subject: [PATCH 61/85] Clarify that exceptions are not crashes in security policy --- security/policy.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/security/policy.rst b/security/policy.rst index d49f4dedb7..14e6bf0652 100644 --- a/security/policy.rst +++ b/security/policy.rst @@ -45,8 +45,10 @@ triggerable with data inputs that are reasonably sized for the use case. Availability vulnerabilities must also demonstrate an "upward" change in posture for the attacker, rather than a "lateral" one. This is to avoid handling performance improvements as security vulnerabilities. -Exceptions are an expected part of control flow when processing inputs, -therefore crashes resulting from unhandled exceptions are not security vulnerabilities. + +Exceptions are an expected part of control flow when processing inputs. +Unhandled exceptions are not considered crashes and are not, by themselves, +security vulnerabilities. Vulnerabilities in dependencies of Python (such as zlib, Tcl/Tk, or OpenSSL) are not vulnerabilities in Python unless Python's use of the dependency From 9c610bafc29fa06fea862150fa0fdadae36838f8 Mon Sep 17 00:00:00 2001 From: Mohit Yadav Date: Sun, 26 Jul 2026 21:44:01 +0530 Subject: [PATCH 62/85] Add new Punjabi translation coordinators (#1870) --- documentation/translations/translating.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/documentation/translations/translating.rst b/documentation/translations/translating.rst index e75ccb93c0..ddf31d6e6e 100644 --- a/documentation/translations/translating.rst +++ b/documentation/translations/translating.rst @@ -84,7 +84,9 @@ For more details about translations and their progress, see `Telegram `__, `article `__ * - Punjabi (pa) - - Bhuvansh Kataria (:github-user:`BHUVANSH855`) + - | Bhuvansh Kataria (:github-user:`BHUVANSH855`), + | Mohit Yadav (:github-user:`mohityadav8`), + | Yashraj Jangra (:github-user:`Yashraj-Jangra`) - :github:`GitHub `, `Transifex `_ * - `Romanian (ro) `__ From 99da8b37cab4f05b741e0bd32a111b9d4c815105 Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Mon, 27 Jul 2026 14:02:41 +0200 Subject: [PATCH 63/85] Expand "various new privileges" in the new core team member checklist (GH-1868) --- core-team/join-team.rst | 47 ++++++++++++++++++++++++++++++++++------- 1 file changed, 39 insertions(+), 8 deletions(-) diff --git a/core-team/join-team.rst b/core-team/join-team.rst index 20ce9e4c98..a0177a4601 100644 --- a/core-team/join-team.rst +++ b/core-team/join-team.rst @@ -30,8 +30,8 @@ After a candidate has demonstrated consistent contributions, commit privileges are granted through these steps: #. A core team member (submitter, usually the mentor) starts a poll - (see the :ref:`template ` below) in - the `Committers category`_ on the `Python Discourse`_. + (see the :ref:`template ` below) with + the `Promotion tag in the Committers category`_ on the `Python Discourse`_. - open for 7 days - results shown only upon closing @@ -53,16 +53,46 @@ are granted through these steps: #. Once the candidate has provided the pertinent details, the approver will: - - Enable the various new privileges. - - Remove the new committer from the triage team, if applicable. + - Enable new permissions for the new committer, and remove redundant ones + if applicable. + If you don't have admin rights, ping the given contact. + + .. list-table:: + :header-rows: 1 + :align: left + + * - Service + - Add to + - Remove from + - Contact + * - GitHub + - :gh-python-team:`python-core` + - :gh-python-team:`python-triage` + - :gh-python-team:`organization-owners` + * - Discourse + - `committers `__ + - --- + - `admins `__ + * - Core Discord + - "Core Developer" + - "Triager" + - ``@Server Admin`` + * - Docs Discord + - "Core Team" + - --- + - | ``@encukou`` (Petr) + | ``@justbinary`` (Stan) + + (Some of these are unofficial spaces managed as a courtesy. + Adjust the list to taste.) + - Add their details to `🔒 python/voters `__. - Once the python/voters update is merged, regenerate the public team membership list at :ref:`developers`. See "Public list of members" in the ``voters`` README. - - Post an announcement in the `Committers Discourse category - `__. The past few announcements - were in the form of a separate post on the already open topic with - the poll. + - Post an announcement to the Discourse topic with the promotional poll. + The topic should be in the `Promotion tag in the Committers category`_. + Getting a python.org email address ---------------------------------- @@ -114,3 +144,4 @@ The important options in the poll builder set to get this result: .. _Code of Conduct: https://policies.python.org/python.org/code-of-conduct/ .. _Committers category: https://discuss.python.org/c/committers/5 .. _Python Discourse: https://discuss.python.org +.. _Promotion tag in the Committers category: https://discuss.python.org/tags/c/committers/5/promotion/31 From 137ada6ad31c46878e31d75f8b7e99e897f04c96 Mon Sep 17 00:00:00 2001 From: Stephen Rosen Date: Tue, 28 Jul 2026 13:34:26 -0500 Subject: [PATCH 64/85] Add a note to the docs style guide about abbreviations (#1844) Co-authored-by: Stan Ulbrych Co-authored-by: Jelle Zijlstra <906600+JelleZijlstra@users.noreply.github.com> --- developer-workflow/development-cycle.rst | 2 +- developer-workflow/stdlib.rst | 4 ++-- development-tools/clinic/index.rst | 2 +- documentation/markup.rst | 8 +++++++- documentation/style-guide.rst | 6 ++++++ getting-started/pull-request-lifecycle.rst | 9 ++++----- getting-started/setup-building.rst | 3 +-- testing/coverage.rst | 2 +- 8 files changed, 23 insertions(+), 13 deletions(-) diff --git a/developer-workflow/development-cycle.rst b/developer-workflow/development-cycle.rst index bcc78d842f..17bd8c2111 100644 --- a/developer-workflow/development-cycle.rst +++ b/developer-workflow/development-cycle.rst @@ -146,7 +146,7 @@ Stages Based on what stage the :ref:`in-development ` version of Python is in, the responsibilities of a core team member change in regards to commits -to the :abbr:`VCS (version control system)`. +to the VCS (version control system). Pre-alpha diff --git a/developer-workflow/stdlib.rst b/developer-workflow/stdlib.rst index ec10977221..691fd8e4bd 100644 --- a/developer-workflow/stdlib.rst +++ b/developer-workflow/stdlib.rst @@ -109,7 +109,7 @@ Python). This prevents a divergence between the code that is included in the stdlib and that which is released outside the stdlib (typically done to provide the module to older versions of Python). It also removes the burden of forcing the core team to have to redirect bug reports or changes to an external issue -tracker and :abbr:`VCS (version control system)`. +tracker and VCS (version control system). Someone involved with the development of the module must promise to help maintain the module in the stdlib for two years. @@ -124,7 +124,7 @@ Proposal process If the module you want to propose adding to the stdlib meets the requirements, you may propose its inclusion -by following the :abbr:`PEP (Python Enhancement Proposal)` process. +by following the PEP (Python Enhancement Proposal) process. See :pep:`1` for details, and the :pep:`PEP index <0>` for previously accepted PEPs that have proposed a module for inclusion. diff --git a/development-tools/clinic/index.rst b/development-tools/clinic/index.rst index a6ddd5c721..20a834e2d8 100644 --- a/development-tools/clinic/index.rst +++ b/development-tools/clinic/index.rst @@ -148,7 +148,7 @@ Terminology Command-line interface ---------------------- -The Argument Clinic :abbr:`CLI (Command-Line Interface)` is typically used to +The Argument Clinic CLI (Command-Line Interface) is typically used to process a single source file, like this: .. code-block:: shell-session diff --git a/documentation/markup.rst b/documentation/markup.rst index 41bf5b39c6..8341278914 100644 --- a/documentation/markup.rst +++ b/documentation/markup.rst @@ -699,12 +699,18 @@ As :ref:`previously mentioned `, Sphinx uses interpreted text roles of the form ``:rolename:`content``` to insert semantic markup in documents. -In the CPython documentation, there are a couple common cases +In the CPython documentation, there are a few common cases where simpler markup should be used: * ``*arg*`` (rendered as *arg*) for function and method arguments. + * ````True````/````False````/````None```` for ``True``/``False``/``None``. +* ``Full Spelling (abbreviation)`` for abbreviations and acronyms. + + The ``:abbr:`` role generates HTML which is not accessible to some forms of + assistive technology and mobile users. + In addition, the CPython documentation defines a few custom roles: * ``:gh:`ID```: link to a GitHub issue. diff --git a/documentation/style-guide.rst b/documentation/style-guide.rst index 57da4d1263..e504f529b5 100644 --- a/documentation/style-guide.rst +++ b/documentation/style-guide.rst @@ -68,6 +68,12 @@ be native English speakers. Don't use Latin abbreviations like "e.g." or "i.e." where English words will do, such as "for example" or "that is." +In general, the first time an acronym or abbreviation is used on a page, spell +it out. +Prefer to write out the full term and follow it with the acronym in parentheses. +For example, write "Basic Multilingual Plane (BMP)". +Commonly understood acronyms, such as "HTML" and "UTF-8", should not be expanded. + Charged terminology to avoid ============================ diff --git a/getting-started/pull-request-lifecycle.rst b/getting-started/pull-request-lifecycle.rst index 351a99dbe5..5cba5f233e 100644 --- a/getting-started/pull-request-lifecycle.rst +++ b/getting-started/pull-request-lifecycle.rst @@ -710,11 +710,10 @@ do not take it personally! Your work is still appreciated regardless of whether your pull request is merged. Balancing what *does* and *does not* go into Python is tricky and we simply cannot accept everyone's contributions. -But if your pull request is merged it will then go into Python's -:abbr:`VCS (version control system)` to be released -with the next feature release of Python. It may also be backported to older -versions of Python as a bugfix if the core team member doing the merge believes -it is warranted. +But if your pull request is merged it will then go into Python's VCS (version +control system) to be released with the next feature release of Python. +It may also be backported to older versions of Python as a bugfix if the core +team member doing the merge believes it is warranted. Crediting diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index d1616fa023..8e35f8a646 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -1107,8 +1107,7 @@ every rule. See also :ref:`building-doc`. ``Grammar`` - Contains the :abbr:`PEG (Parser Expression Grammar)` grammar file for - Python. + Contains the PEG (Parser Expression Grammar) grammar file for Python. ``Include`` Contains all interpreter-wide header files. diff --git a/testing/coverage.rst b/testing/coverage.rst index 48c2efc985..54782caf11 100644 --- a/testing/coverage.rst +++ b/testing/coverage.rst @@ -7,7 +7,7 @@ Increase test coverage .. include:: /include/activate-tab.rst Python development follows a practice that all semantic changes and additions -to the language and :abbr:`stdlib (standard library)` are accompanied by +to the language and stdlib (standard library) are accompanied by appropriate unit tests. Unfortunately Python was in existence for a long time before the practice came into effect. This has left chunks of the stdlib untested which is not a desirable situation to be in. From 6399d35568eab4a5bf080f39589d54df4da77636 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Sat, 1 Aug 2026 03:35:32 +0200 Subject: [PATCH 65/85] Bump the actions group with 3 updates (#1872) Bumps the actions group with 3 updates: [actions/checkout](https://github.com/actions/checkout), [actions/setup-python](https://github.com/actions/setup-python) and [j178/prek-action](https://github.com/j178/prek-action). Updates `actions/checkout` from 7.0.0 to 7.0.1 - [Release notes](https://github.com/actions/checkout/releases) - [Changelog](https://github.com/actions/checkout/blob/main/CHANGELOG.md) - [Commits](https://github.com/actions/checkout/compare/9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0...3d3c42e5aac5ba805825da76410c181273ba90b1) Updates `actions/setup-python` from 6.2.0 to 6.3.0 - [Release notes](https://github.com/actions/setup-python/releases) - [Commits](https://github.com/actions/setup-python/compare/a309ff8b426b58ec0e2a45f0f869d46889d02405...ece7cb06caefa5fff74198d8649806c4678c61a1) Updates `j178/prek-action` from 2.0.4 to 2.0.5 - [Release notes](https://github.com/j178/prek-action/releases) - [Commits](https://github.com/j178/prek-action/compare/bdca6f102f98e2b4c7029491a53dfd366469e33d...e98a699c41eb69ab013a45817a0406469a748f8d) --- updated-dependencies: - dependency-name: actions/checkout dependency-version: 7.0.1 dependency-type: direct:production update-type: version-update:semver-patch dependency-group: actions - dependency-name: actions/setup-python dependency-version: 6.3.0 dependency-type: direct:production update-type: version-update:semver-minor dependency-group: actions - dependency-name: j178/prek-action dependency-version: 2.0.5 dependency-type: direct:production update-type: version-update:semver-patch dependency-group: actions ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- .github/workflows/ci.yml | 4 ++-- .github/workflows/lint.yml | 6 +++--- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 84e4577733..906579081b 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -14,10 +14,10 @@ jobs: timeout-minutes: 10 steps: - - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false - - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0 + - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0 with: python-version: "3" - name: Install uv diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index 0aa7faf8e3..a727a77f3c 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/lint.yml @@ -14,10 +14,10 @@ jobs: timeout-minutes: 10 steps: - - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false - - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0 + - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0 with: python-version: "3.x" - - uses: j178/prek-action@bdca6f102f98e2b4c7029491a53dfd366469e33d # v2.0.4 + - uses: j178/prek-action@e98a699c41eb69ab013a45817a0406469a748f8d # v2.0.5 From 8446273b809917a8d1329406d0d819c828490af7 Mon Sep 17 00:00:00 2001 From: Swen <142266608+sba72@users.noreply.github.com> Date: Sun, 2 Aug 2026 20:02:14 +0200 Subject: [PATCH 66/85] Add German docs translation coordinator details (#1871) Co-authored-by: Stan Ulbrych --- documentation/translations/translating.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/documentation/translations/translating.rst b/documentation/translations/translating.rst index ddf31d6e6e..ab5409522c 100644 --- a/documentation/translations/translating.rst +++ b/documentation/translations/translating.rst @@ -34,6 +34,9 @@ For more details about translations and their progress, see - Julien Palard (:github-user:`JulienPalard`) - `AFPy/python-docs-fr `__, :github:`mirror ` + * - German (de) + - Swen Bachmann (:github-user:`sba72`) + - :github:`GitHub ` * - `Greek (el) `__ - | Lysandros Nikolaou (:github-user:`lysnikolaou`), | Fanis Petkos (:github-user:`thepetk`), From 4f75bd43b018efd46d69ee7b9a5a37e6685a9c0d Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Mon, 3 Aug 2026 21:34:02 +0200 Subject: [PATCH 67/85] Reorganize the 'Issue tracker' section (#1854) --- index.rst | 1 - triage/issue-tracker.rst | 139 +++++++++++++++++++++++---------------- triage/triaging.rst | 13 ++-- 3 files changed, 87 insertions(+), 66 deletions(-) diff --git a/index.rst b/index.rst index 9067b92031..84936f3ecf 100644 --- a/index.rst +++ b/index.rst @@ -50,7 +50,6 @@ contributors through the process. * :ref:`helptriage` * :ref:`experts` * :ref:`labels` - * :ref:`gh-faq` * :ref:`triage-team` We **recommend** that sections of this guide be read as needed. You diff --git a/triage/issue-tracker.rst b/triage/issue-tracker.rst index 55fd81160d..e55cda18c5 100644 --- a/triage/issue-tracker.rst +++ b/triage/issue-tracker.rst @@ -1,31 +1,33 @@ .. _issue-tracker: .. _tracker: -============= -Issue tracker -============= - +======================= Using the issue tracker ======================= +The `issue tracker`_ is hosted on GitHub, alongside the codebase and pull requests. + +.. note:: + + Prior to moving the issue tracker to GitHub, + Python used to use a dedicated `Roundup`_ instance as its issue tracker. + That `old bug tracker`_ was hosted under the domain ``bugs.python.org`` + (sometimes called :dfn:`bpo` or :dfn:`BPO` for short). A read-only version is + available on that domain for historical purposes. All ``bpo`` data has been + migrated to the current issue tracker on GitHub. + Old issues are still referenced in the :samp:`bpo-{NNN}` format, + where ``bpo-12345`` refers to ``https://bugs.python.org/issue12345``. + + +Reporting an issue +================== + If you think you have found a bug in Python, you can report it to the -`issue tracker`_. The `issue tracker`_ is now hosted on GitHub, alongside -the codebase and pull requests. Documentation bugs can also be reported there. +`issue tracker`_. Documentation bugs can also be reported there. If you would like to file an issue about this devguide, please do so in the -:github:`devguide repository `. +:github:`devguide repository ` instead. -.. note:: - Prior to moving the issue tracker to GitHub, - Python used to use a dedicated `Roundup`_ instance as its issue tracker. - That `old bug tracker`_ was hosted under the domain ``bugs.python.org`` - (sometimes called ``bpo`` for short). A read-only version is - available on that domain for historical purposes. All ``bpo`` data has been - migrated to the current `issue tracker`_ on GitHub. - - If you're familiar with ``bpo`` and would like to learn more about GitHub - issues, please read this page, and the :ref:`triaging` page as they - provide good introductory material. Checking if a bug already exists -------------------------------- @@ -44,18 +46,9 @@ To see if an issue already exists, search the bug database using the search box above the list of bugs on the issues page. See :ref:`searching-gh-issues` for more information. -.. _searching-gh-issues: -How to search issues? ---------------------- - -Use the `GitHub search syntax`_ or the interactive `advanced search`_ form -that generates search queries for you. - -Reporting an issue ------------------- - -.. XXX: This section is slightly out of date after recent tracker changes. +Creating a new issue +-------------------- If the problem you're reporting is not already in the `issue tracker`_, you can report it using the green :guilabel:`New issue` button on the right of the search @@ -71,14 +64,15 @@ available choices include, for example: * **Report a security vulnerability**: privately report a security vulnerability. Depending on your choice, a dedicated form template will appear. -In particular, you'll notice that the last button actually takes you to +In particular, you'll notice that one of the buttons actually takes you to the `Python Discourse`_ (``discuss.python.org``), where many Python-related discussions take place. The submission form has only two fields that you need to fill: * in the **Title** field, enter a *very* short description of the problem; - less than ten words is good; + less than ten words is good; don't include "labels" like ``[feature]`` + as we use GitHub labels; * in the **Write** field, describe the problem in detail using hints from the template that was put in that field for you. Be sure to include what you expected to happen, what did happen, and how to replicate the @@ -93,10 +87,32 @@ Use the :ref:`experts` to know who wants to be tagged or assigned for specific areas. There are a number of additional fields like **Assignees**, **Labels**, -and **Projects**. Those are filled by triagers and core -developers and are covered in the :ref:`triaging` page. You don't need +and **Projects**. Those are filled by triagers and core team members +and are covered in the :ref:`triaging` page. You don't need to worry about those when reporting issues as a Python user. + +Working with issues +=================== + +This section covers common tasks on the issue tracker, such as +searching, commenting on, and following issues. + +.. _searching-gh-issues: +.. _how-to-search-issues: + +Searching issues +---------------- + +Use the `GitHub search syntax`_ or the interactive `advanced search`_ form +that generates search queries for you. + +You can also narrow down the results by filtering by label, either with +the :guilabel:`Labels` dropdown above the list of issues or with the +:samp:`label:{name}` search qualifier. See :ref:`gh-labels` for an +overview of the labels used in the CPython repository. + + Formatting issues and comments ------------------------------ @@ -105,8 +121,9 @@ There is a wonderful `beginner guide to writing and formatting on GitHub Highly recommended. One pro-tip we can sell you right here is that if you want to paste -some longer log as a comment, attach a file instead (see how below). -If you still insist on pasting it in your comment, do it like this:: +some longer log as a comment, :ref:`attach a file instead `. +If you still insist on pasting it in your comment, wrap it with a +`collapsed section`_ using ``
`` for better readability::
This is the summary text, click me to expand @@ -116,15 +133,21 @@ If you still insist on pasting it in your comment, do it like this::
-How to attach files to an issue? --------------------------------- +.. _attaching-to-gh-issues: +.. _how-to-attach-files-to-an-issue: + +Attaching files +--------------- Drag them into the comment field, wait until the file uploads, and GitHub will automatically put a link to your file in your comment text. -Adding special links --------------------- +.. _adding-special-links: +.. _how-to-link-to-file-paths-in-the-repository-when-writing-comments: + +Adding links +------------ The following abbreviations can be used in a comment to generate a link: @@ -134,6 +157,11 @@ The following abbreviations can be used in a comment to generate a link: See also the `list of autolinks supported by GitHub `_. +To link to a file in the repository, you can get a permanent link to a +given revision of the file by `pressing "y" +`__. + + Following issues ---------------- @@ -145,28 +173,21 @@ button in the sidebar. Note that you are automatically subscribed to issues you create or comment on. -How to link to file paths in the repository when writing comments? ------------------------------------------------------------------- - -Use Markdown links. If you link to the default GitHub path, the file -will link to the latest current version on the given branch. - -You can get a permanent link to a given revision of a given file by -`pressing "y" `__. - Tracking dependencies and duplicates ------------------------------------ -.. XXX These no longer work, the feature has been retired. - -It is possible to use `checklists`_ to track dependencies or, -in case of meta-issues, to link to the other related issues. +It is possible to `create relationships between issues `_ to track +dependencies and in case of meta-issues, to `add sub-issues `_ +to link to the other related issues. By writing :samp:`Duplicate of #{NNN}` in a comment, you can `mark issues and PRs as duplicates `_. -What on earth is a "mannequin"? -------------------------------- + +.. _what-on-earth-is-a-mannequin: + +Mannequin accounts +------------------ For old issues migrated to GitHub from bugs.python.org (BPO) where the authors or commenters were not core team members, we opted not to link to their GitHub accounts @@ -181,8 +202,10 @@ name in their BPO profile, we use that. Otherwise, their classic BPO username is used instead. -Disagreement with a resolution on the issue tracker -=================================================== +.. _disagreement-with-a-resolution-on-the-issue-tracker: + +Disagreement with a resolution +============================== As humans, we will have differences of opinions from time to time. First and foremost, please be respectful that care, thought, and volunteer time went into @@ -210,7 +233,9 @@ reason either as ``complete`` or ``not planned``. .. _Roundup: https://www.roundup-tracker.org/ .. _Python Discourse: https://discuss.python.org/ .. _autolinks: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/autolinked-references-and-urls -.. _checklists: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/about-task-lists +.. _collapsed section: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-collapsed-sections .. _duplicates: https://docs.github.com/en/issues/tracking-your-work-with-issues/administering-issues/marking-issues-or-pull-requests-as-a-duplicate +.. _issue-rel: https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/creating-issue-dependencies +.. _sub-issues: https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/adding-sub-issues .. _Core Development Discourse category: https://discuss.python.org/c/core-dev/23 .. _old bug tracker: https://bugs.python.org/ diff --git a/triage/triaging.rst b/triage/triaging.rst index 207c59082f..1387fa5177 100644 --- a/triage/triaging.rst +++ b/triage/triaging.rst @@ -21,8 +21,8 @@ Checklist for triaging :guilabel:`Project` fields, and possibly @mention relevant people. * You might also leave a brief comment about the proposed next action needed. If there is a long message list, a summary can be very helpful. -* If the issue is clearly invalid (unrelated to CPython, duplicate, spam, etc), - you can use GitHub's "Close as not planned" option. +* If the issue is clearly invalid (unrelated to CPython, duplicate, spam, and + so on), you can use GitHub's "Close as not planned" option. Assignees --------- @@ -36,7 +36,7 @@ how to proceed. Also consult the :ref:`experts` as certain stdlib modules should always be assigned to a specific person. Note that in order to assign an issue to someone, that person **must** be -a team member, likely a triager or a core developer. +have at least triage permissions in the repository. .. The Assignees subsection was copied from the labels.rst page in #930. For consistency, the other fields mentioned above should be documented too. @@ -105,8 +105,5 @@ Finding an issue you can help with ---------------------------------- If you want to help with triaging, you might also want to search for issues -in modules for which you have a working knowledge. Search for the name of a -module in the issue tracker, filter by label, or use the `advanced search`_ -to find these issues. - -.. _advanced search: https://github.com/search/advanced +in modules for which you have a working knowledge. See :ref:`searching-gh-issues` +for more information. From 6f10a40f7c15237738c45f4273f00ee970523823 Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Thu, 6 Aug 2026 09:09:30 +0200 Subject: [PATCH 68/85] Add new Buildbot worker: Link to instructions for BuildBot admins (GH-1848) I looked in the devguide for the "other side" of this process. In hindsight the location is obvious, but, a link would have helped me. --- testing/new-buildbot-worker.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/testing/new-buildbot-worker.rst b/testing/new-buildbot-worker.rst index aea43a782a..97127b1412 100644 --- a/testing/new-buildbot-worker.rst +++ b/testing/new-buildbot-worker.rst @@ -48,8 +48,10 @@ compiled Python. In order to set up the buildbot software, you will need to obtain an identifier and password for your worker so it can join the fleet. Open an issue in the `configuration repository `__ -to discuss adding your worker and to obtain the -needed workername and password. You can do some of the steps that follow +to discuss adding your worker and to obtain the needed workername and password. +(The steps the administrators follow are documented under `"Add a worker" +`__ in the README.) +You can do some of the steps that follow before having the credentials, but it is easiest to have them before the "buildbot worker" step below. From 4bcdd6b7cc9ddc8a9dd5f90bf811aa2bc788e93c Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Sun, 9 Aug 2026 20:52:59 +0100 Subject: [PATCH 69/85] Python Security Policy: Add note on sandboxes (#1874) --- security/policy.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/security/policy.rst b/security/policy.rst index 14e6bf0652..33228e8e80 100644 --- a/security/policy.rst +++ b/security/policy.rst @@ -33,6 +33,10 @@ and :func:`exec` are documented to execute arbitrary Python code that is supplied as data. The :mod:`ctypes` module is documented to enable modifying arbitrary locations in memory. +CPython does not support sandboxing untrusted Python code as a security +boundary, so escapes from such a sandbox are not vulnerabilities in Python +and should be reported to the sandbox's developers instead. + Vulnerabilities must not depend on malicious control of Python's launch conditions, including (but not limited to) command line arguments, environment variables, or modifications to files on the target system. We assume that, at the time Python From 54bb595e2c1b7778918970b4d8fbf2943bb50202 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Fri, 14 Aug 2026 15:33:18 +0100 Subject: [PATCH 70/85] Updates and restructuring of the 'Triaging an issue' (#1878) Co-authored-by: Ezio Melotti --- triage/labels.rst | 1 + triage/triaging.rst | 86 ++++++++++++++++++++++++++++++++++----------- 2 files changed, 66 insertions(+), 21 deletions(-) diff --git a/triage/labels.rst b/triage/labels.rst index 96e0d8f58e..3251a384cf 100644 --- a/triage/labels.rst +++ b/triage/labels.rst @@ -121,6 +121,7 @@ Other labels * :gh-label:`easy`: for issues that are considered easy. * :gh-label:`infra`: for issues related to the infrastructure of the project (for example, GitHub Actions, dependabot, the buildbots). +* :gh-label:`invalid`: for marking spam issues/PRs. * :gh-label:`pending`: for issues/PRs that will be closed unless further feedback is provided. * :gh-label:`release-blocker`/:gh-label:`deferred-blocker`: for issues/PRs diff --git a/triage/triaging.rst b/triage/triaging.rst index 1387fa5177..22c1c5b745 100644 --- a/triage/triaging.rst +++ b/triage/triaging.rst @@ -4,25 +4,48 @@ Triaging an issue ================= -This section of the devguide documents the :ref:`issue tracker ` for -users and developers. +Every issue on the :ref:`issue tracker ` needs to be triaged to make +sure everything runs smoothly. This section covers what that involves. Checklist for triaging ====================== * Read the initial message and the comments. +* :ref:`Search the tracker ` to check that the issue + isn't a duplicate. If it is, use GitHub's :guilabel:`Close as duplicate` + option and select the issue it duplicates. * Check that the title is reasonably concise, while including enough specifics so that those scanning the list of issues can quickly identify its topic. * For pull requests, ensure that the corresponding issue is added before the title (:samp:`gh-NNNNN: {Title}`). -* Set all the relevant :ref:`labels `. -* Where appropriate, set the :guilabel:`Assignees`, :guilabel:`Reviewers`, - :guilabel:`Project` fields, and possibly @mention relevant people. +* Set all the relevant :ref:`labels `. +* Where appropriate, set the :guilabel:`Assignees`, :guilabel:`Reviewers`, and + :guilabel:`Project` :ref:`fields `, and possibly @mention + relevant people. * You might also leave a brief comment about the proposed next action needed. If there is a long message list, a summary can be very helpful. -* If the issue is clearly invalid (unrelated to CPython, duplicate, spam, and - so on), you can use GitHub's "Close as not planned" option. +* If the issue is clearly invalid (unrelated to CPython, spam, and + so on), you can use GitHub's :guilabel:`Close as not planned` option + and apply the :gh-label:`invalid` label. + + +.. _triage-fields: + +Issue fields +============ + +These fields can be set in the sidebar of issues and pull requests. + + +.. _triage-labels: + +Labels +------ + +Labels are the main way of categorizing issues and automating certain actions on +pull requests. Set all that apply. See :ref:`gh-labels` for more information. + Assignees --------- @@ -35,11 +58,33 @@ forward without their help; for example, they need to make a technical decision how to proceed. Also consult the :ref:`experts` as certain stdlib modules should always be assigned to a specific person. -Note that in order to assign an issue to someone, that person **must** be +Note that in order to assign an issue to someone, that person **must** have at least triage permissions in the repository. -.. The Assignees subsection was copied from the labels.rst page in #930. - For consistency, the other fields mentioned above should be documented too. + +Reviewers +--------- + +This field is used to request a review from specific people. + +In most cases there is nothing to do, as the maintainers listed in the +:cpy-file:`.github/CODEOWNERS` file are automatically requested to review +pull requests touching the files they maintain. Otherwise, consult the +:ref:`experts` to find someone with a working knowledge of the affected area +or platform. + +If the person you have in mind doesn't show up in the :guilabel:`Reviewers` +dropdown (usually because they don't have the required permissions in the +repository), @mention them in a comment instead. + + +Project +------- + +`GitHub projects `__ are used to track +work on a specific module, platform, or interest area across issues and pull +requests. Add all the relevant ones. Note that several are added automatically +when the corresponding :ref:`label ` is added. .. _helptriage: @@ -52,9 +97,6 @@ structured and you are comfortable with the workflow, a great way to contribute is to help triage issues. Do realize, though, that experience working on Python is needed in order to effectively help triage. -Around the clock, new issues are being opened on the :ref:`issue tracker -` and existing issues are being updated. Every issue needs to be -triaged to make sure everything runs smoothly. Classifying reports ------------------- @@ -63,14 +105,14 @@ For bugs, an issue needs to: * clearly explain the bug so it can be reproduced * include all relevant platform details -* state what version(s) of Python are affected by the bug. +* state what versions of Python are affected by the bug. These are things you can help with once you have experience developing for Python: * Try reproducing the bug: if it is not explained clearly - enough for you to reproduce it, then there is a good chance a core developer - won't be able to either. + enough for you to reproduce it, then there is a good chance a core team + member won't be able to either. * See if the issue happens on a different Python version: it is always helpful to know if a bug not only affects the in-development version of Python, but whether it also affects other versions in maintenance mode. @@ -78,8 +120,9 @@ Python: Python's test suite, having that written can be very helpful. This is all helpful as it allows members of the :ref:`triage team ` -to properly classify an issue so it can be handled by the right core developers -in a timely fashion. +to properly classify an issue so it can be handled by the right core team +members in a timely fashion. + Reviewing pull requests ----------------------- @@ -88,19 +131,20 @@ If an issue has a linked pull request that has not been reviewed, you can help by making sure the pull request: * is a good solution to the problem it is trying to solve -* follows the style guides (:pep:`7`, :pep:`8`, :ref:`style-guide`, etc.) +* follows the style guides (for example, :pep:`7`, :pep:`8`, and :ref:`style-guide`) * includes proper tests * includes proper documentation changes * includes a :ref:`NEWS entry ` (if needed) * doesn't have conflicts with the ``main`` branch * :ref:`doesn't have failing CI checks ` -Doing all of this allows core developers and :ref:`triagers ` +Doing all of this allows core team members and :ref:`triagers ` to more quickly look for subtle issues that only people with extensive -experience working on Python's code base will notice. +experience working on Python's codebase will notice. See also :ref:`committing`. + Finding an issue you can help with ---------------------------------- From 6f2e4575d4f0c49c28b1a403028574447e6bf6db Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Fri, 14 Aug 2026 18:43:36 +0100 Subject: [PATCH 71/85] Add an overview of the translation process (#1876) Co-authored-by: Maciej Olko --- documentation/translations/overview-dark.svg | 4 ++ documentation/translations/overview-light.svg | 4 ++ documentation/translations/translating.rst | 38 ++++++++++++++++++- 3 files changed, 44 insertions(+), 2 deletions(-) create mode 100644 documentation/translations/overview-dark.svg create mode 100644 documentation/translations/overview-light.svg diff --git a/documentation/translations/overview-dark.svg b/documentation/translations/overview-dark.svg new file mode 100644 index 0000000000..ff8ce2ca8b --- /dev/null +++ b/documentation/translations/overview-dark.svg @@ -0,0 +1,4 @@ + + +DocumentationPublishDocsbuild-scriptsTranslationrepositoryUploadTranslationPO filesTranslateExtract stringsDocumentationsourceBuild translation diff --git a/documentation/translations/overview-light.svg b/documentation/translations/overview-light.svg new file mode 100644 index 0000000000..39b71714c4 --- /dev/null +++ b/documentation/translations/overview-light.svg @@ -0,0 +1,4 @@ + + +DocumentationPublishDocsbuild-scriptsTranslationrepositoryUploadTranslationPO filesTranslateExtract stringsDocumentationsourceBuild translation diff --git a/documentation/translations/translating.rst b/documentation/translations/translating.rst index ab5409522c..f1c3cfe714 100644 --- a/documentation/translations/translating.rst +++ b/documentation/translations/translating.rst @@ -6,8 +6,8 @@ Translating .. highlight:: rest -There are several documentation translations already -in production and can be found in the language switcher; others are works in +Several documentation translations are already in production and can be found +in the language switcher; others are works in progress. To get started read your repository's contributing guide, which is generally the ``README`` file, and this page. If your language isn’t listed below, feel free to start the translation! @@ -133,6 +133,40 @@ For more details about translations and their progress, see `Transifex `_ +Overview +======== + +.. figure:: overview-light.svg + :class: only-light + :align: center + :alt: Strings are extracted from the source documentation into PO files, + translated, uploaded to the translation repository, built by + docsbuild-scripts, and published. + +.. figure:: overview-dark.svg + :class: only-dark + :align: center + :alt: Strings are extracted from the source documentation into PO files, + translated, uploaded to the translation repository, built by + docsbuild-scripts, and published. + +.. Drawn with Excalidraw: https://excalidraw.com/#json=eh8rCFZJwziIPgj9BjK-r,VEOHnb-9FdAHZNaG4zfH6g + +Roughly, translation works as follows: + +- Translators work on gettext PO file catalogs generated from the Python docs + `by Sphinx `__, + rather than editing the documentation directly. +- Teams work in different ways. For example, some have translators work + locally, while others use tools like :ref:`Transifex `. + Messages without a translation fall back to English, so a translation can be + published before it is complete. +- Translations are committed to the :ref:`translation repository `. +- Completed translations are automatically pulled in from the repository by + :github:`docsbuild-scripts ` and published to + docs.python.org. + + How to get help =============== From d5c8ae0fa94e80d0bf897feb86c2ec14ed63cdaa Mon Sep 17 00:00:00 2001 From: Sepehr Rasouli Date: Sat, 15 Aug 2026 20:37:20 +0330 Subject: [PATCH 72/85] Update Persian translation details (#1881) Adds `@sepehr-rs` as coordinator and link to Telegram. Co-authored-by: Stan Ulbrych --- documentation/translations/translating.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/documentation/translations/translating.rst b/documentation/translations/translating.rst index f1c3cfe714..9112314334 100644 --- a/documentation/translations/translating.rst +++ b/documentation/translations/translating.rst @@ -71,8 +71,10 @@ For more details about translations and their progress, see - Albertas Gimbutas (:github-user:`albertas`, `email `__) - `original announcement `__ * - Persian (fa) - - Alireza Shabani (:github-user:`revisto`) - - :github:`GitHub ` + - | Alireza Shabani (:github-user:`revisto`), + | Sepehr Rasouli (:github-user:`sepehr-rs`) + - :github:`GitHub `, + `Telegram `__ * - `Polish (pl) `__ - | Maciej Olko (:github-user:`m-aciek`), | Stan Ulbrych (:github-user:`StanFromIreland`) From a318fba46f9776ba1f07784f37f441f2cf3f65f4 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Sat, 15 Aug 2026 22:17:34 +0100 Subject: [PATCH 73/85] Add a little section on the motivation behind translation (#1882) --- .../translations/python-logo-languages.svg | 233 ++++++++++++++++++ documentation/translations/translating.rst | 39 +++ 2 files changed, 272 insertions(+) create mode 100644 documentation/translations/python-logo-languages.svg diff --git a/documentation/translations/python-logo-languages.svg b/documentation/translations/python-logo-languages.svg new file mode 100644 index 0000000000..0286904455 --- /dev/null +++ b/documentation/translations/python-logo-languages.svg @@ -0,0 +1,233 @@ + + + + diff --git a/documentation/translations/translating.rst b/documentation/translations/translating.rst index 9112314334..f0789c71ae 100644 --- a/documentation/translations/translating.rst +++ b/documentation/translations/translating.rst @@ -169,6 +169,39 @@ Roughly, translation works as follows: docs.python.org. +Motivation +========== + +The Python documentation is written in English, but Python is taught, learned, +and used around the world, in many languages. English is the native language +of only about 5% of the world's population, and fewer than a fifth more speak +it as an additional language [#f1]_. For many people, learning Python also +means overcoming a language barrier. They must learn not only Python, but also +enough English to be able to use the language's documentation. + +The United Nations Open Source Principles call on projects both to provide +documentation and to foster inclusive participation [#f2]_. Providing +documentation only in English limits who can benefit from it and who can +participate in the wider Python community. + +.. figure:: python-logo-languages.svg + :align: center + :alt: The word "Python" written in dozens of languages. + +.. Image drawn manually in Inkscape. The text in python-logo-languages.svg was + converted to paths before exporting for consistent rendering, contact + StanFromIreland for the original. + +Translations make Python's documentation accessible to a much wider audience. +They allow people to learn and use Python in a language they are confident in, +reducing the additional burden of learning through English. + +Translation also improves the English documentation. Translators review the +source text closely and often find bugs. As a result, translation therefore +benefits not only readers of other languages, but everyone who uses and +contributes to Python's documentation. + + How to get help =============== @@ -460,6 +493,12 @@ with the commit hash from before the files were moved): After running ``pomerge``, review the changes and commit the updated files. You may also need to rewrap the lines (see :pypi:`powrap`). +.. rubric:: Footnotes + +.. [#f1] Ethnologue, `What is the most spoken language? + `__ +.. [#f2] `United Nations Open Source Principles + `__ .. _discourse: https://discuss.python.org/c/documentation/translations/ .. _tx: https://explore.transifex.com/python-doc/python-newest/ From 3f36f40508bbd335f6b5980fd6a28920aa01d061 Mon Sep 17 00:00:00 2001 From: Paul Tobias Date: Mon, 17 Aug 2026 09:26:43 +0700 Subject: [PATCH 74/85] Fix small typos and grammar in documentation/style-guide.rst (#1884) --- documentation/style-guide.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/documentation/style-guide.rst b/documentation/style-guide.rst index e504f529b5..11032a59f7 100644 --- a/documentation/style-guide.rst +++ b/documentation/style-guide.rst @@ -122,7 +122,7 @@ free-threaded open source Follow the usual English rules for compound words. When used as an adjective, hyphenate: "open-source software". When used as a noun, don't use - a hyphen: "open source is a collaboration model.." + a hyphen: "open source is a collaboration model." POSIX The name assigned to a particular group of standards. This is always @@ -168,7 +168,7 @@ as a type. Many types have descriptive names which may or may not exactly match their type name. For example, "context variables" describes ``contextvars.ContextVar``, -and both "dict" and "dictonary" are used to describe ``dict``. Once it is clear +and both "dict" and "dictionary" are used to describe ``dict``. Once it is clear that the text refers to a specific type, use the naming which suits the context: in the case of ``dict``, any of "dict", "dictionary", or "``:class:`dict```" may be best. @@ -274,7 +274,7 @@ Bad example (creating worry in the mind of a reader): Good example (establishing confident knowledge in the effective use of the language): - A best practice for using files is use a try/finally pair to explicitly + A best practice for using files is to use a try/finally pair to explicitly close a file after it is used. Alternatively, using a with-statement can achieve the same effect. This assures that files are flushed and file descriptor resources are released in a timely manner. @@ -378,7 +378,7 @@ model to alternative implementations and because the operation of the "grouper" is more easily shown in code than in English prose. An example of when not to use a code equivalent is for the :func:`oct` function. -The exact steps in converting a number to octal doesn't add value for a user +The exact steps in converting a number to octal don't add value for a user trying to learn what the function does. @@ -393,7 +393,7 @@ your best to connect-the-dots, but don't talk down to them or waste their time. The tutorial is meant for newcomers, many of whom will be using the tutorial to evaluate the language as a whole. The experience needs to be positive and not leave the reader with worries that something bad will happen if they make a -misstep. The tutorial serves as guide for intelligent and curious readers, +misstep. The tutorial serves as a guide for intelligent and curious readers, saving details for the how-to guides and other sources. Be careful accepting requests for documentation changes from the rare but vocal From 708aa7c0306c977e94f74a4da5264b02182947bd Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Wed, 19 Aug 2026 21:55:57 +0300 Subject: [PATCH 75/85] Argument Clinic: document deletion of an attribute and @deleter (GH-1886) Also update the example of the generated code. --- development-tools/clinic/howto.rst | 55 +++++++++++++++++++++++++++--- 1 file changed, 51 insertions(+), 4 deletions(-) diff --git a/development-tools/clinic/howto.rst b/development-tools/clinic/howto.rst index 359c53e903..c3d766f5dc 100644 --- a/development-tools/clinic/howto.rst +++ b/development-tools/clinic/howto.rst @@ -1419,24 +1419,32 @@ The generated glue code looks like this: .. code-block:: c static PyObject * - _io_TextIOWrapper__CHUNK_SIZE_get(textio *self, void *Py_UNUSED(context)) + _io_TextIOWrapper__CHUNK_SIZE_get(PyObject *self, void *Py_UNUSED(context)) { PyObject *return_value = NULL; Py_BEGIN_CRITICAL_SECTION(self); - return_value = _io_TextIOWrapper__CHUNK_SIZE_get_impl(self); + return_value = _io_TextIOWrapper__CHUNK_SIZE_get_impl((textio *)self); Py_END_CRITICAL_SECTION(); return return_value; } static int - _io_TextIOWrapper__CHUNK_SIZE_set(textio *self, PyObject *value, void *Py_UNUSED(context)) + _io_TextIOWrapper__CHUNK_SIZE_set(PyObject *self, PyObject *value, void *Py_UNUSED(context)) { int return_value; + + if (value == NULL) { + PyErr_Format(PyExc_AttributeError, + "attribute '_CHUNK_SIZE' of '%.100s' objects cannot be deleted", + Py_TYPE(self)->tp_name); + return -1; + } Py_BEGIN_CRITICAL_SECTION(self); - return_value = _io_TextIOWrapper__CHUNK_SIZE_set_impl(self, value); + return_value = _io_TextIOWrapper__CHUNK_SIZE_set_impl((textio *)self, value); Py_END_CRITICAL_SECTION(); + return return_value; } @@ -1446,6 +1454,45 @@ The generated glue code looks like this: The *value* parameter for a "setter" is added implicitly by Argument Clinic. It is possible to create a docstring for the property by adding it to the ``@getter``. + The accessors of the same attribute must share the C basename; + declaring the same accessor twice is an error. + +The setter slot of :c:type:`PyGetSetDef` is used both for setting and for +deleting the attribute: the setter is called with ``NULL`` as the value to +delete it. +As shown above, the generated setter rejects the deletion with an +:exc:`AttributeError` before calling the "impl" function. + +If the attribute can be deleted, add the ``@deleter`` directive after +``@setter``. +The "impl" function is then called with ``NULL`` and is responsible for +handling this case, as in this example taken from +:cpy-file:`Objects/funcobject.c`:: + + /*[clinic input] + @critical_section + @setter + @deleter + function.__annotations__ + [clinic start generated code]*/ + +.. code-block:: c + + static int + function___annotations___set_impl(PyFunctionObject *self, PyObject *value) + { + if (value == Py_None) + value = NULL; + /* Legal to del f.func_annotations. + * Can only set func_annotations to NULL (through C api) + * or a dict. */ + if (value != NULL && !PyDict_Check(value)) { + PyErr_SetString(PyExc_TypeError, + "__annotations__ must be set to a dict object"); + return -1; + } + ... + } And then the implementation will work the same as a Python method which is decorated by :py:class:`property`: From 9d5e496abbe69ad47f001034998b5d3b880be668 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E0=A4=B8=E0=A4=82=E0=A4=95=E0=A5=87=E0=A4=A4=20Sanket?= Date: Fri, 21 Aug 2026 18:30:09 +0900 Subject: [PATCH 76/85] Update coordinator of the Marathi translation (#1889) --- documentation/translations/translating.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/documentation/translations/translating.rst b/documentation/translations/translating.rst index f0789c71ae..8026c9c3a6 100644 --- a/documentation/translations/translating.rst +++ b/documentation/translations/translating.rst @@ -65,8 +65,9 @@ For more details about translations and their progress, see - 오동권 (:github-user:`flowdas`) - :github:`GitHub ` * - Marathi (mr) - - Sanket Garade (:github-user:`sanketgarade`, `email `__) - - :github:`GitHub ` + - Satvik Mudgal (:github-user:`satvikmudgal`, `email `__) + - :github:`GitHub `, + `Ownership transfer `__ * - Lithuanian (lt) - Albertas Gimbutas (:github-user:`albertas`, `email `__) - `original announcement `__ From 0d5fbc08982dcc4ef2057ea7919e986465b44182 Mon Sep 17 00:00:00 2001 From: Willy Bruns Date: Sat, 22 Aug 2026 18:43:55 +0000 Subject: [PATCH 77/85] Fix a typo in the 'Comparing changes' section (#1891) --- getting-started/git-boot-camp.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/getting-started/git-boot-camp.rst b/getting-started/git-boot-camp.rst index 4d01a851e8..33717b14d9 100644 --- a/getting-started/git-boot-camp.rst +++ b/getting-started/git-boot-camp.rst @@ -265,7 +265,7 @@ To re-apply the last stashed change:: Comparing changes ----------------- -View all non-commited changes:: +View all non-committed changes:: $ git diff From b5ae109e22bbbd29b1e75b9617baba4713f91291 Mon Sep 17 00:00:00 2001 From: Joe Castle Date: Mon, 24 Aug 2026 06:37:41 -0500 Subject: [PATCH 78/85] Document deb822 sources for Ubuntu 24.04 and later (GH-1885) --- getting-started/setup-building.rst | 26 ++++++++++++++++++++++---- 1 file changed, 22 insertions(+), 4 deletions(-) diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index 8e35f8a646..c29f86c87b 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -790,13 +790,31 @@ some of CPython's modules (for example, ``zlib``). dependencies for the Python you're working on by using the ``apt`` command. First, make sure you have enabled the source packages in the sources list. - You can do this by adding the location of the source packages, including - URL, distribution name and component name, to ``/etc/apt/sources.list``. - Take Ubuntu 22.04 LTS (Jammy Jellyfish) for example:: + Where those live depends on your release. + + On **Ubuntu 24.04 and later**, and on other releases using the deb822 + format, the sources are in ``/etc/apt/sources.list.d/ubuntu.sources``. + Add ``deb-src`` to the ``Types`` field of the entries you want sources + for:: + + $ sudo nano /etc/apt/sources.list.d/ubuntu.sources + + changing:: + + Types: deb + + to:: + + Types: deb deb-src + + On **Ubuntu 22.04 and other releases using the one-line format**, add the + location of the source packages, including URL, distribution name and + component name, to ``/etc/apt/sources.list``. Taking Ubuntu 22.04 LTS + (Jammy Jellyfish) as the example:: $ deb-src http://archive.ubuntu.com/ubuntu/ jammy main - Alternatively, uncomment lines with ``deb-src`` using an editor, for + Alternatively, uncomment the lines with ``deb-src`` using an editor, for example:: $ sudo nano /etc/apt/sources.list From a585e4e7e763b0defd682d80975bbec83e687789 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Tue, 25 Aug 2026 20:36:30 +0100 Subject: [PATCH 79/85] Tidy up translation table (#1890) Co-authored-by: Daniil Kolesnikov --- documentation/translations/translating.rst | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/documentation/translations/translating.rst b/documentation/translations/translating.rst index 8026c9c3a6..8f7ebe92d2 100644 --- a/documentation/translations/translating.rst +++ b/documentation/translations/translating.rst @@ -64,17 +64,17 @@ For more details about translations and their progress, see * - `Korean (ko) `__ - 오동권 (:github-user:`flowdas`) - :github:`GitHub ` - * - Marathi (mr) - - Satvik Mudgal (:github-user:`satvikmudgal`, `email `__) - - :github:`GitHub `, - `Ownership transfer `__ * - Lithuanian (lt) - Albertas Gimbutas (:github-user:`albertas`, `email `__) - `original announcement `__ + * - Marathi (mr) + - Satvik Mudgal (:github-user:`satvikmudgal`, `email `__) + - :github:`GitHub `, + `coordinator transfer `__ * - Persian (fa) - | Alireza Shabani (:github-user:`revisto`), | Sepehr Rasouli (:github-user:`sepehr-rs`) - - :github:`GitHub `, + - :github:`GitHub `, `Telegram `__ * - `Polish (pl) `__ - | Maciej Olko (:github-user:`m-aciek`), @@ -95,12 +95,13 @@ For more details about translations and their progress, see | Yashraj Jangra (:github-user:`Yashraj-Jangra`) - :github:`GitHub `, `Transifex `_ - * - `Romanian (ro) `__ + * - `Romanian (ro) `__ - Octavian Mustafa (:github-user:`octaG-M`, `email `__) - :github:`GitHub ` - * - Russian (ru) - - Daniil Kolesnikov (:github-user:`MLGRussianXP`, `email `__) - - :github:`GitHub `, + * - `Russian (ru) `__ + - Daniil Kolesnikov (:github-user:`dkqzz`, `email `__) + - :github:`GitHub `, + `Telegram `__, `original announcement `__ * - `Simplified Chinese (zh-cn) `__ - | Shengjing Zhu (:github-user:`zhsj`), @@ -110,7 +111,7 @@ For more details about translations and their progress, see * - `Spanish (es) `__ - Raúl Cumplido (:github-user:`raulcd`) - :github:`GitHub ` - * - Swedish (sv) + * - `Swedish (sv) `__ - Daniel Nylander (:github-user:`yeager`) - :github:`GitHub ` * - Tamil (ta) From 261dc2116ca81985c5c0cfc59db5a251d2c8db96 Mon Sep 17 00:00:00 2001 From: Ned Batchelder Date: Wed, 26 Aug 2026 18:19:41 -0400 Subject: [PATCH 80/85] linklint is now sphinx_linklint (#1893) * linklint is now sphinx_linklint * use the canonical package name --- conf.py | 2 +- documentation/style-guide.rst | 2 +- requirements.txt | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/conf.py b/conf.py index 27795dd484..7e0ea0810a 100644 --- a/conf.py +++ b/conf.py @@ -3,7 +3,6 @@ from urllib.request import urlopen extensions = [ - 'linklint.ext', 'notfound.extension', 'sphinx.ext.extlinks', 'sphinx.ext.intersphinx', @@ -11,6 +10,7 @@ 'sphinx_copybutton', 'sphinx_inline_tabs', 'sphinx_last_updated_by_git', + 'sphinx_linklint.ext', 'sphinxcontrib.youtube', 'sphinxext.opengraph', 'sphinxext.rediraffe', diff --git a/documentation/style-guide.rst b/documentation/style-guide.rst index 11032a59f7..9747651b60 100644 --- a/documentation/style-guide.rst +++ b/documentation/style-guide.rst @@ -237,7 +237,7 @@ the second mention is more appropriate for a link. Some units are long enough to have a few repeated links. Use judgement to decide when a link will help the reader. -We use the :pypi:`linklint Sphinx extension ` to suppress two kinds +We use the :pypi:`linklint Sphinx extension ` to suppress two kinds of excessive links: references in a section to itself and duplicate references in a paragraph. Previously, editors had to carefully use an exclamation mark in a Sphinx reference (``:func:`!map```) to prevent such links. diff --git a/requirements.txt b/requirements.txt index 789f9597a3..a63e5aa8ae 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,12 +1,12 @@ furo>=2025.12.19 jinja2 -linklint sphinx-autobuild>=2025.8.25 sphinx-inline-tabs>=2025.12.21.14 sphinx-last-updated-by-git>=0.3.8 sphinx-lint==1.0.2 sphinx-notfound-page>=1.1.0 sphinx_copybutton>=0.5.2 +sphinx_linklint sphinxcontrib-youtube>=1.5.0 sphinxext-opengraph>=0.13.0 sphinxext-rediraffe From 8d02443fd03d9aa4140997ae645628fdfe6fa0d0 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Tue, 1 Sep 2026 03:43:24 +0200 Subject: [PATCH 81/85] Bump the actions group with 3 updates (#1897) Bumps the actions group with 3 updates: [actions/setup-python](https://github.com/actions/setup-python), [hynek/setup-cached-uv](https://github.com/hynek/setup-cached-uv) and [j178/prek-action](https://github.com/j178/prek-action). Updates `actions/setup-python` from 6.3.0 to 7.0.0 - [Release notes](https://github.com/actions/setup-python/releases) - [Commits](https://github.com/actions/setup-python/compare/ece7cb06caefa5fff74198d8649806c4678c61a1...5fda3b95a4ea91299a34e894583c3862153e4b97) Updates `hynek/setup-cached-uv` from 2.5.0 to 2.6.0 - [Release notes](https://github.com/hynek/setup-cached-uv/releases) - [Changelog](https://github.com/hynek/setup-cached-uv/blob/main/CHANGELOG.md) - [Commits](https://github.com/hynek/setup-cached-uv/compare/4300ec2180bc77d705e626a34e381b81a4772c51...34e35d30f1ebc7421a5cc733bca38dcc62603960) Updates `j178/prek-action` from 2.0.5 to 3.0.0 - [Release notes](https://github.com/j178/prek-action/releases) - [Commits](https://github.com/j178/prek-action/compare/e98a699c41eb69ab013a45817a0406469a748f8d...4e14d07f9231acabce116ccfca13b13dd9755ece) --- updated-dependencies: - dependency-name: actions/setup-python dependency-version: 7.0.0 dependency-type: direct:production update-type: version-update:semver-major dependency-group: actions - dependency-name: hynek/setup-cached-uv dependency-version: 2.6.0 dependency-type: direct:production update-type: version-update:semver-minor dependency-group: actions - dependency-name: j178/prek-action dependency-version: 3.0.0 dependency-type: direct:production update-type: version-update:semver-major dependency-group: actions ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- .github/workflows/ci.yml | 4 ++-- .github/workflows/lint.yml | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 906579081b..302992d47a 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -17,11 +17,11 @@ jobs: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false - - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0 + - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0 with: python-version: "3" - name: Install uv - uses: hynek/setup-cached-uv@4300ec2180bc77d705e626a34e381b81a4772c51 # v2.5.0 + uses: hynek/setup-cached-uv@34e35d30f1ebc7421a5cc733bca38dcc62603960 # v2.6.0 - uses: sphinx-doc/github-problem-matcher@1f74d6599f4a5e89a20d3c99aab4e6a70f7bda0f # v1.1 - name: Build docs run: make html diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index a727a77f3c..264a11f5a0 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/lint.yml @@ -17,7 +17,7 @@ jobs: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false - - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0 + - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0 with: python-version: "3.x" - - uses: j178/prek-action@e98a699c41eb69ab013a45817a0406469a748f8d # v2.0.5 + - uses: j178/prek-action@4e14d07f9231acabce116ccfca13b13dd9755ece # v3.0.0 From 3d6c5395324b0f7a8254bf8419921199c3e6d94e Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Tue, 1 Sep 2026 20:15:29 +0200 Subject: [PATCH 82/85] Add Nathan Goldbaum (#1898) --- core-team/core-team.csv | 1 + 1 file changed, 1 insertion(+) diff --git a/core-team/core-team.csv b/core-team/core-team.csv index 133a4e6273..67a28fc338 100644 --- a/core-team/core-team.csv +++ b/core-team/core-team.csv @@ -1,3 +1,4 @@ +Nathan Goldbaum,ngoldbaum,2026-09-01,, Pieter Eendebak,eendebakpt,2026-07-08,, Seth Larson,sethmlarson,2026-06-12,, Chris Eibl,chris-eibl,2026-05-10,, From 9d481ef402e0d112ae6e1c11a87c5df038e0e5f0 Mon Sep 17 00:00:00 2001 From: Arpan Chatterjee <166946969+Arpan2411@users.noreply.github.com> Date: Wed, 2 Sep 2026 15:21:45 +0530 Subject: [PATCH 83/85] correct a/an usage (#1899) --- _static/psrt-coordinator-triage.html | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/_static/psrt-coordinator-triage.html b/_static/psrt-coordinator-triage.html index af5936a6cb..1190c95d78 100644 --- a/_static/psrt-coordinator-triage.html +++ b/_static/psrt-coordinator-triage.html @@ -17,15 +17,15 @@ │ field to Coordinator │ └────────────┬───────────┘ │ - ┌────────────▼───────────┐ - │ Coordinator determines │ - ┌───┤ whether report... ┼───┐ - │ └────────────┬───────────┘ │ + ┌────────────▼────────────┐ + │ Coordinator determines │ + ┌───┤ whether report... ┼──┐ + │ └────────────┬────────────┘ │ │ │ │ -┌────────────▼─┐ ┌────────────▼───────────┐ ┌─▼─────────────┐ -│..is a invalid│ │ ..is a bug, but not │ │..is a security│ -│ or non-issue│ │ security relevant │ │ issue │ -└────────────┬─┘ └────────────┬───────────┘ └─┬─────────────┘ +┌────────────▼──┐ ┌───────────▼───────────┐ ┌─▼─────────────┐ +│..is an invalid│ │ ..is a bug, but not │ │..is a security│ +│ or non-issue │ │ security relevant │ │ issue │ +└────────────┬──┘ └───────────┬───────────┘ └─┬─────────────┘ │ │ │ │ ┌────────────▼───────────┐ │ │ │ Coordinator opens a │ │ From d253c4727876bb7c5663a3dcf9020ae7385c60c0 Mon Sep 17 00:00:00 2001 From: Jacob Coffee Date: Thu, 10 Sep 2026 18:49:33 -0500 Subject: [PATCH 84/85] Update admins (#1903) --- .github/CODEOWNERS | 2 +- security/psrt.csv | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index f04c167334..305a38980a 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -5,4 +5,4 @@ # https://git-scm.com/docs/gitignore#_pattern_format # PSRT member list owned by PSRT admins. -security/psrt*.csv @warsaw @ewdurbin @ned-deily @sethmlarson @stanfromireland +security/psrt*.csv @warsaw @JacobCoffee @ned-deily @sethmlarson @stanfromireland diff --git a/security/psrt.csv b/security/psrt.csv index 169b1a7eac..f6dff2073b 100644 --- a/security/psrt.csv +++ b/security/psrt.csv @@ -5,12 +5,12 @@ Benjamin Peterson,benjaminp, Damian Shaw,notatallshaw, Donald Stufft,dstufft, Dustin Ingram,di, -Ee Durbin,ewdurbin,Admin +Ee Durbin,ewdurbin, Emma Smith,emmatyping, Glyph Lefkowitz,glyph, Gregory P. Smith,gpshead, Hugo van Kemenade,hugovk,Release Manager -Jacob Coffee,JacobCoffee, +Jacob Coffee,JacobCoffee,Admin Jelle Zijlstra,JelleZijlstra, Kushal Das,kushaldas, Kirill Podoprigora,eclips4, From 8b8b1f2db753d80d0aa295abd6c2f5f64897f7a9 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Sun, 13 Sep 2026 20:24:51 +0300 Subject: [PATCH 85/85] Argument Clinic: document how to remove and rename a parameter (GH-1888) --- development-tools/clinic/howto.rst | 91 ++++++++++++++++++++++++++++++ 1 file changed, 91 insertions(+) diff --git a/development-tools/clinic/howto.rst b/development-tools/clinic/howto.rst index c3d766f5dc..8c713a33eb 100644 --- a/development-tools/clinic/howto.rst +++ b/development-tools/clinic/howto.rst @@ -1617,3 +1617,94 @@ and update your unit tests to reflect the new behaviour. If you forget to update your input block during the alpha and beta phases, the compiler warning will turn into a compiler error when the release candidate phase begins. + + +.. _clinic-howto-remove-parameter: + +How to remove a parameter +------------------------- + +A parameter cannot be removed right away: +as mandated by Python's backwards-compatibility policy (see :pep:`387`), +passing it must first emit a :exc:`DeprecationWarning` for two releases. +The ``[until ...]`` prefix marks a parameter which is going away and names +the release in which it will be removed:: + + /*[clinic input] + module foo + myfunc + a: object + [until 3.18] b: object = None + * [from 3.18] + c: object = None + [clinic start generated code]*/ + +Passing an argument for *b* now emits: + +.. code-block:: none + + DeprecationWarning: Passing the argument 'b' to myfunc() is deprecated. It will be removed in Python 3.18. + +A deprecated parameter must have a default value, because calls which do not +pass it must already be valid. + +Removing a parameter shifts the position of every parameter which follows it, +so they should become keyword-only in the same release, +using the ``* [from ...]`` syntax described above. +This is why *c* is deprecated as a positional parameter in the example above. +Argument Clinic enforces this for positional-only parameters: +only the last of them can be deprecated, because there is no way to pass +a positional-only parameter which follows a removed one. + +As with the ``[from ...]`` syntax described above, C preprocessor directives +are generated for emitting compiler warnings if the ``[until ...]`` prefix has +not been removed from the Argument Clinic input when the deprecation period is +over. +Then remove the parameter and the corresponding argument of the "impl" +function. + +.. versionadded:: 3.16 + + +.. _clinic-howto-rename-parameter: + +How to rename a parameter +------------------------- + +Renaming a positional-only parameter is backward compatible: +its name cannot be used in a call, so it is enough to change it. + +For a positional-or-keyword or a keyword-only parameter the name is a part of +the API, so the old name can only be removed after a deprecation period. +Change the name of the parameter, and add an optional keyword-only parameter +with the old name, the C name of the renamed parameter and the ``[until ...]`` +prefix:: + + /*[clinic input] + module foo + myfunc + source: object = None + flag: bool = False + * + [until 3.18] input as source: object = None + [clinic start generated code]*/ + +A parameter which shares the C variable of a preceding parameter is an +alternative name (an *alias*) of it: +both names fill the same argument of the "impl" function, and only one of them +can be used in a call, so ``myfunc(1, input=2)`` and +``myfunc(source=1, input=2)`` raise :exc:`TypeError`. +An alias is declared after all other parameters, but it fills the slot of +the parameter which it renames, so ``myfunc(input=1, flag=True)`` works. +It is not shown in the signature, which for the function above is +``($module, /, source=None, flag=False)``. + +Passing an argument for the old name now emits: + +.. code-block:: none + + DeprecationWarning: Passing the argument 'input' to myfunc() is deprecated. Use 'source' instead. It will be removed in Python 3.18. + +When the deprecation period is over, remove the alias. + +.. versionadded:: 3.16