From 098351234d6beba22faf43612512d5476fea9981 Mon Sep 17 00:00:00 2001 From: David Hills <20931105+DJHills@users.noreply.github.com> Date: Fri, 28 Nov 2025 13:32:24 +0000 Subject: [PATCH 01/48] Fix typo in "Getting Started" guide (#1707) --- 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 c6cf6c9fa..a6ba77959 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -823,7 +823,7 @@ some of CPython's modules (for example, ``zlib``). 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 built it from sources or install this package from + Either build it from sources or install this package from https://deb.sury.org. .. tab:: macOS From 7a8438290bf69c6f6ed20a74fb8a5c8d24028844 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Sat, 29 Nov 2025 18:30:39 +0200 Subject: [PATCH 02/48] RST markup: recommend anonymous hyperlinks (#1709) --- contrib/intro/index.rst | 6 +- core-team/committing.rst | 6 +- core-team/experts.rst | 2 +- core-team/join-team.rst | 10 ++-- core-team/memorialization.rst | 24 ++++---- core-team/motivations.rst | 58 +++++++++---------- core-team/responsibilities.rst | 4 +- developer-workflow/c-api.rst | 4 +- developer-workflow/communication-channels.rst | 22 +++---- developer-workflow/development-cycle.rst | 44 +++++++------- developer-workflow/extension-modules.rst | 6 +- developer-workflow/grammar.rst | 2 +- developer-workflow/sbom.rst | 12 ++-- development-tools/clang.rst | 8 +-- development-tools/gdb.rst | 2 +- documentation/devguide.rst | 2 +- documentation/help-documenting.rst | 4 +- documentation/markup.rst | 13 +++-- documentation/style-guide.rst | 8 +-- documentation/translations/coordinating.rst | 18 +++--- documentation/translations/translating.rst | 16 ++--- getting-started/git-boot-camp.rst | 26 ++++----- getting-started/pull-request-lifecycle.rst | 10 ++-- getting-started/setup-building.rst | 36 ++++++------ index.rst | 20 +++---- internals/compiler.rst | 2 +- internals/garbage-collector.rst | 2 +- internals/interpreter.rst | 2 +- internals/parser.rst | 2 +- testing/buildbots.rst | 2 +- testing/coverage.rst | 2 +- testing/new-buildbot-worker.rst | 26 ++++----- testing/run-write-tests.rst | 4 +- triage/github-bpo-faq.rst | 8 +-- triage/labels.rst | 6 +- triage/triage-team.rst | 6 +- versions.rst | 4 +- 37 files changed, 216 insertions(+), 213 deletions(-) diff --git a/contrib/intro/index.rst b/contrib/intro/index.rst index c5ba303df..98fa30fc3 100644 --- a/contrib/intro/index.rst +++ b/contrib/intro/index.rst @@ -24,12 +24,12 @@ Python is an open source project, with culture and techniques from the broader open source world. You might find it helpful to read about open source in general. A number of individuals from the Python community have contributed to a series of excellent guides at `Open Source Guides -`_. +`__. Anyone will find the following guides useful: -* `How to Contribute to Open Source `_ -* `Building Welcoming Communities `_ +* `How to Contribute to Open Source `__ +* `Building Welcoming Communities `__ Healthy collaboration diff --git a/core-team/committing.rst b/core-team/committing.rst index 41cf67254..a88ff1205 100644 --- a/core-team/committing.rst +++ b/core-team/committing.rst @@ -59,11 +59,11 @@ to enter the public source tree. Ask yourself the following questions: * **Does the pull request pass a check indicating that the submitter has signed the CLA?** Make sure that the contributor has signed a `Contributor - Licensing Agreement `_ + Licensing Agreement `__ (CLA), unless their change has no possible intellectual property associated with it (for example, fixing a spelling mistake in documentation). The `Python Software Foundation Contributor License Agreement Management Bot - `_ + `__ checks whether the author has signed the CLA, and replies in the PR if they haven't. For further questions about the CLA process, write to contributors@python.org. @@ -125,7 +125,7 @@ How to add a NEWS entry ^^^^^^^^^^^^^^^^^^^^^^^ ``NEWS`` entries go into the ``Misc/NEWS.d`` directory as individual files. The -``NEWS`` entry can be created by using `blurb-it `_, +``NEWS`` entry can be created by using `blurb-it `__, or the :pypi:`blurb` tool and its ``blurb add`` command. If you are unable to use the tool, then you can create the ``NEWS`` entry file diff --git a/core-team/experts.rst b/core-team/experts.rst index 2fb37cb3f..01935106b 100644 --- a/core-team/experts.rst +++ b/core-team/experts.rst @@ -365,6 +365,6 @@ Documentation translations ========================== Translations are within the charter of -`Editorial Board `_. +`Editorial Board `__. For a list of translations and their coordinators, see :ref:`this table of translations `. diff --git a/core-team/join-team.rst b/core-team/join-team.rst index d7996cd42..20ce9e4c9 100644 --- a/core-team/join-team.rst +++ b/core-team/join-team.rst @@ -40,14 +40,14 @@ are granted through these steps: (as per :pep:`13`), the submitter `emails the steering council `_ with the candidate's email address requesting that the council either accept or reject the proposed membership. Technically, the - council may only `veto a positive vote `_. + council may only `veto a positive vote `__. #. Assuming the steering council does not veto the positive vote, a member of the council or its delegate (approver, usually in practice a :ref:`Developer-in-Residence `) will email the candidate: - A request for account details as required by - `🔒 python/voters `_. + `🔒 python/voters `__. - A reminder about the `Code of Conduct`_ and guidance on reporting issues to the PSF Conduct WG. @@ -55,12 +55,12 @@ are granted through these steps: - Enable the various new privileges. - Remove the new committer from the triage team, if applicable. - - Add their details to `🔒 python/voters `_. + - 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 + `__. The past few announcements were in the form of a separate post on the already open topic with the poll. @@ -69,7 +69,7 @@ Getting a python.org email address Members of the core team can get an email address on the python.org domain. For more details refer to the `python.org email policy -`_. +`__. Poll template diff --git a/core-team/memorialization.rst b/core-team/memorialization.rst index 7ab0fab02..3d893a302 100644 --- a/core-team/memorialization.rst +++ b/core-team/memorialization.rst @@ -31,11 +31,11 @@ certain content when the legacy contact or family members request it. GitHub ------ -* The user is removed from the `python/ `_ +* The user is removed from the `python/ `__ organization on GitHub; -* The user is removed from the `psf/ `_ +* The user is removed from the `psf/ `__ organization on GitHub; -* The user is removed from the `pypa/ `_ +* The user is removed from the `pypa/ `__ organization on GitHub. The PSF staff does not follow up with GitHub with regards to GitHub account @@ -43,7 +43,7 @@ cancellation as this action is reserved for next-of-kin or designated by the deceased GitHub user to act as an account successor. The general policy regarding deceased users on GitHub is described on their -`Deceased User Policy `_ +`Deceased User Policy `__ page. Repositories in the organization @@ -51,9 +51,9 @@ Repositories in the organization * The user's GitHub handle is removed from ``/.github/CODEOWNERS``. To see all that need action, perform - `this query `_. + `this query `__. * The user is marked as deceased in the private - `voters/python-core.toml `_ + `voters/python-core.toml `__ file with the ``left=`` field set to the day of passing, if known. discuss.python.org @@ -80,7 +80,7 @@ a community member close to the deceased. The general best practice for deceased community members on Discourse-powered forums is described on their -`Best practices for deceased community members `_ +`Best practices for deceased community members `__ page. python.org email account @@ -116,8 +116,8 @@ python.org admin devguide.python.org ------------------- -* The user is marked as deceased in `core-team.csv `_; -* The user is removed from the `experts index `_. +* The user is marked as deceased in `core-team.csv `__; +* The user is removed from the `experts index `__. bugs.python.org --------------- @@ -139,16 +139,16 @@ Other PSF-related infrastructure Discord server to remove the user from the server. The PSF staff does not follow up with Discord with regards to Discord account cancellation. The general policy regarding deceased users on Discord - is available on their `Deceased or Incapacitated Users `_ + is available on their `Deceased or Incapacitated Users `__ page. * The user is removed from Salt configuration for the PSF infrastructure - in `/pillar/base/users `_ + in `/pillar/base/users `__ that allows SSH access to PSF-controlled servers. * The user might have ran a buildbot worker. The PSF staff member will look for that in the - `buildmaster-config `_ + `buildmaster-config `__ repository. PyPI diff --git a/core-team/motivations.rst b/core-team/motivations.rst index 6d539b7c3..d0e5a0cc1 100644 --- a/core-team/motivations.rst +++ b/core-team/motivations.rst @@ -97,13 +97,13 @@ participating in the CPython core development process: .. topic:: Brett Cannon (Canada) - * Personal site: `snarky.ca `_ + * Personal site: `snarky.ca `__ * Microsoft (Software Developer) * Python Software Foundation (Fellow) .. topic:: Alyssa Coghlan (Australia) - * Personal site: `Curious Efficiency `_ + * Personal site: `Curious Efficiency `__ * `Extended bio `__ * Python Software Foundation (Fellow, Packaging Working Group) * Westpac (Principal Python Engineer) @@ -123,9 +123,9 @@ participating in the CPython core development process: .. topic:: Steve Dower (United States/Australia) * Microsoft (Software Developer) - * Personal site: `stevedower.id.au `_ - * Speaking: `stevedower.id.au/speaking `_ - * Work blog: `devblogs.microsoft.com/python/ `_ + * Personal site: `stevedower.id.au `__ + * Speaking: `stevedower.id.au/speaking `__ + * Work blog: `devblogs.microsoft.com/python/ `__ * Email address: steve.dower@python.org Steve started with Python while automating a test harness for medical @@ -143,25 +143,25 @@ participating in the CPython core development process: .. topic:: Mariatta (Canada) - * Personal site: `mariatta.ca `_ - * Works as a `Software Engineer `_ + * Personal site: `mariatta.ca `__ + * Works as a `Software Engineer `__ in Vancouver, helps organize `Vancouver PyLadies - `_ meetup on the side, and - sometimes `speaks `_ + `__ meetup on the side, and + sometimes `speaks `__ at conferences. * Email address: mariatta@python.org - * `Sponsor Mariatta on GitHub `_ - * `Patreon `_ + * `Sponsor Mariatta on GitHub `__ + * `Patreon `__ - Support Mariatta by `becoming a sponsor `_, - sending her a `happiness packet `_, - or `paypal `_. + Support Mariatta by `becoming a sponsor `__, + sending her a `happiness packet `__, + or `paypal `__. .. topic:: R. David Murray (United States) - * Personal site: `bitdance.com `_ + * Personal site: `bitdance.com `__ * Available for `Python and Internet Services Consulting - and Python contract programming `_ + and Python contract programming `__ David has been involved in the Internet since the days when the old IBM BITNET and the ARPANet got cross connected, and in Python programming since @@ -177,7 +177,7 @@ participating in the CPython core development process: 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 + 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 @@ -187,7 +187,7 @@ participating in the CPython core development process: .. topic:: Antoine Pitrou (France) - * LinkedIn: ``_ (Senior Software Engineer) + * LinkedIn: ``__ (Senior Software Engineer) * QuantStack * Python Software Foundation (Fellow) * Email address: antoine@python.org @@ -213,7 +213,7 @@ participating in the CPython core development process: Victor is paid by Red Hat to maintain Python upstream and downstream (RHEL, CentOS, Fedora & Software collections). See `Victor's contributions to - Python `_. + Python `__. .. topic:: Kushal Das (India) @@ -224,21 +224,21 @@ participating in the CPython core development process: .. topic:: Barry Warsaw (United States) * NVIDIA, Principal System Software Engineer, Open Source Python Ecosystem - * Personal site: `barry.warsaw.us `_ - * Blog: `We Fear Change `_ - * `LinkedIn `_ - * `Bluesky `_ + * Personal site: `barry.warsaw.us `__ + * Blog: `We Fear Change `__ + * `LinkedIn `__ + * `Bluesky `__ * Email address: barry@python.org * Python Software Foundation (Fellow) Barry has been working in, with, and on Python since 1994. He attended the - first Python workshop at `NIST `_ in Gaithersburg, + first Python workshop at `NIST `__ in Gaithersburg, MD in 1994, where he met Guido and several other early Python adopters. Barry subsequently worked with Guido for 8 years while at `CNRI - `_. Barry has served as Python's postmaster, + `__. Barry has served as Python's postmaster, webmaster, release manager, Language Summit co-chair, `Jython - `_ project leader, `GNU Mailman - `_ project leader, and Python Steering Council + `__ project leader, `GNU Mailman + `__ project leader, and Python Steering Council member in 2019, 2020, 2021, 2024, and 2025. .. topic:: Eric Snow (United States) @@ -256,13 +256,13 @@ participating in the CPython core development process: developers on the project for 6 years. After that he started the Python Tools for Visual Studio project focusing on providing advanced code completion and debugging features for Python. Today he works on - `Cinder `_ improving Python + `Cinder `__ improving Python performance for Instagram. .. topic:: Carol Willing (United States) * Noteable (VP Engineering) - * Personal site: `Willing Consulting `_ + * Personal site: `Willing Consulting `__ * `Extended bio `__ * Project Jupyter (Software Council, Core Team for JupyterHub/Binder) * Python Software Foundation (Fellow) diff --git a/core-team/responsibilities.rst b/core-team/responsibilities.rst index 3b2137d6b..9f5c62b72 100644 --- a/core-team/responsibilities.rst +++ b/core-team/responsibilities.rst @@ -48,12 +48,12 @@ Communication channels and bug notifications ============================================ Mailing lists have generally been replaced by the -`Discourse forum `_ (``discuss.python.org``). +`Discourse forum `__ (``discuss.python.org``). Refer to the :ref:`mailinglists` and :ref:`communication-discourse` sections for more information. If you want notification of new issues, you can use the appropriate GitHub notification -settings for the `python/cpython `_ repository — +settings for the `python/cpython `__ repository — follow the link and click on the :guilabel:`Watch` button to set your notification options. diff --git a/developer-workflow/c-api.rst b/developer-workflow/c-api.rst index 90c1d12e4..c65e88ce1 100644 --- a/developer-workflow/c-api.rst +++ b/developer-workflow/c-api.rst @@ -38,7 +38,7 @@ While internal API can be changed at any time, it's still good to keep it stable: other API or other CPython developers may depend on it. For users, internal API is sometimes the best workaround for a thorny problem --- though those use cases should be discussed on the -`C API Discourse category `_ +`C API Discourse category `__ or an issue so we can try to find a supported way to serve them. @@ -218,7 +218,7 @@ use this API reliably: (:samp:`3.{x}.0`, including Alphas and Betas for :samp:`3.{x}.0`). * Adding a new unstable API *for an existing feature* is allowed even after Beta feature freeze, up until the first Release Candidate. - Consensus on the `Core Development Discourse `_ + Consensus on the `Core Development Discourse `__ is needed in the Beta period. * Backwards-incompatible changes should make existing C callers fail to compile. For example, arguments should be added/removed, or a function should be diff --git a/developer-workflow/communication-channels.rst b/developer-workflow/communication-channels.rst index 9b088b350..43c00b9e1 100644 --- a/developer-workflow/communication-channels.rst +++ b/developer-workflow/communication-channels.rst @@ -64,7 +64,7 @@ core development workflow. A complete list of Python mailing lists can be found at https://mail.python.org/mailman/listinfo (older lists, using Mailman2) or https://mail.python.org/mailman3/ (newer lists, using Mailman3). Some lists may also -be mirrored at `GMANE `_ and can be read and posted to in various +be mirrored at `GMANE `__ and can be read and posted to in various ways, including via web browsers, NNTP newsreaders, and RSS feed readers. .. _python-list: https://mail.python.org/mailman/listinfo/python-list @@ -84,7 +84,7 @@ take place in the open forum categories for `PEPs`_ and `Core Development`_ (these are the Discourse equivalents to the python-dev mailing list). All categories are open for users to read and post with the exception of the `Committers`_ category, where posting is restricted to the `CPython -`_ core team. +`__ core team. The Committers category is often used for announcements and notifications. It is also the designated venue for the core team promotion votes. @@ -97,8 +97,8 @@ create an account using an email address or GitHub account. You can do so by clicking the :guilabel:`Sign Up` button on the top right hand corner of the `Discourse`_ main page. -The Python Discourse `Quick Start `_ -compiled by `Carol Willing `_ gives you +The Python Discourse `Quick Start `__ +compiled by `Carol Willing `__ gives you a quick overview on how to kick off Python Discourse. We recommend new users getting familiarised with the forum by going through Discobot tutorials. @@ -114,13 +114,13 @@ Greetings!" received under Notifications and Messages in your user account. * Select either Notifications or Messages. * Open the "Greetings!" message sent by Discobot to start the tutorial. -Ensure that you read through the `Python Code of Conduct `_. +Ensure that you read through the `Python Code of Conduct `__. We are to be open, considerate and respectful to all users in the community. You can report messages that don't respect the CoC by clicking on the three dots under the message and then on the :guilabel:`⚐` icon. You can also mention the -`@staff `_, -`@moderators `_, or -`@admins `_ groups in a message. +`@staff `__, +`@moderators `__, or +`@admins `__ groups in a message. @@ -164,7 +164,7 @@ Customising notifications on user preference ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ To get a bird's eye view of all your customised notifications, you can -go to `Preferences of your account `_. +go to `Preferences of your account `__. This allows you to make adjustments according to categories, users, and tags. Enabling mailing list mode @@ -174,7 +174,7 @@ In mailing list mode, you will receive one email per post, as happens with traditional mailing lists. This is desirable if you prefer to interact via email, without visiting the forum website. To activate the mailing list mode, go to the `email preferences -`_, check "Enable +`__, check "Enable mailing list mode" and save changes. .. _Discourse: https://discuss.python.org/ @@ -243,7 +243,7 @@ Setting expectations for open source participation ================================================== Burn-out is common in open source due to a misunderstanding of what users, contributors, -and maintainers should expect from each other. Brett Cannon gave a `talk `_ +and maintainers should expect from each other. Brett Cannon gave a `talk `__ about this topic that sets out to help everyone set reasonable expectations of each other in order to make open source pleasant for everyone involved. diff --git a/developer-workflow/development-cycle.rst b/developer-workflow/development-cycle.rst index 7f82ea42f..d39fd2cfc 100644 --- a/developer-workflow/development-cycle.rst +++ b/developer-workflow/development-cycle.rst @@ -134,7 +134,7 @@ former branch, for example, ``3.8`` or ``2.7``. The :ref:`versions` page contains list of active and end-of-life branches. The latest release for each Python version can be found on the `download page -`_. +`__. .. _stages: @@ -212,27 +212,27 @@ Repository administration ------------------------- The source code is currently hosted on `GitHub -`_ in the `Python organization `_. +`__ in the `Python organization `__. Organization repository policy ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Within the `GitHub Python organization `_, +Within the `GitHub Python organization `__, repositories are expected to relate to the Python language, the CPython reference implementation, their documentation and their development workflow. This includes, for example: -* The reference implementation of Python and related repositories: `CPython `_. -* Tooling and support around CPython development: `pyperformance `_, `Bedevere `_. -* Helpers and backports for Python/CPython features: `typing_extensions `_, `typeshed `_, `tzdata `_, `pythoncapi-compat `_. -* Organization-related repositories: the `Code of Conduct `_, `.github `_. -* Documentation and websites for all the above: `python.org repository `_, `PEPs `_, `Devguide `_, docs translations. -* Infrastructure for all the above: `docsbuild-scripts `_, `buildmaster-config `_. -* Discussions and notes around official development-related processes and events: `steering-council `_, `core-sprint `_. +* The reference implementation of Python and related repositories: `CPython `__. +* Tooling and support around CPython development: `pyperformance `__, `Bedevere `__. +* Helpers and backports for Python/CPython features: `typing_extensions `__, `typeshed `__, `tzdata `__, `pythoncapi-compat `__. +* Organization-related repositories: the `Code of Conduct `__, `.github `__. +* Documentation and websites for all the above: `python.org repository `__, `PEPs `__, `Devguide `__, docs translations. +* Infrastructure for all the above: `docsbuild-scripts `__, `buildmaster-config `__. +* Discussions and notes around official development-related processes and events: `steering-council `__, `core-sprint `__. Before adding a new repository to the organization, open a discussion to seek consensus -in the `Committers Discourse category `_. -Once people are satisfied with that, ask the `Python steering council `_ +in the `Committers Discourse category `__. +Once people are satisfied with that, ask the `Python steering council `__ to grant permission. Note that several repositories remain in the organization for historic reasons, @@ -241,18 +241,18 @@ and would probably not be appropriate to add today. Generally, new repositories should start their life under personal GitHub accounts or other GitHub orgs. It is relatively easy to move a repository to the organization once it is mature. For example, this would now apply to -experimental features like `asyncio `_, -`exceptiongroups `_, +experimental features like `asyncio `__, +`exceptiongroups `__, and drafts of new guides and other documentation (for example, `redistributor-guide -`_). +`__). -General-use tools and libraries (for example, `mypy `_ -or `Black `_) should also be developed outside +General-use tools and libraries (for example, `mypy `__ +or `Black `__) should also be developed outside the ``python`` organization, unless core devs (as represented by the SC) specifically want to “bless” one implementation (as with -`typeshed `_, -`tzdata `_, or -`pythoncapi-compat `_). +`typeshed `__, +`tzdata `__, or +`pythoncapi-compat `__). Organization owner policy @@ -264,7 +264,7 @@ at all levels including organization membership, team membership, access control, and merge privileges on all repositories. For full details of the permission levels see `GitHub's documentation on Organization permission levels -`_. +`__. This role is paramount to the security of the Python Language, Community, and Infrastructure. @@ -315,7 +315,7 @@ The Administrator role on the repository allows for managing all aspects including collaborators, access control, integrations, webhooks, and branch protection. For full details of the permission levels see `GitHub's documentation on repository permission levels -`_. +`__. Common reasons for this role are: maintenance of core workflow tooling, Release Managers for all :ref:`in-development `, :ref:`maintenance `, and :ref:`security mode ` diff --git a/developer-workflow/extension-modules.rst b/developer-workflow/extension-modules.rst index 7131cfdf8..fa4c11868 100644 --- a/developer-workflow/extension-modules.rst +++ b/developer-workflow/extension-modules.rst @@ -562,7 +562,7 @@ Now that the configuration is in place, it remains to compile the project: .. tip:: - We recommend installing `Podman `_ + We recommend installing `Podman `__ instead of Docker since the former does not require a background service and avoids creating files owned by the ``root`` user in some cases. @@ -609,8 +609,8 @@ by executing :cpy-file:`Tools/build/regen-configure.sh`: If Docker complains about missing permissions, this Stack Overflow post could be useful in solving the issue: `How to fix docker: permission denied -`_. Alternatively, you may try -using `Podman `_. +`__. Alternatively, you may try +using `Podman `__. Missing ``Py_BUILD_CORE`` define when using internal headers ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/developer-workflow/grammar.rst b/developer-workflow/grammar.rst index d574dfed7..bd314c61e 100644 --- a/developer-workflow/grammar.rst +++ b/developer-workflow/grammar.rst @@ -5,4 +5,4 @@ Changing CPython's grammar ========================== This document is now part of the -`CPython Internals Docs `_. +`CPython Internals Docs `__. diff --git a/developer-workflow/sbom.rst b/developer-workflow/sbom.rst index 756c17570..c8a2facd1 100644 --- a/developer-workflow/sbom.rst +++ b/developer-workflow/sbom.rst @@ -5,15 +5,15 @@ Software Bill-of-Materials (abbreviated as "SBOM") is a document for sharing information about software and how it's been composed. This format is used most often in the security space for checking software and its dependencies for vulnerabilities using vulnerability databases like -`CVE `_ and `OSV `_. The SBOM format -that the CPython project uses is `SPDX `_ +`CVE `__ and `OSV `__. The SBOM format +that the CPython project uses is `SPDX `__ which can be transformed into other formats if necessary by consumers. There are multiple sources of third-party dependencies for CPython. Some are vendored into the source code of CPython itself (like ``mpdecimal`` vendored at :cpy-file:`Modules/_decimal/libmpdec`) or they could be optionally pulled in during builds like Windows using dependencies from the -`python/cpython-source-deps `_ +`python/cpython-source-deps `__ repository. Whenever adding or updating a third-party dependency, an update will likely @@ -51,10 +51,10 @@ Adding a new dependency When adding a dependency it's important to have the following information: * Name, version, and download URL of the project -* License of the project as an `SPDX License Expression `_ +* License of the project as an `SPDX License Expression `__ * Software identifiers that match values in vulnerability databases - (`CPE `_ and - `Package URLs `_ + (`CPE `__ and + `Package URLs `__ or "PURLs") * Paths to include and exclude in the CPython source tree corresponding to this dependency diff --git a/development-tools/clang.rst b/development-tools/clang.rst index b353d82f0..149fb7adc 100644 --- a/development-tools/clang.rst +++ b/development-tools/clang.rst @@ -11,7 +11,7 @@ libraries. This document does not cover interpreting the findings. For a discussion of interpreting results, see Marshall Clow's `Testing libc++ with --fsanitize=undefined `_. The +-fsanitize=undefined `__. The blog posting is a detailed examinations of issues uncovered by Clang in ``libc++``. @@ -45,7 +45,7 @@ flags are passed through ``CFLAGS`` and ``CXXFLAGS``, and sometimes through ``CC`` and ``CXX`` (in addition to the compiler). A complete list of sanitizers can be found at `Controlling Code Generation -`_. +`__. .. note:: @@ -70,7 +70,7 @@ Pre-built Clang builds are available for most platforms: includes the "C++ clang tools for windows" feature. You can also build ``clang`` from source; refer to -`the clang documentation `_ for details. +`the clang documentation `__ for details. The installer does not install all the components needed on occasion. For example, you might want to run a ``scan-build`` or examine the results with @@ -284,6 +284,6 @@ Or, you could ignore the entire file with:: Unfortunately, you won't know what to ignorelist until you run the sanitizer. The documentation is available at `Sanitizer special case list -`_. +`__. .. _Valgrind: https://github.com/python/cpython/blob/main/Misc/README.valgrind diff --git a/development-tools/gdb.rst b/development-tools/gdb.rst index 8f89ea136..835b2dbc7 100644 --- a/development-tools/gdb.rst +++ b/development-tools/gdb.rst @@ -29,7 +29,7 @@ this approach is less helpful when debugging the runtime virtual machine, since the main interpreter loop function, ``_PyEval_EvalFrameDefault``, is well over 4,000 lines long as of Python 3.12. Fortunately, among the `many ways to set breakpoints -`_, +`__, you can break at C labels, such as those generated for computed gotos. If you are debugging an interpreter compiled with computed goto support (generally true, certainly when using GCC), each instruction will be diff --git a/documentation/devguide.rst b/documentation/devguide.rst index 7c53d054e..9f2ada23c 100644 --- a/documentation/devguide.rst +++ b/documentation/devguide.rst @@ -23,7 +23,7 @@ Changes to the Developer's Guide are published when pull requests are merged. Changes to the Python documentation are published regularly, ususally within 48 hours of the change being committed. -The documentation is also `published for each release `_, +The documentation is also `published for each release `__, which may also be used by redistributors. diff --git a/documentation/help-documenting.rst b/documentation/help-documenting.rst index 1c64b4832..23520375c 100644 --- a/documentation/help-documenting.rst +++ b/documentation/help-documenting.rst @@ -37,8 +37,8 @@ The in-development and recent maintenance branches are rebuilt once per day. If you would like to be more involved with documentation, consider subscribing to the `Documentation category on the Python Discourse -`_ and the -`docs@python.org `_ mailing list +`__ and the +`docs@python.org `__ mailing list where user issues are raised and documentation toolchain, projects, and standards are discussed. diff --git a/documentation/markup.rst b/documentation/markup.rst index cad0b4d9c..f9291a335 100644 --- a/documentation/markup.rst +++ b/documentation/markup.rst @@ -28,7 +28,7 @@ attribute definitions ``.. attribute: `attr-name``` :ref:`inform attribute references ``:attr:`attr-name``` :ref:`roles` reference labels ``.. _label-name:`` :ref:`doc-ref-role` internal references ``:ref:`label-name``` :ref:`doc-ref-role` -external links ```Link text `_`` :ref:`hyperlinks` +external links ```Link text `__`` :ref:`hyperlinks` roles w/ custom text ``:role:`custom text ``` :ref:`roles` roles w/ only last part ``:role:`~hidden.hidden.visible``` :ref:`roles` roles w/o link ``:role:`!target``` :ref:`roles` @@ -51,7 +51,7 @@ language, this will not take too long. .. seealso:: The authoritative `reStructuredText User - Documentation `_. + Documentation `__. Use of whitespace @@ -185,9 +185,12 @@ Hyperlinks External links ^^^^^^^^^^^^^^ -Use ```Link text `_`` for inline web links. If the link text +Use ```Link text `__`` for inline web links. If the link text should be the web address, you don't need special markup at all, the parser -finds links and mail addresses in ordinary text. +finds links and mail addresses in ordinary text. Prefer anonymous hyperlinks +(with a double underscore) over named hyperlinks (with a single underscore) +to avoid target name clashes. + Internal links ^^^^^^^^^^^^^^ @@ -343,7 +346,7 @@ they are used in the Python documentation. This is just an overview of Sphinx' extended markup capabilities; full coverage can be found in `its own documentation - `_. + `__. Meta-information markup diff --git a/documentation/style-guide.rst b/documentation/style-guide.rst index 68350c401..d90a14ce9 100644 --- a/documentation/style-guide.rst +++ b/documentation/style-guide.rst @@ -73,7 +73,7 @@ boolean abbreviated name with appropriate markup (for example, ``:type:`bool```). C API - Python's `API `_ used by C programmers + Python's `API `__ used by C programmers to write extension modules. All caps and unhyphenated. CPU @@ -122,7 +122,7 @@ such as "for example" or "that is." Diátaxis ======== -Python's documentation strives to follow the `Diátaxis `_ +Python's documentation strives to follow the `Diátaxis `__ framework. This means adapting the writing style according to the nature of the documentation that is being written. The framework splits documentation into four distinct types: tutorials, how-to guides, reference, and @@ -135,7 +135,7 @@ explanation. and abstract concepts should be avoided. Please consult the Diátaxis guide on :ref:`diataxis:tutorials` for more detail. -* `Python how-to guides `_ are +* `Python how-to guides `__ are designed to guide a user through a problem-field. Both tutorials and how-to guides are instructional rather than explanatory and should provide logical steps on how to complete a task. However, @@ -158,7 +158,7 @@ explanation. found throughout Python's documentation, for example the :ref:`python:unicode-howto`. -Please consult the `Diátaxis `_ guide for more +Please consult the `Diátaxis `__ guide for more detail. diff --git a/documentation/translations/coordinating.rst b/documentation/translations/coordinating.rst index 066237e5d..a7872b6ae 100644 --- a/documentation/translations/coordinating.rst +++ b/documentation/translations/coordinating.rst @@ -12,7 +12,7 @@ Communication/help channels =========================== Discussions about translations occur on the Python Docs Discord -`#translations channel `_ and the +`#translations channel `__ and the `translations category `_ of the Python Discourse. For administrative issues, ping ``@python/editorial-board``. @@ -72,16 +72,16 @@ account, with the correct Git hierarchy and folder structure. This can be done in several ways, and depends on what translation process you plan to use. Each translation is assigned an appropriate lowercase -`IETF language tag `_. +`IETF language tag `__. The tag may have an optional subtag, joined with a dash. For example, ``pt`` (Portuguese) or ``pt-br`` (Brazilian Portuguese). The repository name is then: ``python-docs-TAG`` The name of each branch should be the Python version it holds translations for, for example, ``3.14``. The files should be structured like the source files -in `CPython/Doc `_. +in `CPython/Doc `__. A correctly set up repository looks like this: -`python-docs-pl `_ +`python-docs-pl `__ Below, the recommended ways for starting your repository are described. You can choose another way if you like; it’s up to you. @@ -100,7 +100,7 @@ Translation platform ~~~~~~~~~~~~~~~~~~~~ You can also start your translation using -`Transifex `_. +`Transifex `__. This will allow you to translate via the web interface, and to use shared automatically updated source files. @@ -155,7 +155,7 @@ PEP 545 summary Here are the essential points of :PEP:`545`: - Each translation is assigned an appropriate lowercase - `IETF language tag `_. + `IETF language tag `__. The tag may have an optional region subtag, joined with a dash. For example, ``pt`` (Portuguese) or ``pt-br`` (Brazilian Portuguese). @@ -210,10 +210,10 @@ Testing should ideally be set up in your repository, and will help catch errors early and ensure translation quality. Testing generally consists of building, and linting with :pypi:`sphinx-lint`. -See `this documentation `_ +See `this documentation `__ for sample workflows with usage guides. -The `dashboard `_ +The `dashboard `__ also tests translations and uploads error logs. @@ -289,7 +289,7 @@ Is there a Weblate instance we can translate on? ------------------------------------------------ There is currently no Weblate instance for Python translations. -See this `Discourse thread `_ +See this `Discourse thread `__ for updates. diff --git a/documentation/translations/translating.rst b/documentation/translations/translating.rst index 6252add5a..2e4f6cf91 100644 --- a/documentation/translations/translating.rst +++ b/documentation/translations/translating.rst @@ -32,7 +32,7 @@ For more details about translations and their progress, see - :github:`GitHub ` * - `French (fr) `__ - Julien Palard (:github-user:`JulienPalard`) - - `AFPy/python-docs-fr `_, + - `AFPy/python-docs-fr `__, :github:`mirror ` * - `Greek (el) `__ - | Lysandros Nikolaou (:github-user:`lysnikolaou`), @@ -122,7 +122,7 @@ If there is already a repository for your language team (there may be links to Telegrams/Discords in the ``README``), join and introduce yourself. Your fellow translators will be more than happy to help! General discussions about translations occur on the Python Docs Discord -`#translations channel `_ and the +`#translations channel `__ and the `translations category `_ of the Python Discourse. .. _translation-style-guide: @@ -215,7 +215,7 @@ Code examples Translate values in code examples, that is string literals, and comments. Don't translate keywords or names, including variable, function, class, argument, -and attribute names. An example of a translated codeblock from the `tutorial `_ +and attribute names. An example of a translated codeblock from the `tutorial `__ is provided below: .. code-block:: python @@ -259,7 +259,7 @@ through the following resources from the Transifex documentation: Within the organization, a project for translating the :github:`Python Docs Sphinx Theme ` can also be found. -For further information about Transifex see our `documentation `_. +For further information about Transifex see our `documentation `__. Resources @@ -270,10 +270,10 @@ Some useful resources: - :ref:`git-boot-camp`: Several translations accept contributions by pull requests. Most have their own guide for how to do this, but this can provide useful tips. -- `Translation issues & improvements `_ GitHub project: +- `Translation issues & improvements `__ GitHub project: This project contains issues and pull requests that aim to improve the Python documentation for translations. -- `Python Pootle archive `_: +- `Python Pootle archive `__: Pootle is no longer used for translation. Contains translations for old Python versions. @@ -322,7 +322,7 @@ How do I translate the Python Docs Sphinx Theme? The Sphinx theme for the Python documentation supports localization. You can translate either on -`Transifex `_ +`Transifex `__ (see :ref:`translating on Transifex ` for more information) or locally by following the steps outlined below. @@ -357,7 +357,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 +`devguide `__ adding yourself to the table at the top of this page, and ping ``@python/editorial-board``. diff --git a/getting-started/git-boot-camp.rst b/getting-started/git-boot-camp.rst index 2ecaa62f0..b845e00aa 100644 --- a/getting-started/git-boot-camp.rst +++ b/getting-started/git-boot-camp.rst @@ -33,7 +33,7 @@ relevant to CPython's workflow. .. note:: Setting up Git aliases for common tasks can be useful to you. You can get more information about that in - `Git documentation `_ + `Git documentation `__ .. _fork-cpython: @@ -280,7 +280,7 @@ Compare to the ``main`` branch:: $ git diff main Exclude generated files from diff using an ``attr`` -`pathspec `_ (note the +`pathspec `__ (note the single quotes):: $ git diff main ':(attr:!generated)' @@ -289,7 +289,7 @@ Exclude generated files from diff by default:: $ git config diff.generated.binary true -The ``generated`` `attribute `_ is +The ``generated`` `attribute `__ is defined in :cpy-file:`.gitattributes`, found in the repository root. .. _push-changes: @@ -389,8 +389,8 @@ you run ``git merge upstream/main``. When it happens, you need to resolve conflict. See these articles about resolving conflicts: -- `About merge conflicts `_ -- `Resolving a merge conflict using the command line `_ +- `About merge conflicts `__ +- `Resolving a merge conflict using the command line `__ .. _git_from_patch: @@ -443,8 +443,8 @@ Scenario: - A contributor made a pull request to CPython. - Before merging it, you want to be able to test their changes locally. -If you've got `GitHub CLI `_ or -`hub `_ installed, you can do:: +If you've got `GitHub CLI `__ or +`hub `__ installed, you can do:: $ gh co # GitHub CLI $ hub pr checkout # hub @@ -523,7 +523,7 @@ The bad example contains bullet points that are a direct effect of the PR life cycle, while being irrelevant to the final change. .. note:: - `How to Write a Git Commit Message `_ + `How to Write a Git Commit Message `__ is a nice article describing how to write a good commit message. Finally, press the :guilabel:`Confirm squash and merge` button. @@ -557,7 +557,7 @@ 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. Use the utility script -`cherry_picker.py `_ +`cherry_picker.py `__ to backport the commit. The commit hash for backporting is the squashed commit that was merged to @@ -649,12 +649,12 @@ To edit an open pull request that targets ``main``: GitHub CLI ---------- -`GitHub CLI `_ is a command-line +`GitHub CLI `__ is a command-line interface that allows you to create, update, and check GitHub issues and pull requests. You can install GitHub CLI `by following these instructions -`_. After installing, +`__. After installing, you need to authenticate:: $ gh auth login @@ -740,6 +740,6 @@ Change into a directory to work from that branch. For example:: .. seealso:: - * `Git Reference Manual `_ + * `Git Reference Manual `__ * `"Experiment on your code freely with Git worktree" - `_ + `__ diff --git a/getting-started/pull-request-lifecycle.rst b/getting-started/pull-request-lifecycle.rst index 46975b7f7..d1f7e26a5 100644 --- a/getting-started/pull-request-lifecycle.rst +++ b/getting-started/pull-request-lifecycle.rst @@ -183,7 +183,7 @@ resolved as follows: When running the final command, Git may open an editor for writing a commit message. It is usually okay to leave that as-is and close the editor. -See `the merge command's documentation `_ +See `the merge command's documentation `__ for a detailed technical explanation. @@ -283,7 +283,7 @@ The automated checklist runs through: * Has the documentation been updated? * Has the test suite been updated? * Has an entry under ``Misc/NEWS.d/next`` been added? - (using `blurb-it `_, + (using `blurb-it `__, or the :pypi:`blurb` tool) * Has ``Misc/ACKS`` been updated? * Has ``configure`` been regenerated, if necessary? @@ -329,7 +329,7 @@ instructions on how the commit message should look like when merging a pull request. .. note:: - `How to Write a Git Commit Message `_ + `How to Write a Git Commit Message `__ is a nice article that describes how to write a good commit message. @@ -417,7 +417,7 @@ This will get your changes up to GitHub. Now you want to `create a pull request from your fork -`_. +`__. If this is a pull request in response to a pre-existing issue on the `issue tracker`_, please make sure to reference the issue number using ``gh-NNNNN:`` prefix in the pull request title and ``#NNNNN`` in the description. @@ -452,7 +452,7 @@ existing patch. In this case, both parties should sign the :ref:`CLA `. When creating a pull request based on another person's patch, provide attribution to the original patch author by adding "Co-authored-by: Author Name ." to the pull request description and commit message. -See `the GitHub article `_ +See `the GitHub article `__ on how to properly add the co-author info. See also :ref:`Applying a Patch to Git `. diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index a6ba77959..df208f28c 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -20,9 +20,9 @@ compiled version of the CPython interpreter (CPython is the version of Python available from https://www.python.org/). It also gives an overview of the directory structure of the CPython source code. -Alternatively, if you have `Docker `_ installed you +Alternatively, if you have `Docker `__ installed you might want to use `our official images -`_. These +`__. These contain the latest releases of several Python versions, along with Git head, and are provided for development and testing purposes only. @@ -38,23 +38,23 @@ Install Git .. c_install_git_start -CPython is developed using `Git `_ for version control. The Git +CPython is developed using `Git `__ for version control. The Git command line program is named ``git``; this is also used to refer to Git itself. Git is easily available for all common operating systems. - **Install** As the CPython repo is hosted on GitHub, please refer to either the - `GitHub setup instructions `_ - or the `Git project instructions `_ for step-by-step + `GitHub setup instructions `__ + or the `Git project instructions `__ for step-by-step installation directions. You may also want to consider a graphical client - such as `TortoiseGit `_ or - `GitHub Desktop `_. + such as `TortoiseGit `__ or + `GitHub Desktop `__. - **Configure** Configure :ref:`your name and email ` and create - `an SSH key `_ + `an SSH key `__ as this will allow you to interact with GitHub without typing a username and password each time you execute a command, such as ``git pull``, ``git push``, or ``git fetch``. On Windows, you should also @@ -141,7 +141,7 @@ Install pre-commit as a Git hook -------------------------------- To make sure your code is linted correctly, we recommend setting up -`pre-commit `_ as a Git hook:: +`pre-commit `__ as a Git hook:: $ pre-commit install --allow-missing-config pre-commit installed at .git/hooks/pre-commit @@ -170,7 +170,7 @@ working only on pure Python code the pydebug build provides several useful checks that one should not skip. .. seealso:: The effects of various configure and build flags are documented in - the `Python configure docs `_. + the `Python configure docs `__. .. _unix-compiling: @@ -822,7 +822,7 @@ some of CPython's modules (for example, ``zlib``). 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. + `libmpdec `__ library. Either build it from sources or install this package from https://deb.sury.org. @@ -889,7 +889,7 @@ some of CPython's modules (for example, ``zlib``). --with-dbmliborder=gdbm:ndbm (``--with-dbmliborder`` is a workaround for a Homebrew-specific change - to ``gdbm``; see `#89452 `_ + to ``gdbm``; see `#89452 `__ for details.) .. tab:: MacPorts @@ -928,7 +928,7 @@ some of CPython's modules (for example, ``zlib``). For more details on various options and considerations for building, refer to the `macOS README - `_. + `__. .. note:: While you need a C compiler to build CPython, you don't need any knowledge of the C language to contribute! Vast areas of CPython are @@ -981,7 +981,7 @@ If a change is made to Python which relies on some POSIX system-specific functionality (such as using a new system call), it is necessary to update the :cpy-file:`configure` script to test for availability of the functionality. Python's :file:`configure` script is generated from :cpy-file:`configure.ac` -using `GNU Autoconf `_. +using `GNU Autoconf `__. After editing :file:`configure.ac`, run ``make regen-configure`` to generate :file:`configure`, :cpy-file:`pyconfig.h.in`, and :cpy-file:`aclocal.m4`. @@ -1185,13 +1185,13 @@ What is GitHub Codespaces? If you'd like to start contributing to CPython without needing to set up a local developer environment, you can use -`GitHub Codespaces `_. +`GitHub Codespaces `__. Codespaces is a cloud-based development environment offered by GitHub that allows developers to write, build, test, and debug code directly within their web browser or in Visual Studio Code (VS Code). To help you get started, CPython contains a -`devcontainer folder `_ +`devcontainer folder `__ with a JSON configuration file that provides consistent and versioned codespace configurations for all users of the project. It also contains a Dockerfile that allows you to set up the same environment but locally in a Docker container if @@ -1204,7 +1204,7 @@ Create a CPython codespace Here are the basic steps needed to contribute a pull request using Codespaces. You first need to navigate to the -`CPython repo `_ hosted on GitHub. +`CPython repo `__ hosted on GitHub. Then you will need to: @@ -1229,7 +1229,7 @@ Then you will need to: 2. A screen should appear that lets you know your codespace is being set up. (Note: Since the CPython devcontainer is provided, codespaces will use the configuration it specifies.) -3. A `web version of VS Code `_ will open inside your web +3. A `web version of VS Code `__ will open inside your web browser, already linked up with your code and a terminal to the remote codespace where CPython and its documentation have already been built. 4. Use the terminal with the usual Git commands to create a new branch, commit diff --git a/index.rst b/index.rst index e19bb8826..0af90e295 100644 --- a/index.rst +++ b/index.rst @@ -31,7 +31,7 @@ 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 `_ +2. Fork `the CPython repository `__ to your GitHub account and :ref:`get the source code ` using:: git clone https://github.com//cpython @@ -91,7 +91,7 @@ instructions please see the :ref:`setup guide `. git checkout -b fix-issue-12345 main If an issue does not already exist, please `create it - `_. Trivial issues (for example, typo fixes) do + `__. Trivial issues (for example, typo fixes) do not require any issue to be created. 6. Once you fixed the issue, run the tests, and the patchcheck: @@ -125,10 +125,10 @@ instructions please see the :ref:`setup guide `. gh-12345: Fix some bug in spam module 8. Add a News entry into the ``Misc/NEWS.d`` directory as individual file. The - news entry can be created by using `blurb-it `_, + 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 `_. + `repository `__. .. note:: @@ -159,12 +159,12 @@ this guide, then the `Core Python Mentorship`_ group is available to help guide contributors through the process. A number of individuals from the Python community have contributed to a series -of excellent guides at `Open Source Guides `_. +of excellent guides at `Open Source Guides `__. Core developers and contributors alike will find the following guides useful: -* `How to Contribute to Open Source `_ -* `Building Welcoming Communities `_ +* `How to Contribute to Open Source `__ +* `Building Welcoming Communities `__ Guide for contributing to Python: @@ -251,8 +251,8 @@ Key resources * `Buildbot status`_ * Source code - * `Browse online `_ - * `Snapshot of the *main* branch `_ + * `Browse online `__ + * `Snapshot of the *main* branch `__ * PEPs_ (Python Enhancement Proposals) * :ref:`help` @@ -279,7 +279,7 @@ Additional resources * :ref:`clang` * Various tools with configuration files as found in the `Misc directory`_ * Information about editors and their configurations can be found in the - `wiki `_ + `wiki `__ * `python.org maintenance`_ * :ref:`Search this guide ` diff --git a/internals/compiler.rst b/internals/compiler.rst index 5b43e1e6d..f22039c64 100644 --- a/internals/compiler.rst +++ b/internals/compiler.rst @@ -7,4 +7,4 @@ Compiler design .. highlight:: none This document is now part of the -`CPython Internals Docs `_. +`CPython Internals Docs `__. diff --git a/internals/garbage-collector.rst b/internals/garbage-collector.rst index acbcedf0e..d86bbf8a1 100644 --- a/internals/garbage-collector.rst +++ b/internals/garbage-collector.rst @@ -9,4 +9,4 @@ Garbage collector design .. highlight:: none This document is now part of the -`CPython Internals Docs `_. +`CPython Internals Docs `__. diff --git a/internals/interpreter.rst b/internals/interpreter.rst index a7ae39c12..52c150944 100644 --- a/internals/interpreter.rst +++ b/internals/interpreter.rst @@ -5,4 +5,4 @@ The bytecode interpreter ======================== This document is now part of the -`CPython Internals Docs `_. +`CPython Internals Docs `__. diff --git a/internals/parser.rst b/internals/parser.rst index 688ad61e7..9700c25b0 100644 --- a/internals/parser.rst +++ b/internals/parser.rst @@ -7,4 +7,4 @@ Guide to the parser .. highlight:: none This document is now part of the -`CPython Internals Docs `_. +`CPython Internals Docs `__. diff --git a/testing/buildbots.rst b/testing/buildbots.rst index e03849935..1e711ab6b 100644 --- a/testing/buildbots.rst +++ b/testing/buildbots.rst @@ -11,7 +11,7 @@ branches `, Python has a set of dedicated machines (called *buildbots* or *build workers*) used for continuous integration. They span a number of hardware/operating system combinations. Furthermore, each machine hosts several *builders*, one per active branch: when a new change is pushed -to this branch on the public `GitHub repository `_, all corresponding builders +to this branch on the public `GitHub repository `__, all corresponding builders will schedule a new build to be run as soon as possible. The build steps run by the buildbots are the following: diff --git a/testing/coverage.rst b/testing/coverage.rst index d01141a7d..c34bb5235 100644 --- a/testing/coverage.rst +++ b/testing/coverage.rst @@ -127,7 +127,7 @@ to install coverage. You can now use python without the ./ for the rest of these instructions, as long as your venv is activated. For more info on venv see `Virtual Environment -`_ documentation. +`__ documentation. If this does not work for you for some reason, you should try using the in-development version of coverage.py to see if it has been updated as needed. diff --git a/testing/new-buildbot-worker.rst b/testing/new-buildbot-worker.rst index cac7bb63d..a0fbf9681 100644 --- a/testing/new-buildbot-worker.rst +++ b/testing/new-buildbot-worker.rst @@ -20,12 +20,12 @@ to go about setting up a buildbot worker, getting it added, and some hints about buildbot maintenance. Anyone running a buildbot that is part of the fleet should subscribe to the -`python-buildbots `_ +`python-buildbots `__ mailing list. This mailing list is also the place to contact if you want to contribute a buildbot but have questions. As for what kind of buildbot to run...take a look at our `current fleet -`_. Pretty much anything that isn't +`__. Pretty much anything that isn't on that list would be interesting: different Linux/Unix distributions, different versions of the various OSes, other OSes if you or someone are prepared to make the test suite actually pass on that new OS. Even if you only @@ -47,7 +47,7 @@ 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 `_ +`configuration repository `__ to discuss adding your worker and to obtain the needed workername and password. You can do some of the steps that follow before having the credentials, but it is easiest to have them before @@ -60,7 +60,7 @@ Setting up the buildbot worker Conventional always-on machines ------------------------------- -You need a recent version of the `buildbot `_ software, +You need a recent version of the `buildbot `__ software, and you will probably want a separate 'buildbot' user to run the buildbot software. You may also want to set the buildbot up using a virtual environment, depending on how you manage your system. We won't cover how to that @@ -103,7 +103,7 @@ can put the ``buildarea`` wherever you want to):: :file:`Scripts` directory of your Python installation.) On Windows, `the maximum length for a path is limited -`_. +`__. This might cause some tests to fail, unless long paths support is enabled. Use this PowerShell command to check whether long paths are enabled:: @@ -254,7 +254,7 @@ For Windows: * Alternatively (note: don't do both!), set up the worker service as described in the `buildbot documentation - `_. + `__. To start the worker running for your initial testing, you can do:: @@ -262,7 +262,7 @@ To start the worker running for your initial testing, you can do:: Then you can either wait for someone to make a commit, or you can pick a builder associated with your worker from the `list of builders -`_ and force a build. +`__ and force a build. In any case you should initially monitor builds on your builders to make sure the tests are passing and to resolve any platform issues that may be revealed @@ -273,7 +273,7 @@ idea. .. note:: If your buildbot worker is disconnecting regularly, it may be a symptom of the default ``keepalive`` value (``600`` for 10 minutes) being `set - `_ + `__ too high. You can change it to a lower value (for example, ``180`` for 3 minutes) in the ``buildbot.tac`` file found in your build area. @@ -282,7 +282,7 @@ Latent workers -------------- We also support running `latent workers -`_ +`__ on the AWS EC2 service. To set up such a worker: * Start an instance of your chosen base AMI and set it up as a @@ -305,7 +305,7 @@ instance(s), so it is recommended to periodically check and make sure there are no "zombie" instances running on your account, created by the buildbot master. Also, if you notice that your worker seems to have been down for an unexpectedly long time, please ping the `python-buildbots -`_ list to +`__ list to request that the master be restarted. Latent workers should also be updated periodically to include operating system @@ -390,7 +390,7 @@ Required resources ================== Based on the last time we did a `survey -`_ on +`__ on buildbot requirements, the recommended resource allocations for a python buildbot are at least: @@ -408,7 +408,7 @@ Security considerations ======================= We only allow builds to be triggered against commits to the -`CPython repository on GitHub `_. +`CPython repository on GitHub `__. This means that the code your buildbot will run will have been vetted by a committer. However, mistakes and bugs happen, as could a compromise, so keep this in mind when siting your buildbot on your network and establishing the security around it. @@ -427,7 +427,7 @@ VM setup. But if you are confident in your setup, we'd love to have a buildbot that runs python as root. Note that the above is a summary of a `discussion -`_ on +`__ on python-dev about buildbot security that includes examples of the tests for which privilege matters. There was no final consensus, but the information is useful as a point of reference. diff --git a/testing/run-write-tests.rst b/testing/run-write-tests.rst index 83a4a2861..34101bd2d 100644 --- a/testing/run-write-tests.rst +++ b/testing/run-write-tests.rst @@ -286,7 +286,7 @@ Benchmarks Benchmarking is useful to test that a change does not degrade performance. -`The Python Benchmark Suite `_ +`The Python Benchmark Suite `__ has a collection of benchmarks for all Python implementations. Documentation about running the benchmarks is in the `README.txt -`_ of the repo. +`__ of the repo. diff --git a/triage/github-bpo-faq.rst b/triage/github-bpo-faq.rst index 8c21a17fe..f4f8b16dd 100644 --- a/triage/github-bpo-faq.rst +++ b/triage/github-bpo-faq.rst @@ -16,7 +16,7 @@ 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 @@ -43,7 +43,7 @@ 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" `_. +`pressing "y" `__. How to do advanced searches? ============================ @@ -80,7 +80,7 @@ Add a checkbox list like this in the issue description:: 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"? =============================== @@ -88,7 +88,7 @@ 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 +`__ 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. diff --git a/triage/labels.rst b/triage/labels.rst index 34c7dc26c..96e0d8f58 100644 --- a/triage/labels.rst +++ b/triage/labels.rst @@ -9,7 +9,7 @@ Triagers, core developers and bots can add labels on GitHub to categorize issues and pull requests. Many labels are shared for both use cases, while some are dedicated only to one. Below is a possibly inexhaustive list, but it should get -you going. For a full list, see `here `_. +you going. For a full list, see `here `__. .. _general-purpose-labels: @@ -73,7 +73,7 @@ we don't have a dedicated Unix label. Use the :gh-label:`OS-unsupported` label for issues on platforms outside the support tiers defined in :pep:`11`. Applying this label adds the issue to -`a GitHub project `_ where +`a GitHub project `__ where it can be categorized further. See also the :ref:`Platform experts list `. @@ -92,7 +92,7 @@ they are encouraged to subscribe to them. Depending on the label, this might also automatically add the issue to a GitHub project. You can see the `full list of topic labels on GitHub -`_. +`__. .. _Version labels: diff --git a/triage/triage-team.rst b/triage/triage-team.rst index 68a88457e..7acebc130 100644 --- a/triage/triage-team.rst +++ b/triage/triage-team.rst @@ -86,14 +86,14 @@ Any existing active contributor to the Python repository on GitHub can transition into becoming a Python triager. They can request this to any core developer, either confidentially via a DM in Discourse, or publicly by opening an `issue in the core-workflow repository -`_. +`__. If the core developer decides you are ready to gain the extra privileges on the tracker, they will ask a :ref:`Python organization admin ` to invite you to the Python organisation, and then act as a mentor to you until you are ready to do things entirely on your own. For every new triager, it would be great to announce them in the -`Committers category `_ -on the `Python Discourse `_ +`Committers category `__ +on the `Python Discourse `__ (`example announcement `__). diff --git a/versions.rst b/versions.rst index 0a52829c2..d0f837991 100644 --- a/versions.rst +++ b/versions.rst @@ -7,14 +7,14 @@ Status of Python versions The ``main`` branch is currently the future Python |main_version|, and is the only branch that accepts new features. The latest release for each Python -version can be found on the `download page `_. +version can be found on the `download page `__. .. raw:: html :file: include/release-cycle.svg (See :ref:`below ` for a chart with older versions. -Another useful visualization is `endoflife.date/python `_.) +Another useful visualization is `endoflife.date/python `__.) Supported versions From 0e9faabf8519c49ae3070ee95707f7dc706c1b17 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Mon, 1 Dec 2025 10:23:54 +0800 Subject: [PATCH 03/48] Bump actions/checkout from 5 to 6 in the actions group (#1711) Bumps the actions group with 1 update: [actions/checkout](https://github.com/actions/checkout). Updates `actions/checkout` from 5 to 6 - [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/v5...v6) --- updated-dependencies: - dependency-name: actions/checkout dependency-version: '6' 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 | 2 +- .github/workflows/lint.yml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 6479277af..b85a45c1b 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -12,7 +12,7 @@ jobs: timeout-minutes: 10 steps: - - uses: actions/checkout@v5 + - uses: actions/checkout@v6 - uses: actions/setup-python@v6 with: python-version: "3" diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index c1554eb5e..4622f995a 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/lint.yml @@ -8,7 +8,7 @@ jobs: timeout-minutes: 10 steps: - - uses: actions/checkout@v5 + - uses: actions/checkout@v6 - uses: actions/setup-python@v6 with: python-version: "3.x" From 4732570b2e2ecaaa83804e07c6c42d2b07209f04 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Mon, 1 Dec 2025 11:02:33 +0000 Subject: [PATCH 04/48] Bump the pip group with 2 updates (#1710) --- requirements.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/requirements.txt b/requirements.txt index cb6b2cd5c..7c2bbd806 100644 --- a/requirements.txt +++ b/requirements.txt @@ -2,9 +2,9 @@ furo>=2022.6.4 jinja2 sphinx-autobuild>=2024.9.19 sphinx-inline-tabs>=2023.4.21 -sphinx-lint==1.0.1 +sphinx-lint==1.0.2 sphinx-notfound-page>=1.0.0 sphinx_copybutton>=0.3.3 sphinxext-opengraph>=0.13.0 sphinxext-rediraffe -Sphinx~=8.2.3 +Sphinx>=8.2.3 From 1830dddf03451b7bb2bf31b7c553a9789ed44bdf Mon Sep 17 00:00:00 2001 From: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> Date: Fri, 19 Dec 2025 11:41:00 +0000 Subject: [PATCH 05/48] Remove empty InternalDoc pages (GH-1712) The info is now in the CPython repo; the devguide has links to that and other guides. --- conf.py | 12 ++++-- developer-workflow/c-api.rst | 2 +- index.rst | 7 +--- internals/exploring.rst => internals.rst | 50 ++---------------------- internals/compiler.rst | 10 ----- internals/garbage-collector.rst | 12 ------ internals/index.rst | 20 ---------- internals/interpreter.rst | 8 ---- internals/parser.rst | 10 ----- 9 files changed, 15 insertions(+), 116 deletions(-) rename internals/exploring.rst => internals.rst (67%) delete mode 100644 internals/compiler.rst delete mode 100644 internals/garbage-collector.rst delete mode 100644 internals/index.rst delete mode 100644 internals/interpreter.rst delete mode 100644 internals/parser.rst diff --git a/conf.py b/conf.py index 0f6a820d8..02f9c7477 100644 --- a/conf.py +++ b/conf.py @@ -149,10 +149,14 @@ "pullrequest.rst": "getting-started/pull-request-lifecycle.rst", "setup.rst": "getting-started/setup-building.rst", # CPython Internals - "compiler.rst": "internals/compiler.rst", - "exploring.rst": "internals/exploring.rst", - "garbage_collector.rst": "internals/garbage-collector.rst", - "parser.rst": "internals/parser.rst", + "compiler.rst": "internals.rst", + "exploring.rst": "internals.rst", + "garbage_collector.rst": "internals.rst", + "parser.rst": "internals.rst", + "internals/compiler.rst": "internals.rst", + "internals/exploring.rst": "internals.rst", + "internals/garbage_collector.rst": "internals.rst", + "internals/parser.rst": "internals.rst", # Testing and Buildbots "buildbots.rst": "testing/buildbots.rst", "coverage.rst": "testing/coverage.rst", diff --git a/developer-workflow/c-api.rst b/developer-workflow/c-api.rst index c65e88ce1..a6523a909 100644 --- a/developer-workflow/c-api.rst +++ b/developer-workflow/c-api.rst @@ -387,7 +387,7 @@ Guidelines for adding to the Limited API details involve: - The GIL - - :ref:`Garbage collection ` + - Garbage collection - Memory layout of PyObject, lists/tuples and other structures If following these guidelines would hurt performance, add a fast function diff --git a/index.rst b/index.rst index 0af90e295..997f59932 100644 --- a/index.rst +++ b/index.rst @@ -267,11 +267,8 @@ Additional resources * Anyone can clone the sources for this guide. See :ref:`devguide`. * Help with ... - * :ref:`exploring` + * :ref:`internals` * :ref:`grammar` - * :ref:`parser` - * :ref:`compiler` - * :ref:`garbage_collector` * Tool support @@ -317,7 +314,7 @@ Full table of contents testing/index development-tools/index core-team/index - internals/index + internals versions contrib/index diff --git a/internals/exploring.rst b/internals.rst similarity index 67% rename from internals/exploring.rst rename to internals.rst index 0ae8337e8..89897eb19 100644 --- a/internals/exploring.rst +++ b/internals.rst @@ -1,53 +1,9 @@ -.. _exploring: +.. _internals: =================== -CPython source code +CPython's internals =================== -This section gives an overview of CPython's code structure and provides -a summary of file locations for modules and built-ins. - - -Source code layout -================== - -For a Python :term:`module`, the typical layout is: - -* :file:`Lib/{}.py` -* :file:`Modules/_{}.c` (if there's also a C accelerator module) -* :file:`Lib/test/test_{}.py` -* :file:`Doc/library/{}.rst` - -For an :term:`extension module`, the typical layout is: - -* :file:`Modules/{}module.c` -* :file:`Lib/test/test_{}.py` -* :file:`Doc/library/{}.rst` - -For :ref:`bltin-types`, the typical layout is: - -* :file:`Objects/{}object.c` -* :file:`Lib/test/test_{}.py` -* :cpy-file:`Doc/library/stdtypes.rst` - -For :ref:`built-in-funcs`, the typical layout is: - -* :cpy-file:`Python/bltinmodule.c` -* :cpy-file:`Lib/test/test_builtin.py` -* :cpy-file:`Doc/library/functions.rst` - -Some exceptions to these layouts are: - -* built-in type ``int`` is at :cpy-file:`Objects/longobject.c` -* built-in type ``str`` is at :cpy-file:`Objects/unicodeobject.c` -* built-in module ``sys`` is at :cpy-file:`Python/sysmodule.c` -* built-in module ``marshal`` is at :cpy-file:`Python/marshal.c` -* Windows-only module ``winreg`` is at :cpy-file:`PC/winreg.c` - - -Additional references -===================== - The CPython code base is constantly changing and evolving. Here's a sample of references about CPython's architecture aimed at building your understanding of CPython internals and its evolution: @@ -56,6 +12,7 @@ building your understanding of CPython internals and its evolution: :header: "Title", "Brief", "Author", "Version" :widths: 50, 50, 20, 5 + "`CPython's InternalDocs`_", "Docs on CPython internals maintained in the source tree", "", "" "`A guide from parser to objects, observed using GDB`_", "Code walk from Parser, AST, Sym Table and Objects", Louie Lu, 3.7.a0 "`Green Tree Snakes`_", "The missing Python AST docs", Thomas Kluyver, 3.6 "`Yet another guided tour of CPython`_", "A guide for how CPython REPL works", Guido van Rossum, 3.5 @@ -72,6 +29,7 @@ building your understanding of CPython internals and its evolution: "`A guide from parser to objects, observed using Eclipse`_", "Code walk from Parser, AST, Sym Table and Objects", Prashanth Raghu, 2.7.12 "`CPython internals: A ten-hour codewalk through the Python interpreter source code`_", "Code walk from source code to generators", Philip Guo, 2.7.8 +.. _CPython's InternalDocs: https://github.com/python/cpython/blob/main/InternalDocs/README.md .. _A guide from parser to objects, observed using GDB: https://hackmd.io/s/ByMHBMjFe diff --git a/internals/compiler.rst b/internals/compiler.rst deleted file mode 100644 index f22039c64..000000000 --- a/internals/compiler.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _compiler: - -=============== -Compiler design -=============== - -.. highlight:: none - -This document is now part of the -`CPython Internals Docs `__. diff --git a/internals/garbage-collector.rst b/internals/garbage-collector.rst deleted file mode 100644 index d86bbf8a1..000000000 --- a/internals/garbage-collector.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. _garbage-collector: -.. _gc: -.. _garbage_collector: - -======================== -Garbage collector design -======================== - -.. highlight:: none - -This document is now part of the -`CPython Internals Docs `__. diff --git a/internals/index.rst b/internals/index.rst deleted file mode 100644 index 05723f482..000000000 --- a/internals/index.rst +++ /dev/null @@ -1,20 +0,0 @@ -.. _internals: - -=================== -CPython's internals -=================== - -This guide describes the basics of CPython's internals. -It explains the layout of CPython's source code. -It also explains how the parser, compiler, and interpreter -work together to run your Python code. -Finally, it covers the garbage collector and how it manages memory. - -.. toctree:: - :maxdepth: 3 - - exploring - parser - compiler - interpreter - garbage-collector diff --git a/internals/interpreter.rst b/internals/interpreter.rst deleted file mode 100644 index 52c150944..000000000 --- a/internals/interpreter.rst +++ /dev/null @@ -1,8 +0,0 @@ -.. _interpreter: - -======================== -The bytecode interpreter -======================== - -This document is now part of the -`CPython Internals Docs `__. diff --git a/internals/parser.rst b/internals/parser.rst deleted file mode 100644 index 9700c25b0..000000000 --- a/internals/parser.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _parser: - -=================== -Guide to the parser -=================== - -.. highlight:: none - -This document is now part of the -`CPython Internals Docs `__. From ec0447ad318b673ec6a640c5af31d9cfe0ebb2a1 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Date: Sun, 21 Dec 2025 08:50:04 +0000 Subject: [PATCH 06/48] Pin to Sphinx 8.2.3 (#1716) --- requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/requirements.txt b/requirements.txt index 7c2bbd806..359d28268 100644 --- a/requirements.txt +++ b/requirements.txt @@ -7,4 +7,4 @@ sphinx-notfound-page>=1.0.0 sphinx_copybutton>=0.3.3 sphinxext-opengraph>=0.13.0 sphinxext-rediraffe -Sphinx>=8.2.3 +Sphinx~=8.2.3 From b24ed5025bb9efa6df0c638cdec81121f03ed8b3 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Sun, 21 Dec 2025 11:06:59 +0200 Subject: [PATCH 07/48] Clarify development cycle (#1681) Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- developer-workflow/development-cycle.rst | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/developer-workflow/development-cycle.rst b/developer-workflow/development-cycle.rst index d39fd2cfc..2f1cadbbd 100644 --- a/developer-workflow/development-cycle.rst +++ b/developer-workflow/development-cycle.rst @@ -68,8 +68,8 @@ Maintenance branches A branch for a previous feature release, currently being maintained for bug fixes, or for the next feature release in its :ref:`beta ` or :ref:`release candidate ` stages. -There is usually either one or two maintenance branches at any given time for -Python 3.x. After the final release of a new minor version (3.x.0), releases +There are usually either one or two maintenance branches at any given time. +After the final release of a new minor version (3.x.0), releases 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. @@ -190,7 +190,7 @@ severe enough (for example, crashes) that they deserve fixing before the final r All other issues should be deferred to the next development cycle, since stability is the strongest concern at this point. -While the goal is to have no code changes between a RC and a final release, +While the goal is to have no code changes between an RC and a final release, there may be a need for final documentation or test fixes. Any such proposed changes should be discussed first with the release manager. @@ -204,8 +204,7 @@ Final ^^^^^ When a final release is being cut, only the release manager (RM) can make -changes to the branch. After the final release is published, the full -:ref:`development cycle ` starts again for the next minor version. +changes to the branch. Repository administration From 43b50c317669a4ecbeb11ce2be8ba784fbbe3af8 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Sun, 21 Dec 2025 11:13:41 +0200 Subject: [PATCH 08/48] Replace local release-cycle.json with PEPs repo version (#1685) Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- .pre-commit-config.yaml | 2 - Makefile | 17 ++-- _tools/generate_release_cycle.py | 14 ++- conf.py | 5 +- include/release-cycle.json | 146 ------------------------------- 5 files changed, 26 insertions(+), 158 deletions(-) delete mode 100644 include/release-cycle.json diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index ae27fd1f2..c5beee4a3 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -7,14 +7,12 @@ repos: args: [--exit-non-zero-on-fix] - id: ruff-format name: Run Ruff (format) - args: [--check] - repo: https://github.com/pre-commit/pre-commit-hooks rev: v4.5.0 hooks: - id: check-case-conflict - id: check-merge-conflict - - id: check-json - id: check-yaml - id: debug-statements - id: end-of-file-fixer diff --git a/Makefile b/Makefile index 3d485ae2d..a3e176438 100644 --- a/Makefile +++ b/Makefile @@ -103,15 +103,20 @@ _ensure-pre-commit: lint: _ensure-pre-commit $(VENVDIR)/bin/python3 -m pre_commit run --all-files -# Defined so that "include/release-cycle.json" -# doesn't fall through to the catch-all target. -include/release-cycle.json: - @exit - -$(_RELEASE_CYCLE): include/release-cycle.json +# Generate all release cycle files together with a single script invocation +# Use branches.csv as the primary target, others depend on it +include/branches.csv: $(VENVDIR)/bin/python3 _tools/generate_release_cycle.py @echo Release cycle data generated. +# Other files are generated together with branches.csv +include/end-of-life.csv: include/branches.csv + @: +include/release-cycle-all.svg: include/branches.csv + @: +include/release-cycle.svg: include/branches.csv + @: + # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. .PHONY: Makefile diff --git a/_tools/generate_release_cycle.py b/_tools/generate_release_cycle.py index dd0a3a7c6..00373036d 100644 --- a/_tools/generate_release_cycle.py +++ b/_tools/generate_release_cycle.py @@ -7,6 +7,9 @@ import csv import datetime as dt import json +from functools import cache +from pathlib import Path +from urllib.request import urlopen import jinja2 @@ -37,12 +40,17 @@ def parse_version(ver: str) -> list[int]: return [int(i) for i in ver["key"].split(".")] +@cache +def get_versions() -> dict[str, dict[str, str | int]]: + with urlopen("https://peps.python.org/api/release-cycle.json") as in_file: + return json.loads(in_file.read().decode("utf-8")) + + class Versions: """For converting JSON to CSV and SVG.""" def __init__(self, *, limit_to_active=False, special_py27=False) -> None: - with open("include/release-cycle.json", encoding="UTF-8") as in_file: - self.versions = json.load(in_file) + self.versions = get_versions() # Generate a few additional fields for key, version in self.versions.items(): @@ -197,6 +205,8 @@ def main() -> None: versions = Versions() assert len(versions.versions) > 10 + Path("include").mkdir(exist_ok=True) + versions.write_csv() versions.write_svg(args.today, "include/release-cycle-all.svg") diff --git a/conf.py b/conf.py index 02f9c7477..c38e33dd8 100644 --- a/conf.py +++ b/conf.py @@ -1,4 +1,5 @@ import json +from urllib.request import urlopen extensions = [ 'notfound.extension', @@ -182,8 +183,8 @@ # Dynamically expose the Python version associated with the "main" branch. # Exactly one entry in ``release-cycle.json`` should have ``"branch": "main"``. -with open("include/release-cycle.json", encoding="UTF-8") as _f: - _cycle = json.load(_f) +with urlopen("https://peps.python.org/api/release-cycle.json") as _f: + _cycle = json.loads(_f.read().decode("utf-8")) _main_version = next( version for version, data in _cycle.items() if data.get("branch") == "main" diff --git a/include/release-cycle.json b/include/release-cycle.json deleted file mode 100644 index 26436bf00..000000000 --- a/include/release-cycle.json +++ /dev/null @@ -1,146 +0,0 @@ -{ - "3.15": { - "branch": "main", - "pep": 790, - "status": "feature", - "first_release": "2026-10-01", - "end_of_life": "2031-10", - "release_manager": "Hugo van Kemenade" - }, - "3.14": { - "branch": "3.14", - "pep": 745, - "status": "bugfix", - "first_release": "2025-10-07", - "end_of_life": "2030-10", - "release_manager": "Hugo van Kemenade" - }, - "3.13": { - "branch": "3.13", - "pep": 719, - "status": "bugfix", - "first_release": "2024-10-07", - "end_of_life": "2029-10", - "release_manager": "Thomas Wouters" - }, - "3.12": { - "branch": "3.12", - "pep": 693, - "status": "security", - "first_release": "2023-10-02", - "end_of_life": "2028-10", - "release_manager": "Thomas Wouters" - }, - "3.11": { - "branch": "3.11", - "pep": 664, - "status": "security", - "first_release": "2022-10-24", - "end_of_life": "2027-10", - "release_manager": "Pablo Galindo Salgado" - }, - "3.10": { - "branch": "3.10", - "pep": 619, - "status": "security", - "first_release": "2021-10-04", - "end_of_life": "2026-10", - "release_manager": "Pablo Galindo Salgado" - }, - "3.9": { - "branch": "3.9", - "pep": 596, - "status": "end-of-life", - "first_release": "2020-10-05", - "end_of_life": "2025-10-31", - "release_manager": "Łukasz Langa" - }, - "3.8": { - "branch": "3.8", - "pep": 569, - "status": "end-of-life", - "first_release": "2019-10-14", - "end_of_life": "2024-10-07", - "release_manager": "Łukasz Langa" - }, - "3.7": { - "branch": "3.7", - "pep": 537, - "status": "end-of-life", - "first_release": "2018-06-27", - "end_of_life": "2023-06-27", - "release_manager": "Ned Deily" - }, - "3.6": { - "branch": "3.6", - "pep": 494, - "status": "end-of-life", - "first_release": "2016-12-23", - "end_of_life": "2021-12-23", - "release_manager": "Ned Deily" - }, - "3.5": { - "branch": "3.5", - "pep": 478, - "status": "end-of-life", - "first_release": "2015-09-13", - "end_of_life": "2020-09-30", - "release_manager": "Larry Hastings" - }, - "3.4": { - "branch": "3.4", - "pep": 429, - "status": "end-of-life", - "first_release": "2014-03-16", - "end_of_life": "2019-03-18", - "release_manager": "Larry Hastings" - }, - "3.3": { - "branch": "3.3", - "pep": 398, - "status": "end-of-life", - "first_release": "2012-09-29", - "end_of_life": "2017-09-29", - "release_manager": "Georg Brandl, Ned Deily (3.3.7+)" - }, - "3.2": { - "branch": "3.2", - "pep": 392, - "status": "end-of-life", - "first_release": "2011-02-20", - "end_of_life": "2016-02-20", - "release_manager": "Georg Brandl" - }, - "2.7": { - "branch": "2.7", - "pep": 373, - "status": "end-of-life", - "first_release": "2010-07-03", - "end_of_life": "2020-01-01", - "release_manager": "Benjamin Peterson" - }, - "3.1": { - "branch": "3.1", - "pep": 375, - "status": "end-of-life", - "first_release": "2009-06-27", - "end_of_life": "2012-04-09", - "release_manager": "Benjamin Peterson" - }, - "3.0": { - "branch": "3.0", - "pep": 361, - "status": "end-of-life", - "first_release": "2008-12-03", - "end_of_life": "2009-06-27", - "release_manager": "Barry Warsaw" - }, - "2.6": { - "branch": "2.6", - "pep": 361, - "status": "end-of-life", - "first_release": "2008-10-01", - "end_of_life": "2013-10-29", - "release_manager": "Barry Warsaw" - } -} From 7e6a146b4fc8c4e2bc274f7bb3ac62f03c4a16f1 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Sun, 21 Dec 2025 11:20:39 +0200 Subject: [PATCH 09/48] Replace deprecated workflow with RTD app (#1713) --- .github/workflows/documentation-links.yml | 18 ------------------ 1 file changed, 18 deletions(-) delete mode 100644 .github/workflows/documentation-links.yml diff --git a/.github/workflows/documentation-links.yml b/.github/workflows/documentation-links.yml deleted file mode 100644 index bacb37d07..000000000 --- a/.github/workflows/documentation-links.yml +++ /dev/null @@ -1,18 +0,0 @@ -name: Read the Docs PR preview -on: - pull_request_target: - types: - - opened - -permissions: - pull-requests: write - -jobs: - documentation-links: - runs-on: ubuntu-latest - timeout-minutes: 10 - steps: - - uses: readthedocs/actions/preview@v1 - with: - project-slug: "cpython-devguide" - single-version: "true" From e583bd3f9407d5edacd94e6e2799e1d8032fda78 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Mon, 29 Dec 2025 11:53:23 +0200 Subject: [PATCH 10/48] Fix typos (#1714) Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- developer-workflow/c-api.rst | 2 +- developer-workflow/extension-modules.rst | 2 +- documentation/devguide.rst | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/developer-workflow/c-api.rst b/developer-workflow/c-api.rst index a6523a909..e7f129a27 100644 --- a/developer-workflow/c-api.rst +++ b/developer-workflow/c-api.rst @@ -104,7 +104,7 @@ This helps us ensure *newly added* API is consistent and maintainable. Also check with the C API WG before requiring a C feature not present in C99. While the *public* docs only promise compatibility with C11, in practice -we only intruduce C11 features individually as needed. +we only introduce C11 features individually as needed. .. _decisions repo: https://github.com/capi-workgroup/decisions/issues diff --git a/developer-workflow/extension-modules.rst b/developer-workflow/extension-modules.rst index fa4c11868..4d8c0ffca 100644 --- a/developer-workflow/extension-modules.rst +++ b/developer-workflow/extension-modules.rst @@ -574,7 +574,7 @@ Now that the configuration is in place, it remains to compile the project: :mod:`!_foo` discoverable and importable via ``import _foo``. * The final ``make`` step is generally not needed since the previous ``make`` - invokations may completely rebuild the project, but it could be needed in + invocations may completely rebuild the project, but it could be needed in some specific cases. Troubleshooting diff --git a/documentation/devguide.rst b/documentation/devguide.rst index 9f2ada23c..fc12c369f 100644 --- a/documentation/devguide.rst +++ b/documentation/devguide.rst @@ -22,7 +22,7 @@ lives in a `separate repository`_ and bug reports should be submitted to the Changes to the Developer's Guide are published when pull requests are merged. Changes to the Python documentation are published regularly, -ususally within 48 hours of the change being committed. +usually within 48 hours of the change being committed. The documentation is also `published for each release `__, which may also be used by redistributors. From 3e65c0c96150433530b74c9dc46210e2f4d4d027 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Tue, 30 Dec 2025 15:51:16 +0200 Subject: [PATCH 11/48] Make release cycle charts reusable (#1708) Co-authored-by: Petr Viktorin --- .gitignore | 4 +- Makefile | 4 +- _static/devguide_overrides.css | 96 ------------ _tools/generate_release_cycle.py | 4 +- _tools/release_cycle_template.svg.jinja | 186 +++++++++++++++++++----- make.ps1 | 2 +- versions.rst | 6 +- 7 files changed, 160 insertions(+), 142 deletions(-) diff --git a/.gitignore b/.gitignore index b71249201..f61a10830 100644 --- a/.gitignore +++ b/.gitignore @@ -90,5 +90,5 @@ celerybeat-schedule # Generated CSV and SVG files include/branches.csv include/end-of-life.csv -include/release-cycle.svg -include/release-cycle-all.svg +_static/release-cycle.svg +_static/release-cycle-all.svg diff --git a/Makefile b/Makefile index a3e176438..2f8e08614 100644 --- a/Makefile +++ b/Makefile @@ -22,8 +22,8 @@ REQUIREMENTS = requirements.txt _ALL_SPHINX_OPTS = --jobs $(JOBS) $(SPHINXOPTS) _RELEASE_CYCLE = include/branches.csv \ include/end-of-life.csv \ - include/release-cycle-all.svg \ - include/release-cycle.svg + _static/release-cycle-all.svg \ + _static/release-cycle.svg .PHONY: help help: diff --git a/_static/devguide_overrides.css b/_static/devguide_overrides.css index 5b6d67b09..625a9dda2 100644 --- a/_static/devguide_overrides.css +++ b/_static/devguide_overrides.css @@ -6,102 +6,6 @@ height: 110px; } -/* Release cycle chart */ - -.release-cycle-chart { - width: 100%; -} - -.release-cycle-chart .release-cycle-year-line { - stroke: var(--color-foreground-primary); - stroke-width: 0.8px; - opacity: 75%; -} - -.release-cycle-chart .release-cycle-year-text { - fill: var(--color-foreground-primary); -} - -.release-cycle-chart .release-cycle-today-line { - stroke: var(--color-brand-primary); - stroke-width: 1.6px; -} - -.release-cycle-chart .release-cycle-row-shade { - fill: var(--color-background-item); - opacity: 50%; -} - -.release-cycle-chart .release-cycle-version-label { - fill: var(--color-foreground-primary); -} - -.release-cycle-chart .release-cycle-blob { - stroke-width: 1.6px; - /* default colours, overridden below for individual statuses */ - fill: var(--color-background-primary); - stroke: var(--color-foreground-primary); -} - -.release-cycle-chart .release-cycle-blob-label { - /* white looks good on both light & dark */ - fill: white; -} - -.release-cycle-chart .release-cycle-blob-label.release-cycle-status-security, -.release-cycle-chart .release-cycle-blob-label.release-cycle-status-bugfix { - /* but use black to improve contrast for lighter backgrounds */ - fill: black; -} - -.release-cycle-chart .release-cycle-blob-label.release-cycle-status-end-of-life, -.release-cycle-chart .release-cycle-blob-label.release-cycle-status-prerelease, -.release-cycle-chart .release-cycle-blob-label.release-cycle-status-feature { - /* and FG when it's not in a blob */ - fill: var(--color-foreground-primary); -} - -.release-cycle-chart .release-cycle-status-end-of-life { - --status-bg-color: #DD2200; - --status-border-color: #FF8888; -} - -.release-cycle-chart .release-cycle-status-security { - --status-bg-color: #FFDD44; - --status-border-color: #FF8800; -} - -.release-cycle-chart .release-cycle-status-bugfix { - --status-bg-color: #00DD22; - --status-border-color: #008844; -} - -.release-cycle-chart .release-cycle-status-prerelease { - --status-bg-color: teal; - --status-border-color: darkgreen; -} - -.release-cycle-chart .release-cycle-status-feature { - --status-bg-color: #2222EE; - --status-border-color: #008888; -} - -.release-cycle-chart .release-cycle-blob { - fill: var(--status-bg-color); - stroke: transparent; -} - -.release-cycle-chart .release-cycle-blob-full { - fill: var(--status-bg-color); - stroke: var(--status-border-color); -} - -.release-cycle-chart .release-cycle-border { - fill: transparent; - stroke: var(--status-border-color); - stroke-width: 1.6px; -} - .good pre { border-left: 3px solid rgba(74, 182, 93, 1); } diff --git a/_tools/generate_release_cycle.py b/_tools/generate_release_cycle.py index 00373036d..24dfa03e7 100644 --- a/_tools/generate_release_cycle.py +++ b/_tools/generate_release_cycle.py @@ -208,10 +208,10 @@ def main() -> None: Path("include").mkdir(exist_ok=True) versions.write_csv() - versions.write_svg(args.today, "include/release-cycle-all.svg") + versions.write_svg(args.today, "_static/release-cycle-all.svg") versions = Versions(limit_to_active=True, special_py27=True) - versions.write_svg(args.today, "include/release-cycle.svg") + versions.write_svg(args.today, "_static/release-cycle.svg") if __name__ == "__main__": diff --git a/_tools/release_cycle_template.svg.jinja b/_tools/release_cycle_template.svg.jinja index d3d5866a0..9f23814a9 100644 --- a/_tools/release_cycle_template.svg.jinja +++ b/_tools/release_cycle_template.svg.jinja @@ -4,6 +4,104 @@ class="release-cycle-chart" viewBox="0 0 {{ diagram_width }} {{ diagram_height }}" > + @@ -11,9 +109,16 @@ + + {% for version in versions %} {% set y = version.y * line_height %} - {% if version.y % 2 %} {% for version in versions %} - + {% set top_y = version.y * line_height - 1 * SCALE %} {% set height = 1.25 * SCALE %} @@ -82,8 +187,6 @@ {% set end_x = date_to_x(version.end_of_life_date) %} {% set radius = 0.25 * SCALE %} - {% set small_text_y = version.y * line_height - 0.1 * SCALE %} - + + + {% for version in versions %} + + + {% set start_x = date_to_x(version.first_release_date) %} + {% set end_x = date_to_x(version.end_of_life_date) %} + {% set middle_x = ([end_x, date_to_x(version.start_security_date)]|min) %} + {% set small_text_y = version.y * line_height - 0.1 * SCALE %} - - {{ version.status }} - + {% for cls in ('text-outline', 'text-main') %} + + {{ version.status }} + + {% endfor %} {% endfor %} - - - diff --git a/make.ps1 b/make.ps1 index ffda67269..c8ad842c9 100644 --- a/make.ps1 +++ b/make.ps1 @@ -65,7 +65,7 @@ if ($target -Eq "clean") { $BUILDDIR, $_VENV_DIR, "include/branches.csv", "include/end-of-life.csv", - "include/release-cycle.svg", "include/release-cycle-all.svg" + "_static/release-cycle.svg", "_static/release-cycle-all.svg" ) foreach ($item in $ToClean) { if (Test-Path -Path $item) { diff --git a/versions.rst b/versions.rst index d0f837991..3d5fdced9 100644 --- a/versions.rst +++ b/versions.rst @@ -11,7 +11,7 @@ version can be found on the `download page `_ .. raw:: html - :file: include/release-cycle.svg + :file: _static/release-cycle.svg (See :ref:`below ` for a chart with older versions. Another useful visualization is `endoflife.date/python `__.) @@ -36,7 +36,7 @@ Unsupported versions .. csv-table:: :header-rows: 1 :width: 100% - :file: include/end-of-life.csv + :file: _static/end-of-life.csv .. _full-chart: @@ -45,7 +45,7 @@ Full chart ========== .. raw:: html - :file: include/release-cycle-all.svg + :file: _static/release-cycle-all.svg Status key From 521dacefce4e4cad0c42704e4dc07f48e6f02a35 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Tue, 30 Dec 2025 16:45:01 +0200 Subject: [PATCH 12/48] Fix paths in Makefile (#1719) --- Makefile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Makefile b/Makefile index 2f8e08614..a26ad48e0 100644 --- a/Makefile +++ b/Makefile @@ -112,9 +112,9 @@ include/branches.csv: # Other files are generated together with branches.csv include/end-of-life.csv: include/branches.csv @: -include/release-cycle-all.svg: include/branches.csv +_static/release-cycle-all.svg: include/branches.csv @: -include/release-cycle.svg: include/branches.csv +_static/release-cycle.svg: include/branches.csv @: # Catch-all target: route all unknown targets to Sphinx using the new From 5d02e79675aeaf80fbf821a8d4af9d1977958a9b Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Thu, 1 Jan 2026 12:48:21 +0200 Subject: [PATCH 13/48] Revert "Pin to Sphinx 8.2.3 (#1716)" (#1717) --- requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/requirements.txt b/requirements.txt index 359d28268..7c2bbd806 100644 --- a/requirements.txt +++ b/requirements.txt @@ -7,4 +7,4 @@ sphinx-notfound-page>=1.0.0 sphinx_copybutton>=0.3.3 sphinxext-opengraph>=0.13.0 sphinxext-rediraffe -Sphinx~=8.2.3 +Sphinx>=8.2.3 From f657b399c31fef3682249e65835772bee1ae2a4b Mon Sep 17 00:00:00 2001 From: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> Date: Tue, 6 Jan 2026 17:05:22 +0000 Subject: [PATCH 14/48] Add section on terminology to avoid to style guide (#1715) Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> --- documentation/style-guide.rst | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/documentation/style-guide.rst b/documentation/style-guide.rst index d90a14ce9..d263fb8f1 100644 --- a/documentation/style-guide.rst +++ b/documentation/style-guide.rst @@ -116,6 +116,24 @@ 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 + + .. index:: diataxis .. _diataxis: From d5ca1b4aea6281aa66ce4b25b9889e6f89c0d2fe Mon Sep 17 00:00:00 2001 From: Rafael Weingartner-Ortner <38643099+RafaelWO@users.noreply.github.com> Date: Sun, 25 Jan 2026 14:52:04 +0100 Subject: [PATCH 15/48] Merge macOS "Python 3.13+" and "Python 3.11-3.12" tabs (#1726) --- getting-started/setup-building.rst | 13 ++----------- 1 file changed, 2 insertions(+), 11 deletions(-) diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index df208f28c..110d718e9 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -858,18 +858,9 @@ some of CPython's modules (for example, ``zlib``). $ brew install pkg-config openssl@3 xz gdbm tcl-tk mpdecimal zstd - .. tab:: Python 3.13+ - - For Python 3.13 and newer:: + .. tab:: Python 3.11+ - $ GDBM_CFLAGS="-I$(brew --prefix gdbm)/include" \ - GDBM_LIBS="-L$(brew --prefix gdbm)/lib -lgdbm" \ - ./configure --with-pydebug \ - --with-openssl="$(brew --prefix openssl@3)" - - .. tab:: Python 3.11-3.12 - - For Python 3.11 and 3.12:: + For Python 3.11 and newer:: $ GDBM_CFLAGS="-I$(brew --prefix gdbm)/include" \ GDBM_LIBS="-L$(brew --prefix gdbm)/lib -lgdbm" \ From b3bbf54d8091637a301c6958f8214c2d96f7e999 Mon Sep 17 00:00:00 2001 From: Seth Michael Larson Date: Fri, 6 Feb 2026 13:31:12 -0600 Subject: [PATCH 16/48] Publish the list of PSRT members (#1729) Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Co-authored-by: Savannah Ostrowski --- .github/CODEOWNERS | 2 + developer-workflow/psrt.csv | 21 ++++++++++ developer-workflow/psrt.rst | 76 +++++++++++++++++++++++++++++++++++++ 3 files changed, 99 insertions(+) create mode 100644 developer-workflow/psrt.csv diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 668bb5ace..7f1f223e3 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -4,5 +4,7 @@ # It uses the same pattern rule for gitignore file # https://git-scm.com/docs/gitignore#_pattern_format +# PSRT member list owned by PSRT admins. +developer-workflow/psrt.csv @warsaw @ewdurbin @ned-deily @sethmlarson garbage_collector.rst @pablogsal diff --git a/developer-workflow/psrt.csv b/developer-workflow/psrt.csv new file mode 100644 index 000000000..d5ee7d954 --- /dev/null +++ b/developer-workflow/psrt.csv @@ -0,0 +1,21 @@ +Barry Warsaw,warsaw,Admin +Benjamin Peterson,benjaminp, +Donald Stufft,dstufft, +Dustin Ingram,di, +Ee Durbin,ewdurbin,Admin +Glyph Lefkowitz,glyph, +Gregory P. Smith,gpshead, +Hugo van Kemenade,hugovk,Release Manager +Jacob Coffee,JacobCoffee, +Larry Hastings,larryhastings, +Łukasz Langa,ambv,Release Manager +Ned Deily,ned-deily,"Admin, Release Manager" +Pablo Galindo Salgado,pablogsal,Release Manager +Paul McMillan,paulmcmillan, +Pradyun Gedam,pradyunsg, +Savannah Ostrowski,savannahostrowski,Release Manager +Serhiy Storchaka,serhiy-storchaka, +Seth Larson,sethmlarson,Admin +Steve Dower,zooba,Release Manager +Thomas Wouters,Yhg1s,Release Manager +Tim Peters,tim-one, diff --git a/developer-workflow/psrt.rst b/developer-workflow/psrt.rst index cf5acd2b7..543e09358 100644 --- a/developer-workflow/psrt.rst +++ b/developer-workflow/psrt.rst @@ -4,6 +4,82 @@ Python Security Response Team (PSRT) The Python Security Response Team (PSRT) is responsible for handling vulnerability reports for CPython and pip. +Members +------- + +The PSRT publishes a full +list of members and admins, included in the table below: + +.. csv-table:: + :header: "Name", "GitHub username", "Notes" + :file: psrt.csv + :encoding: "utf-8" + +How can I join the PSRT? +~~~~~~~~~~~~~~~~~~~~~~~~ + +Anyone can join the PSRT following a nomination process +`similar to core team nominations`_. Nomination for a new member +is brought to the PSRT by an existing PSRT member and then +this nomination is voted on by existing PSRT members. +The nomination succeeds if the nomination receives at least +two-thirds positive votes from a vote of existing PSRT members +that is open for one week and not vetoed by the Steering Council. + +Once per year the Steering Council will receive a report of inactive members +of the PSRT with the recommendation to remove the inactive users from the PSRT. +“Inactive” is defined as a member who hasn’t coordinated or commented on a +vulnerability report in the past year since the last report was generated. +The Steering Council may remove members of the PSRT with a simple vote. + +Members of the PSRT who are a Release Manager or Steering Council member may +remain in the PSRT regardless of inactivity in vulnerability reports. + +.. _similar to core team nominations: https://devguide.python.org/core-team/join-team/ + +Responsibilities of PSRT members +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Below are the responsibilities of PSRT members: + +* Being knowledgeable about typical software vulnerability report handling + processes, such as CVE IDs, patches, coordinated disclosure, embargoes. +* Not sharing or acting on embargoed information about the reported + vulnerability. Examples of disallowed behavior include sharing information + with colleagues or publicly deploying unpublished mitigations or patches ahead + of the advisory publication date. +* Acting as a “Coordinator” of vulnerability reports that are submitted to + projects. A Coordinator’s responsibility is to move a report through the PSRT + process to a “finished” state, either rejected or as a published advisory and + mitigation, within the industry standard timeline of 90 days. +* As a Coordinator, involving relevant core team members or triagers where + necessary to make a determination whether a report is a vulnerability and + developing a patch. Coordinators are encouraged to involve members of the core + team to make the best decision for each report rather than working in isolation. +* As a Coordinator, calculating the severity using CVSS and authoring advisories + to be shared on `security-announce@python.org`_. These advisories are used for + CVE records by the `PSF CVE Numbering Authority`_. +* Coordinators that can no longer move a report forwards for any reason must + delegate their Coordinator role to someone else in the PSRT. + +.. _security-announce@python.org: https://mail.python.org/archives/list/security-announce@python.org/ +.. _PSF CVE Numbering Authority: https://www.python.org/cve-numbering-authority/ + +Responsibilities of PSRT admins +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +PSRT members who are designated as admins by the Steering Council have the +following additional responsibilities: + +* Triaging the ``security@python.org`` mailing list. +* Managing PSRT membership access including the GitHub team, the mailing list, + and Discord channel, to ensure they are synchronized with the canonical list + of PSRT members. +* On a yearly basis, providing the Steering Council with a report including a + list of inactive PSRT members. +* Running nomination elections, including counting final votes and giving + the Steering Council an opportunity to veto nominations via email. + Vulnerability report triage --------------------------- From caeafb2b5e921ccc7184c9dfa528d5998db19e68 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> Date: Thu, 12 Feb 2026 10:43:27 +0000 Subject: [PATCH 17/48] Restructure the "new buildbot worker" guide (GH-1732) Co-authored-by: Victor Stinner Co-authored-by: Zachary Ware Co-authored-by: Petr Viktorin --- testing/new-buildbot-worker.rst | 362 +++++++++++++++++--------------- 1 file changed, 191 insertions(+), 171 deletions(-) diff --git a/testing/new-buildbot-worker.rst b/testing/new-buildbot-worker.rst index a0fbf9681..8c3f99acb 100644 --- a/testing/new-buildbot-worker.rst +++ b/testing/new-buildbot-worker.rst @@ -25,7 +25,7 @@ mailing list. This mailing list is also the place to contact if you want to contribute a buildbot but have questions. As for what kind of buildbot to run...take a look at our `current fleet -`__. Pretty much anything that isn't +`__. Pretty much anything that isn't on that list would be interesting: different Linux/Unix distributions, different versions of the various OSes, other OSes if you or someone are prepared to make the test suite actually pass on that new OS. Even if you only @@ -40,14 +40,14 @@ Preparing for buildbot worker setup Since the goal is to build Python from source, the system will need to have everything required to do normal python development: a compiler, a linker, and -(except on windows) the "development" headers for any of the optional modules -(zlib, OpenSSL, etc) supported by the platform. Follow the steps outlined in +(except on Windows) the "development" headers for any of the optional modules +(zlib, OpenSSL, and so on) supported by the platform. Follow the steps outlined in :ref:`setup` for the target platform, all the way through to having a working -compiled python. +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 `__ +`configuration repository `__ to discuss adding your worker and to obtain the needed workername and password. You can do some of the steps that follow before having the credentials, but it is easiest to have them before @@ -68,52 +68,70 @@ here; it doesn't differ from setting up a virtual environment for any other software, but you'll need to modify the sequence of steps below as appropriate if you choose that path. -For Linux: +.. tab:: Linux -* If your package manager provides the buildbot worker software, that is - probably the best way to install it; it may create the buildbot user for - you, in which case you can skip the next step. Otherwise, do ``pip install - buildbot-worker`` or ``pip3 install buildbot-worker``. -* Create a ``buildbot`` user (using, eg: ``useradd``) if necessary. -* Log in as the buildbot user. + * If your package manager provides the buildbot worker software, that is + probably the best way to install it; it may create the buildbot user for + you, in which case you can skip the next step. Otherwise, do ``pip install + buildbot-worker`` or ``pip3 install buildbot-worker``. + * Create a ``buildbot`` user (using, eg: ``useradd``) if necessary. + * Log in as the buildbot user. -For Mac: + In a terminal window for the buildbot user, issue the following commands (you + can put the ``buildarea`` wherever you want to):: -* Create a buildbot user using the OS/X control panel user admin. It - should be a "standard" user. -* Log in as the buildbot user. -* Install the buildbot worker [#]_ by running ``pip install buildbot-worker``. + mkdir buildarea + buildbot-worker create-worker buildarea buildbot-api.python.org:9020 workername workerpasswd -For Windows: -* Create a buildbot user as a "standard" user. -* Install the latest version of Python from python.org. -* Open a Command Prompt. -* Execute ``python -m pip install pypiwin32 buildbot-worker`` (note that - ``python.exe`` is not added to ``PATH`` by default, making the - ``python`` command accessible is left as an exercise for the user). +.. tab:: macOS -In a terminal window for the buildbot user, issue the following commands (you -can put the ``buildarea`` wherever you want to):: + * Create a buildbot user using the macOS control panel user admin. It + should be a "standard" user. + * Log in as the buildbot user. + * Install the buildbot worker [#]_ by running ``pip install buildbot-worker``. - mkdir buildarea - buildbot-worker create-worker buildarea buildbot-api.python.org:9020 workername workerpasswd + In a terminal window for the buildbot user, issue the following commands (you + can put the ``buildarea`` wherever you want to):: -(Note that on Windows, the ``buildbot-worker`` command will be in the -:file:`Scripts` directory of your Python installation.) + mkdir buildarea + buildbot-worker create-worker buildarea buildbot-api.python.org:9020 workername workerpasswd -On Windows, `the maximum length for a path is limited -`__. -This might cause some tests to fail, unless long paths support is enabled. -Use this PowerShell command to check whether long paths are enabled:: +.. tab:: Windows + + * Create a buildbot user as a "standard" user. + * Install the latest version of Python from python.org. + * Open a Command Prompt. + * Execute ``python -m pip install pywin32 buildbot-worker`` (note that + ``python.exe`` is not added to ``PATH`` by default, making the + ``python`` command accessible is left as an exercise for the user). + + On Windows, `the maximum length for a path is limited + `__. + This might cause some tests to fail, unless long paths support is enabled. + + Use this PowerShell command to check whether long paths are enabled:: Get-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -If the value is not "1", you can enable long paths using this PowerShell command:: + If the value is not "1", you can enable long paths using this PowerShell command:: New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force + + In a terminal window for the buildbot user, issue the following commands. + (You can put the ``buildarea`` wherever you want to.) + Note that the ``buildbot-worker`` command will be in the + :file:`Scripts` directory of your Python installation. Here and in the rest + of the guide, you may need to launch it using the full path. + + .. code-block:: + + mkdir buildarea + buildbot-worker create-worker buildarea buildbot-api.python.org:9020 workername workerpasswd + + Once this initial worker setup completes, you should edit the files ``buildarea/info/admin`` and ``buildarea/info/host`` to provide your contact info and information on the host configuration, respectively. This information @@ -123,138 +141,138 @@ builders running on your worker. You will also want to make sure that the worker is started when the machine reboots: -For Linux: +.. tab:: Linux -* For systemd based distributions, you can create a systemd unit file in order - to manage the service. Create the unit file named ``buildbot-worker.service`` - under ``/home/buildbot/.config/systemd/user/`` and change the paths according to where the - buildbot-worker binary resides. You can verify its location by running - ``which buildbot-worker``. - If you installed the buildbot-worker through - your package manager it would be:: - - [Unit] - Description=Buildbot Worker - Wants=network-online.target - After=network-online.target local-fs.target - - [Service] - Type=forking - PIDFile=/home/buildbot/buildarea/twistd.pid - WorkingDirectory=/home/buildbot/buildarea - ExecStart=/usr/bin/buildbot-worker start - ExecReload=/usr/bin/buildbot-worker restart - ExecStop=/usr/bin/buildbot-worker stop - Restart=always - User=buildbot - - [Install] - WantedBy=multi-user.target - - - If you installed the buildbot-worker through pip, the systemd unit - file should look like this:: - - [Unit] - Description=Buildbot Worker - Wants=network-online.target - After=network-online.target local-fs.target - - [Service] - Type=forking - PIDFile=/home/buildbot/buildarea/twistd.pid - WorkingDirectory=/home/buildbot/buildarea - ExecStart=/usr/local/bin/buildbot-worker start - ExecReload=/usr/local/bin/buildbot-worker restart - ExecStop=/usr/local/bin/buildbot-worker stop - Restart=always - User=buildbot - - [Install] - WantedBy=multi-user.target - - - Then enable lingering for the buildbot user via the - ``loginctl enable-linger buildbot`` command and you can start - the service through a login shell of the buildbot user - via the ``systemctl --user enable --now buildbot-worker.service`` - command. - - Note that using a systemd unit file, might produce some selinux warnings on systems - where the enforcing mode is enabled, usually related to the twistd.pid file. - If the service fails to start, you should check the output of - ``systemctl status buildbot-worker.service`` as well as the - ``/var/log/audit/audit.log`` file (e.g. through - ``sealert -a /var/log/audit/audit.log``) for potential issues and remedies. - - -* Alternatively you can create a cronjob. Add the following line to ``/etc/crontab``:: - - @reboot buildbot-worker restart /path/to/buildarea - - Note that we use ``restart`` rather than ``start`` in case a crash has - left a ``twistd.pid`` file behind. - -For OSX: - -* Create a bin directory for your buildbot user:: - - mkdir bin - -* Place the following script, named ``run_worker.sh``, into that directory:: - - #!/bin/bash - export PATH=/usr/local/bin:/Library/Frameworks/Python.framework/Versions/2.7/bin:$PATH - export LC_CTYPE=en_US.utf-8 - cd /Users/buildbot/buildarea - twistd --nodaemon --python=buildbot.tac --logfile=buildbot.log --prefix=worker - - If you use pip with Apple's system python, add '/System' to the front of - the path to the Python bin directory. - -* Place a file with the following contents into ``/Library/LaunchDaemons``: - - .. code-block:: xml - - - - - - Label - net.buildbot.worker - UserName - buildbot - WorkingDirectory - /Users/buildbot/buildarea - ProgramArguments - - /Users/buildbot/bin/run_worker.sh - - StandardOutPath - twistd.log - StandardErrorPath - twistd.log - KeepAlive - - SessionCreate - - - - - The recommended name for the file is ``net.buildbot.worker``. - -For Windows: + * For systemd based distributions, you can create a systemd unit file in order + to manage the service. Create the unit file named ``buildbot-worker.service`` + under ``/home/buildbot/.config/systemd/user/`` and change the paths according to where the + buildbot-worker binary resides. You can verify its location by running + ``which buildbot-worker``. + If you installed the buildbot-worker through + your package manager it would be:: + + [Unit] + Description=Buildbot Worker + Wants=network-online.target + After=network-online.target local-fs.target + + [Service] + Type=forking + PIDFile=/home/buildbot/buildarea/twistd.pid + WorkingDirectory=/home/buildbot/buildarea + ExecStart=/usr/bin/buildbot-worker start + ExecReload=/usr/bin/buildbot-worker restart + ExecStop=/usr/bin/buildbot-worker stop + Restart=always + User=buildbot + + [Install] + WantedBy=multi-user.target + + + If you installed the buildbot-worker through pip, the systemd unit + file should look like this:: + + [Unit] + Description=Buildbot Worker + Wants=network-online.target + After=network-online.target local-fs.target + + [Service] + Type=forking + PIDFile=/home/buildbot/buildarea/twistd.pid + WorkingDirectory=/home/buildbot/buildarea + ExecStart=/usr/local/bin/buildbot-worker start + ExecReload=/usr/local/bin/buildbot-worker restart + ExecStop=/usr/local/bin/buildbot-worker stop + Restart=always + User=buildbot + + [Install] + WantedBy=multi-user.target + + + Then enable lingering for the buildbot user via the + ``loginctl enable-linger buildbot`` command and you can start + the service through a login shell of the buildbot user + via the ``systemctl --user enable --now buildbot-worker.service`` + command. + + Note that using a systemd unit file, might produce some SELinux warnings on systems + where the enforcing mode is enabled, usually related to the ``twistd.pid`` file. + If the service fails to start, you should check the output of + ``systemctl status buildbot-worker.service`` as well as the + ``/var/log/audit/audit.log`` file (for example, through + ``sealert -a /var/log/audit/audit.log``) for potential issues and remedies. + + * Alternatively you can create a cronjob. Add the following line to ``/etc/crontab``:: + + @reboot buildbot-worker restart /path/to/buildarea + + Note that we use ``restart`` rather than ``start`` in case a crash has + left a ``twistd.pid`` file behind. + + +.. tab:: macOS + + * Create a bin directory for your buildbot user:: + + mkdir bin + + * Place the following script, named ``run_worker.sh``, into that directory:: + + #!/bin/bash + export PATH=/usr/local/bin:/Library/Frameworks/Python.framework/Versions/2.7/bin:$PATH + export LC_CTYPE=en_US.utf-8 + cd /Users/buildbot/buildarea + twistd --nodaemon --python=buildbot.tac --logfile=buildbot.log --prefix=worker + + If you use pip with Apple's system python, add '/System' to the front of + the path to the Python bin directory. + + * Place a file with the following contents into ``/Library/LaunchDaemons``: + + .. code-block:: xml + + + + + + Label + net.buildbot.worker + UserName + buildbot + WorkingDirectory + /Users/buildbot/buildarea + ProgramArguments + + /Users/buildbot/bin/run_worker.sh + + StandardOutPath + twistd.log + StandardErrorPath + twistd.log + KeepAlive + + SessionCreate + + + + + The recommended name for the file is ``net.buildbot.worker``. + +.. tab:: Windows -* Add a Scheduled Task to run ``buildbot-worker start buildarea`` as the - buildbot user "when the computer starts up". It is best to provide - absolute paths to the ``buildbot-worker`` command and the :file:`buildarea` - directory. It is also recommended to set the task to run in the - directory that contains the :file:`buildarea` directory. - -* Alternatively (note: don't do both!), set up the worker - service as described in the `buildbot documentation - `__. + * Add a Scheduled Task to run ``buildbot-worker start buildarea`` as the + buildbot user "when the computer starts up". It is best to provide + absolute paths to the ``buildbot-worker`` command and the :file:`buildarea` + directory. It is also recommended to set the task to run in the + directory that contains the :file:`buildarea` directory. + + * Alternatively (note: don't do both!), set up the worker + service as described in the `buildbot documentation + `__. To start the worker running for your initial testing, you can do:: @@ -262,7 +280,7 @@ To start the worker running for your initial testing, you can do:: Then you can either wait for someone to make a commit, or you can pick a builder associated with your worker from the `list of builders -`__ and force a build. +`__ and force a build. In any case you should initially monitor builds on your builders to make sure the tests are passing and to resolve any platform issues that may be revealed @@ -375,7 +393,7 @@ Port Host Description 53 your DNS server test_socket, and others implicitly 80 python.org (several tests) example.com -119 news.gmane.org test_nntplib +119 news.gmane.org test_nntplib (Python versions < 3.13) 443 (various) test_ssl 465 smtp.gmail.com test_smtpnet 587 smtp.gmail.com test_smtpnet @@ -398,9 +416,9 @@ buildbot are at least: * 512 MB RAM * 30 GB free disk space -The bigmem tests won't run in this configuration, since they require +Many tests won't run in this configuration, since they require substantially more memory, but these resources should be sufficient to ensure -that Python compiles correctly on the platform and can run the rest of the test +that Python compiles correctly on the platform and can run part of the test suite. @@ -413,7 +431,7 @@ This means that the code your buildbot will run will have been vetted by a commi However, mistakes and bugs happen, as could a compromise, so keep this in mind when siting your buildbot on your network and establishing the security around it. Treat the buildbot like you would any resource that is public facing and might -get hacked (use a VM and/or jail/chroot/solaris zone, put it in a DMZ, etc). +get hacked (use a VM and/or jail/chroot/solaris zone, put it in a DMZ, and so on). While the buildbot does not have any ports open for inbound traffic (and is not public facing in that sense), committer mistakes do happen, and security flaws are discovered in both released and unreleased code, so treating the buildbot @@ -422,7 +440,7 @@ as if it were fully public facing is a good policy. Code runs differently as privileged and unprivileged users. We would love to have builders running as privileged accounts, but security considerations do make that difficult, as access to root can provide access to surprising -resources (such as spoofed IP packets, changes in MAC addresses, etc) even on a +resources (such as spoofed IP packets, changes in MAC addresses, and so on) even on a VM setup. But if you are confident in your setup, we'd love to have a buildbot that runs python as root. @@ -435,3 +453,5 @@ useful as a point of reference. .. [#] If the buildbot is going to do Framework builds, it is better to use the Apple-shipped Python so as to avoid any chance of the buildbot picking up components from the installed python.org python. + +.. _builders: https://buildbot.python.org/#/builders From 08b6ec803175bb7ef03d8900843de5f58e587e91 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bartosz=20S=C5=82awecki?= Date: Fri, 13 Feb 2026 17:00:46 +0100 Subject: [PATCH 18/48] Remove `Misc/ACKS` from `patchcheck` description (GH-1733) Follow-up to python/cpython#141960 --- getting-started/pull-request-lifecycle.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/getting-started/pull-request-lifecycle.rst b/getting-started/pull-request-lifecycle.rst index d1f7e26a5..d23e16695 100644 --- a/getting-started/pull-request-lifecycle.rst +++ b/getting-started/pull-request-lifecycle.rst @@ -285,7 +285,6 @@ The automated checklist runs through: * Has an entry under ``Misc/NEWS.d/next`` been added? (using `blurb-it `__, or the :pypi:`blurb` tool) -* Has ``Misc/ACKS`` been updated? * Has ``configure`` been regenerated, if necessary? * Has ``pyconfig.h.in`` been regenerated, if necessary? From 8298b155a59f812741d99dc68c9d929c42ddd914 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> Date: Sun, 15 Feb 2026 23:10:28 +0000 Subject: [PATCH 19/48] Remove unused rule in CODEOWNERS (#1730) --- .github/CODEOWNERS | 2 -- 1 file changed, 2 deletions(-) diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 7f1f223e3..eba83ca39 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -6,5 +6,3 @@ # PSRT member list owned by PSRT admins. developer-workflow/psrt.csv @warsaw @ewdurbin @ned-deily @sethmlarson - -garbage_collector.rst @pablogsal From aff5b972f83e8e510b63bd4f87e332e2cc6bf2a3 Mon Sep 17 00:00:00 2001 From: Itamar Oren Date: Mon, 16 Feb 2026 13:53:18 -0800 Subject: [PATCH 20/48] Add Itamar Oren to core-team (#1734) --- 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 8c4625493..48234eff4 100644 --- a/core-team/core-team.csv +++ b/core-team/core-team.csv @@ -1,3 +1,4 @@ +Itamar Oren,itamaro,2026-02-16,, Emma Smith,emmatyping,2025-07-31,, Tomas Roun,tomasr8,2025-06-16,, Peter Bierma,ZeroIntensity,2025-06-16,, From a112f9b252c66cf49adaf57297056006082dfd6d Mon Sep 17 00:00:00 2001 From: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> Date: Wed, 18 Feb 2026 08:07:29 +0000 Subject: [PATCH 21/48] Removed `edelsohn` as AIX expert (GH-1737) --- core-team/experts.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/core-team/experts.rst b/core-team/experts.rst index 01935106b..ea807c42b 100644 --- a/core-team/experts.rst +++ b/core-team/experts.rst @@ -282,7 +282,7 @@ for “their” platform as a third-party project. =================== =========== Platform Maintainers =================== =========== -AIX edelsohn, ayappanec +AIX ayappanec Android mhsmith Cygwin jlt63^, stutzbach^ Emscripten hoodmane, pmp-p, rdb, rth, ryanking13 From a1740a10322edf4018f61c7b77f39f768a4cf238 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> Date: Thu, 19 Feb 2026 14:39:46 +0000 Subject: [PATCH 22/48] Update `buildbot.rst` doc (#1738) Co-authored-by: Victor Stinner Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> --- testing/buildbots.rst | 141 +++++++++++++++++++++--------------------- 1 file changed, 72 insertions(+), 69 deletions(-) diff --git a/testing/buildbots.rst b/testing/buildbots.rst index 1e711ab6b..fc420d3f7 100644 --- a/testing/buildbots.rst +++ b/testing/buildbots.rst @@ -11,35 +11,38 @@ branches `, Python has a set of dedicated machines (called *buildbots* or *build workers*) used for continuous integration. They span a number of hardware/operating system combinations. Furthermore, each machine hosts several *builders*, one per active branch: when a new change is pushed -to this branch on the public `GitHub repository `__, all corresponding builders -will schedule a new build to be run as soon as possible. +to this branch on the public `GitHub repository `__, +all corresponding builders will schedule a new build to be run as soon as possible. -The build steps run by the buildbots are the following: +The build steps run by the buildbots are: * Check out the source tree for the change which triggered the build * Compile Python * Run the test suite using :ref:`strenuous settings ` * Clean up the build tree -It is your responsibility, as a core developer, to check the automatic -build results after you push a change to the repository. It is therefore -important that you get acquainted with the way these results are presented, +It is the responsibility of core team members to check the automatic +build results after they push a change to the repository. It is therefore +important that they are acquainted with the way these results are presented, and how various kinds of failures can be explained and diagnosed. + In case of trouble ================== Please read this page in full. If your questions aren't answered here and you need assistance with the buildbots, a good way to get help is to either: -* contact the ``python-buildbots@python.org`` mailing list where all buildbot - worker owners are subscribed; or +* contact the `python-buildbots@python.org + `__ + mailing list where all buildbot worker owners are subscribed; or * contact the release manager of the branch you have issues with. + Buildbot failures on pull requests ================================== -The ``bedevere-bot`` on GitHub will put a message on your merged Pull Request +The Bedevere bot on GitHub will put a message on your merged pull request if building your commit on a stable buildbot worker fails. Take care to evaluate the failure, even if it looks unrelated at first glance. @@ -48,6 +51,7 @@ after each commit. In particular, reference leaks builds take several hours to complete so they are done periodically. This is why it's important for you to be able to check the results yourself, too. + Triggering on pull requests =========================== @@ -63,19 +67,19 @@ buildbots again on a later commit, you'll have to remove the label and add it again. If you want to test a pull request against specific platforms, you can trigger -one or more build bots by posting a comment that begins with: +one or more buildbots by posting a comment that begins with: .. code-block:: none !buildbot regex-matching-target -For example to run both the iOS and Android build bot, you can use: +For example to run both the iOS and Android buildbots, you can use: .. code-block:: none !buildbot ios|android -bedevere-bot will post a comment indicating which build bots, if +Bedevere will post a comment indicating which buildbots, if any, were matched. If none were matched, or you do not have the necessary permissions to trigger a request, it will tell you that too. @@ -83,38 +87,30 @@ The ``!buildbot`` comment will also only run buildbots on the most recent commit. To trigger the buildbots again on a later commit, you will have to repeat the comment. + Checking results of automatic builds ==================================== -There are three ways of visualizing recent build results: +The Web interface at https://buildbot.python.org/#/ has several ways of +visualizing recent build results: -* The Web interface for each branch at https://www.python.org/dev/buildbot/, - where the so-called "waterfall" view presents a vertical rundown of recent - builds for each builder. When interested in one build, you'll have to - click on it to know which commits it corresponds to. Note that - the buildbot web pages are often slow to load, be patient. +* A `release status dashboard `__ + that shows the status of buildbots for each active branch, + summarizing whether the builds are ready for release. -* The command-line ``bbreport.py`` client, which you can get from - https://code.google.com/archive/p/bbreport. Installing it is trivial: just add - the directory containing ``bbreport.py`` to your system path so that - you can run it from any filesystem location. For example, if you want - to display the latest build results on the development ("main") branch, - type:: +* A `waterfall view `__ + that presents a vertical rundown of recent builds for each builder. + When interested in one build, click on it for more detail such as logs and + which commits it corresponds to. - bbreport.py -q 3.x - -* The buildbot "console" interface at https://buildbot.python.org/all/ - This works best on a wide, high resolution +* A `console view `__, + which works best on a wide, high resolution monitor. Clicking on the colored circles will allow you to open a new page containing whatever information about that particular build is of interest to you. You can also access builder information by clicking on the builder status bubbles in the top line. -If you like IRC, having an IRC client open to the #python-dev-notifs channel on -irc.libera.chat is useful. Any time a builder changes state (last build -passed and this one didn't, or vice versa), a message is posted to the channel. -Keeping an eye on the channel after pushing a commits is a simple way to get -notified that there is something you should look in to. +Note that the buildbot web pages are often slow to load, be patient. Some buildbots are much faster than others. Over time, you will learn which ones produce the quickest results after a build, and which ones take the @@ -124,20 +120,24 @@ Also, when several commits are pushed in a quick succession in the same branch, it often happens that a single build is scheduled for all these commits. + Stability ========= -A subset of the buildbots are marked "stable". They are taken into account -when making a new release. The rule is that all stable builders must be free of -persistent failures when the release is cut. It is absolutely **vital** -that core developers fix any issue they introduce on the stable buildbots, -as soon as possible. +A subset of the buildbots are marked as +`"stable" `__. +They are taken into account when making a new release. +The rule is that all tier 1 and 2 stable builders must be free of +persistent failures when the release is cut (see :pep:`11` for more information). +It is absolutely **vital** that core team members fix or revert any issue they +introduce on the stable buildbots, as soon as possible. This does not mean that other builders' test results can be taken lightly, either. Some of them are known for having platform-specific issues that prevent some tests from succeeding (or even terminating at all), but introducing additional failures should generally not be an option. + Flags-dependent failures ======================== @@ -148,11 +148,8 @@ or to Python itself. To reproduce, make sure you use the same flags as the buildbots: they can be found out simply by clicking the **stdio** link for the failing build's tests. For example:: - ./python.exe -Wd -E -bb ./Lib/test/regrtest.py -uall -rwW + ./python -E -m test --slow-ci --timeout=1200 -j2 --junit-xml test-results.xml -j10 -.. note:: - Running ``Lib/test/regrtest.py`` is exactly equivalent to running - ``-m test``. Ordering-dependent failures =========================== @@ -170,31 +167,37 @@ run, and check the beginning of the test output proper. Let's assume, for the sake of example, that the output starts with: .. code-block:: none - :emphasize-lines: 6 + :emphasize-lines: 9 - ./python -Wd -E -bb Lib/test/regrtest.py -uall -rwW - == CPython 3.3a0 (default:22ae2b002865, Mar 30 2011, 13:58:40) [GCC 4.4.5] - == Linux-2.6.36-gentoo-r5-x86_64-AMD_Athlon-tm-_64_X2_Dual_Core_Processor_4400+-with-gentoo-1.12.14 little-endian - == /home/buildbot/buildarea/3.x.ochtman-gentoo-amd64/build/build/test_python_29628 - Testing with flags: sys.flags(debug=0, inspect=0, interactive=0, optimize=0, dont_write_bytecode=0, no_user_site=0, no_site=0, ignore_environment=1, verbose=0, bytes_warning=2, quiet=0) - Using random seed 2613169 - [ 1/353] test_augassign - [ 2/353] test_functools + ./python -E -m test --slow-ci --timeout=2400 -j2 -u-cpu,-urlfetch,-network --junit-xml test-results.xml -j4 + == CPython 3.15.0a6+ (heads/main:d625f7da33b, Feb 13 2026, 17:27:29) [GCC 12.2.0] + == Linux-6.12.20+rpt-rpi-v8-aarch64-with-glibc2.36 little-endian + == Python build: release + == cwd: /home/stan/buildarea/3.x.stan-raspbian.nondebug/build/build/test_python_worker_181905æ + == CPU count: 4 + == encodings: locale=ISO-8859-1 FS=utf-8 + == resources: all,-cpu,-network,-urlfetch + Using random seed: 1000348774 + 0:00:00 load avg: 3.34 Run 500 tests in parallel using 4 worker processes (timeout: 40 min, worker timeout: 45 min) + 0:00:01 load avg: 3.34 [ 1/500] test_colorsys passed + 0:00:01 load avg: 3.34 [ 2/500] test_float passed -You can reproduce the exact same order using:: +You can reproduce the exact same order by adding the ``--randseed 1000348774`` option:: - ./python -Wd -E -bb -m test -uall -rwW --randseed 2613169 + ./python -E -m test --slow-ci --timeout=2400 -j2 -u-cpu,-urlfetch,-network --junit-xml test-results.xml -j4 --randseed 1000348774 It will run the following sequence (trimmed for brevity): .. code-block:: none - [ 1/353] test_augassign - [ 2/353] test_functools - [ 3/353] test_bool - [ 4/353] test_contains - [ 5/353] test_compileall - [ 6/353] test_unicode + [ 1/500] test_colorsys + [ 2/500] test_float + [ 3/500] test.test_io.test_memoryio + [ 4/500] test_profile + [ 5/500] test_picklebuffer + [ 6/500] test_zipimport + [ 7/500] test_devpoll + ... If this is enough to reproduce the failure on your setup, you can then bisect the test sequence to look for the specific interference causing the @@ -202,26 +205,26 @@ failure. Copy and paste the test sequence in a text file, then use the ``--fromfile`` (or ``-f``) option of the test runner to run the exact sequence recorded in that text file:: - ./python -Wd -E -bb -m test -uall -rwW --fromfile mytestsequence.txt + ./python -E -m test --slow-ci --timeout=2400 -j2 -u-cpu,-urlfetch,-network --junit-xml test-results.xml -j4 --fromfile mytestsequence.txt -In the example sequence above, if ``test_unicode`` had failed, you would +In the example sequence above, if ``test_zipimport`` had failed, you would first test the following sequence: .. code-block:: none - [ 1/353] test_augassign - [ 2/353] test_functools - [ 3/353] test_bool - [ 6/353] test_unicode + [ 1/500] test_colorsys + [ 2/500] test_float + [ 3/500] test.test_io.test_memoryio + [ 6/500] test_zipimport And, if it succeeds, the following one instead (which, hopefully, shall fail): .. code-block:: none - [ 4/353] test_contains - [ 5/353] test_compileall - [ 6/353] test_unicode + [ 4/500] test_profile + [ 5/500] test_picklebuffer + [ 6/500] test_zipimport Then, recursively, narrow down the search until you get a single pair of tests which triggers the failure. It is very rare that such an interference @@ -243,7 +246,7 @@ not reach a perfect level of reproducibility. Some of them will sometimes display spurious failures, depending on various conditions. Here are common offenders: -* Network-related tests, such as ``test_poplib``, ``test_urllibnet``, etc. +* Network-related tests, such as ``test_poplib``, ``test_urllibnet``, and so on. Their failures can stem from adverse network conditions, or imperfect thread synchronization in the test code, which often has to run a server in a separate thread. From 2eae7233ec75545be9dfaa4b4761ed78621fc8b8 Mon Sep 17 00:00:00 2001 From: Ned Batchelder Date: Thu, 19 Feb 2026 10:19:40 -0500 Subject: [PATCH 23/48] Clarify what authorship attribution means (#1740) See https://github.com/python/docs-community/issues/180 Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> --- documentation/style-guide.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/documentation/style-guide.rst b/documentation/style-guide.rst index d263fb8f1..4d2ca0d70 100644 --- a/documentation/style-guide.rst +++ b/documentation/style-guide.rst @@ -242,8 +242,8 @@ For new documentation, do not use a byline (naming the author of the document). Explicit attribution tends to discourage other users from updating community documentation. -Existing documentation with bylines will not be changed unless the author -decides to do so. This is subject to change in the future. +Existing bylines are for historical interest only. They do not imply ownership +or necessary approvals, and do not prevent edits or updates by others. Pronunciation of dunder names From 2243924d488f19b0a7d3792798f7f321d1c9ad38 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Thu, 19 Feb 2026 18:51:24 +0200 Subject: [PATCH 24/48] Update org owners (#1728) --- developer-workflow/development-cycle.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/developer-workflow/development-cycle.rst b/developer-workflow/development-cycle.rst index 2f1cadbbd..53a78772e 100644 --- a/developer-workflow/development-cycle.rst +++ b/developer-workflow/development-cycle.rst @@ -268,8 +268,8 @@ This role is paramount to the security of the Python Language, Community, and Infrastructure. The Executive Director of the Python Software Foundation delegates authority on -GitHub Organization Owner Status to Ee Durbin - Python Software -Foundation Director of Infrastructure. Common reasons for this role are: +GitHub Organization Owner Status to Jacob Coffee - Python Software +Foundation Infrastructure Engineer. Common reasons for this role are: Infrastructure Staff Membership, Python Software Foundation General Counsel, and Python Software Foundation Staff as fallback. @@ -293,7 +293,7 @@ Current owners +----------------------+--------------------------------+-----------------+ | Donald Stufft | Infrastructure Staff | dstufft | +----------------------+--------------------------------+-----------------+ -| Ee Durbin | PSF Director of Infrastructure | ewdurbin | +| Ee Durbin | Infrastructure Staff | ewdurbin | +----------------------+--------------------------------+-----------------+ | Jacob Coffee | PSF Infrastructure Engineer | JacobCoffee | +----------------------+--------------------------------+-----------------+ From 5ed0f19204f525459990ab21218106bf2a24a0ea Mon Sep 17 00:00:00 2001 From: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> Date: Fri, 20 Feb 2026 13:08:39 +0000 Subject: [PATCH 25/48] Refactor tab activation logic (#1742) --- contrib/index.rst | 9 +-------- documentation/devguide.rst | 8 +------- documentation/start-documenting.rst | 8 +------- getting-started/git-boot-camp.rst | 8 +------- getting-started/setup-building.rst | 8 +------- include/activate-tab.rst | 7 +++++++ index.rst | 8 +------- testing/coverage.rst | 8 +------- testing/run-write-tests.rst | 8 +------- 9 files changed, 15 insertions(+), 57 deletions(-) create mode 100644 include/activate-tab.rst diff --git a/contrib/index.rst b/contrib/index.rst index e519c7dab..0e7c79ca1 100644 --- a/contrib/index.rst +++ b/contrib/index.rst @@ -4,14 +4,7 @@ Python Contributor's Guide (draft) ================================== -.. raw:: html - - - +.. include:: /include/activate-tab.rst .. important:: diff --git a/documentation/devguide.rst b/documentation/devguide.rst index fc12c369f..74f734831 100644 --- a/documentation/devguide.rst +++ b/documentation/devguide.rst @@ -4,13 +4,7 @@ Helping with the Developer's Guide ================================== -.. raw:: html - - +.. include:: /include/activate-tab.rst .. highlight:: console diff --git a/documentation/start-documenting.rst b/documentation/start-documenting.rst index 7865f125d..917cb30bf 100644 --- a/documentation/start-documenting.rst +++ b/documentation/start-documenting.rst @@ -5,13 +5,7 @@ Getting started =============== -.. raw:: html - - +.. include:: /include/activate-tab.rst .. highlight:: rest diff --git a/getting-started/git-boot-camp.rst b/getting-started/git-boot-camp.rst index b845e00aa..6808e99b4 100644 --- a/getting-started/git-boot-camp.rst +++ b/getting-started/git-boot-camp.rst @@ -4,13 +4,7 @@ Git bootcamp and cheat sheet ============================ -.. raw:: html - - +.. include:: /include/activate-tab.rst .. highlight:: console diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index 110d718e9..ed7376a02 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -5,13 +5,7 @@ Setup and building ================== -.. raw:: html - - +.. include:: /include/activate-tab.rst .. highlight:: console diff --git a/include/activate-tab.rst b/include/activate-tab.rst new file mode 100644 index 000000000..229542bf4 --- /dev/null +++ b/include/activate-tab.rst @@ -0,0 +1,7 @@ +.. raw:: html + + diff --git a/index.rst b/index.rst index 997f59932..d1369cac3 100644 --- a/index.rst +++ b/index.rst @@ -4,13 +4,7 @@ Python Developer's Guide ======================== -.. raw:: html - - +.. include:: include/activate-tab.rst .. highlight:: bash diff --git a/testing/coverage.rst b/testing/coverage.rst index c34bb5235..48c2efc98 100644 --- a/testing/coverage.rst +++ b/testing/coverage.rst @@ -4,13 +4,7 @@ Increase test coverage ====================== -.. raw:: html - - +.. 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 diff --git a/testing/run-write-tests.rst b/testing/run-write-tests.rst index 34101bd2d..405d10f03 100644 --- a/testing/run-write-tests.rst +++ b/testing/run-write-tests.rst @@ -5,13 +5,7 @@ Running and writing tests ========================= -.. raw:: html - - +.. include:: /include/activate-tab.rst .. note:: From b736a43529cb453eda9377ccde028b42b9f3b30d Mon Sep 17 00:00:00 2001 From: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> Date: Fri, 20 Feb 2026 13:09:20 +0000 Subject: [PATCH 26/48] Remove `sectionauthor` and `moduleauthor` doc (#1743) --- documentation/markup.rst | 27 --------------------------- 1 file changed, 27 deletions(-) diff --git a/documentation/markup.rst b/documentation/markup.rst index f9291a335..24f359bb1 100644 --- a/documentation/markup.rst +++ b/documentation/markup.rst @@ -349,22 +349,6 @@ they are used in the Python documentation. `__. -Meta-information markup ------------------------ - -.. describe:: sectionauthor - - Identifies the author of the current section. The argument should include - the author's name such that it can be used for presentation (though it isn't) - and email address. The domain name portion of the address should be lower - case. Example:: - - .. sectionauthor:: Guido van Rossum - - Currently, this markup isn't reflected in the output in any way, but it helps - keep track of contributions. - - Module-specific markup ---------------------- @@ -379,11 +363,6 @@ file might start like this:: .. module:: parrot :platform: Unix, Windows :synopsis: Analyze and reanimate dead parrots. - .. moduleauthor:: Eric Cleese - .. moduleauthor:: John Idle - -As you can see, the module-specific markup consists of two directives, the -``module`` directive and the ``moduleauthor`` directive. .. describe:: module @@ -403,12 +382,6 @@ As you can see, the module-specific markup consists of two directives, the The ``deprecated`` option can be given (with no value) to mark a module as deprecated; it will be designated as such in various locations then. -.. describe:: moduleauthor - - The ``moduleauthor`` directive, which can appear multiple times, names the - authors of the module code, just like ``sectionauthor`` names the author(s) - of a piece of documentation. It too does not result in any output currently. - .. note:: It is important to make the section title of a module-describing file From 0fe9ca76732165bae2ce783a97f142ab704e2957 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> Date: Sat, 21 Feb 2026 14:57:05 +0000 Subject: [PATCH 27/48] Move NEWS entries to pull-request-lifecycle (#1506) 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: Bénédikt Tran <10796600+picnixz@users.noreply.github.com> --- core-team/committing.rst | 102 +-------------------- getting-started/pull-request-lifecycle.rst | 99 ++++++++++++++++++++ 2 files changed, 103 insertions(+), 98 deletions(-) diff --git a/core-team/committing.rst b/core-team/committing.rst index a88ff1205..c606df383 100644 --- a/core-team/committing.rst +++ b/core-team/committing.rst @@ -73,104 +73,10 @@ to enter the public source tree. Ask yourself the following questions: significant improvements, or backwards-incompatible changes), then an entry in the ``What's New in Python`` document (in ``Doc/whatsnew/``) should be added as well. Changes that affect only documentation generally do not - require a ``NEWS`` entry. (See the following section for more information.) - -.. _news-entry: -.. _what-s-new-and-news-entries: - -Updating NEWS and What's New in Python --------------------------------------- - -Changes that require NEWS entries -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Most changes made to the codebase deserve an entry in :cpy-file:`Misc/NEWS.d`, -except for the following: - -* documentation changes -* test changes -* strictly internal changes with no user-visible effects -* changes that already have a ``NEWS`` entry -* reverts that have not yet been included in any formal release - (including alpha and beta releases) - -For the last two, note the following: - -#. **If a change is reverted prior to release**, then the corresponding - entry is simply removed. Otherwise, a new entry must be added noting - that the change has been reverted (for example, when a feature is released in - an alpha and then cut prior to the first beta). - -#. **If a change is a fix (or other adjustment) to an earlier unreleased - change and the original** ``NEWS`` **entry remains valid**, then no additional - entry is needed. - -Changes that require "What's New in Python" entries -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -If a change is particularly interesting for end users (for example, new features, -significant improvements, or backwards-incompatible changes), add an entry in -the "What's New in Python" document (in :cpy-file:`Doc/whatsnew/`) -in addition to the ``NEWS`` entry. - -In most cases, it is sufficient to reuse the wording from the ``NEWS`` entry -in the "What's New in Python" entry. - -.. note:: - - A change that needs an entry in "What's New in Python", - is very likely not suitable for inclusion in a maintenance release. - -How to add a NEWS entry -^^^^^^^^^^^^^^^^^^^^^^^ - -``NEWS`` entries go into the ``Misc/NEWS.d`` directory as individual files. The -``NEWS`` entry can be created by using `blurb-it `__, -or the :pypi:`blurb` tool and its ``blurb add`` command. - -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 -for what was affected (for example, ``Misc/NEWS.d/next/Library`` for changes relating -to the standard library). The file name itself should be in the format -``.gh-issue-..rst``: - -* ```` is today's date joined with a hyphen (``-``) to your current - local time, in the ``YYYY-MM-DD-hh-mm-ss`` format (for example, ``2017-05-27-16-46-23``). -* ```` is the issue number the change is for (for example, ``12345`` - for ``gh-issue-12345``). -* ```` is a unique string to guarantee that the file name is - unique across branches (for example, ``Yl4gI2``). It is typically six characters - long, but it can be any length of letters and numbers. Its uniqueness - can be satisfied by typing random characters on your keyboard. - -As a result, a file name can look something like -``Misc/NEWS.d/next/Library/2017-05-27-16-46-23.gh-issue-12345.Yl4gI2.rst``. - -How to write a NEWS entry -^^^^^^^^^^^^^^^^^^^^^^^^^ - -All ``NEWS`` entries end up being part of the changelog. -The changelog contains *a lot* of entries, -and its intended audience is mainly users, not the core team and contributors. -Take this into consideration when wording your ``NEWS`` entry. -Describe the user-visible effects of your change succinctly and accurately; -avoid long technical elaborations, digressions, and do not expect or require -the reader to have read the actual diff for the change. - -The contents of a ``NEWS`` file should be valid reStructuredText. An 80 character -column width should be used. There is no indentation or leading marker in the -file (for example, ``-``). There is also no need to start the entry with the issue -number since it is part of the file name. You can use -:ref:`inline markups ` too. Here is an example of a ``NEWS`` -entry:: - - Fix warning message when :func:`os.chdir` fails inside - :func:`test.support.temp_cwd`. Contributed by Chris Jerdonek. - -The inline Sphinx roles like ``:func:`` can be used help readers -find more information. You can build HTML and verify that the -link target is appropriate by using :ref:`make html `. + require a ``NEWS`` entry. + + .. seealso:: + :ref:`what-s-new-and-news-entries` Working with Git_ diff --git a/getting-started/pull-request-lifecycle.rst b/getting-started/pull-request-lifecycle.rst index d23e16695..c1e471c17 100644 --- a/getting-started/pull-request-lifecycle.rst +++ b/getting-started/pull-request-lifecycle.rst @@ -240,6 +240,105 @@ should do to help ensure that your pull request is accepted. #. Proper :ref:`documentation ` additions/changes should be included. +.. _news-entry: +.. _what-s-new-and-news-entries: + +Updating NEWS and What's New in Python +====================================== + +Changes that require NEWS entries +--------------------------------- + +Most changes made to the codebase deserve an entry in :cpy-file:`Misc/NEWS.d`, +except for the following: + +* documentation changes +* test changes +* strictly internal changes with no user-visible effects +* changes that already have a ``NEWS`` entry +* reverts that have not yet been included in any formal release + (including alpha and beta releases) + +For the last two, note the following: + +#. **If a change is reverted prior to release**, then the corresponding + entry is simply removed. Otherwise, a new entry must be added noting + that the change has been reverted (for example, when a feature is released in + an alpha and then cut prior to the first beta). + +#. **If a change is a fix (or other adjustment) to an earlier unreleased + change and the original** ``NEWS`` **entry remains valid**, then no additional + entry is needed. + +Changes that require "What's New in Python" entries +--------------------------------------------------- + +If a change is particularly interesting for end users (for example, new features, +significant improvements, or backwards-incompatible changes), add an entry in +the "What's New in Python" document (in :cpy-file:`Doc/whatsnew/`, the 3.X.rst +file where X is the current Python version) in addition to the ``NEWS`` entry. + +In most cases, it is sufficient to reuse the wording from the ``NEWS`` entry +in the "What's New in Python" entry. + +.. note:: + + A change that needs an entry in "What's New in Python" + is very likely not suitable for inclusion in a maintenance release. + +How to add a NEWS entry +----------------------- + +``NEWS`` entries go into the ``Misc/NEWS.d`` directory as individual files. The +``NEWS`` entry can be created by using `blurb-it `_, +or the :pypi:`blurb` tool and its ``blurb add`` command. + +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 +for what was affected (for example, ``Misc/NEWS.d/next/Library`` for changes relating +to the standard library). The file name itself should be in the format +``.gh-issue-..rst``: + +* ```` is today's date joined with a hyphen (``-``) to your current + local time, in the ``YYYY-MM-DD-hh-mm-ss`` format (for example, ``2017-05-27-16-46-23``). +* ```` is the issue number the change is for (for example, ``12345`` + for ``gh-issue-12345``). +* ```` is a unique string to guarantee that the file name is + unique across branches (for example, ``Yl4gI2``). It is typically six characters + long, but it can be any length of letters and numbers. Its uniqueness + can be satisfied by typing random characters on your keyboard. + +As a result, a file name can look something like +``Misc/NEWS.d/next/Library/2017-05-27-16-46-23.gh-issue-12345.Yl4gI2.rst``. + +How to write a NEWS entry +------------------------- + +All ``NEWS`` entries end up being part of the changelog. +The changelog contains *a lot* of entries, +and its intended audience is mainly users, not core devs and contributors. +Take this into consideration when wording your ``NEWS`` entry. +Describe the user-visible effects of your change succinctly and accurately; +avoid long technical elaborations, digressions, and do not expect or require +the reader to have read the actual diff for the change. + +The contents of a ``NEWS`` file should be valid reStructuredText. An 80 character +column width should be used. There is no indentation or leading marker in the +file (for example, ``-``). There is also no need to start the entry with the issue +number since it is part of the file name. You can use +:ref:`inline markups ` too. Here is an example of a ``NEWS`` +entry: + +.. code-block:: rst + + Fix warning message when :func:`os.chdir` fails inside + :func:`test.support.temp_cwd`. Contributed by Chris Jerdonek. + +The inline Sphinx roles like :rst:role:`:func: ` can be used help readers +find more information. You can build HTML and verify that the +link target is appropriate by using :ref:`make html `. + Copyrights ========== From 16c670ea8e4ce2751f45ce68ab4adbcb06a4993c Mon Sep 17 00:00:00 2001 From: Seth Michael Larson Date: Thu, 26 Feb 2026 09:06:37 -1000 Subject: [PATCH 28/48] Add William Woodruff to the PSRT (#1745) --- developer-workflow/psrt.csv | 1 + 1 file changed, 1 insertion(+) diff --git a/developer-workflow/psrt.csv b/developer-workflow/psrt.csv index d5ee7d954..e21aac97b 100644 --- a/developer-workflow/psrt.csv +++ b/developer-workflow/psrt.csv @@ -19,3 +19,4 @@ Seth Larson,sethmlarson,Admin Steve Dower,zooba,Release Manager Thomas Wouters,Yhg1s,Release Manager Tim Peters,tim-one, +William Woodruff,woodruffw, From c70035a7f96bca6dc6057285f4f4d1893b95e820 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> Date: Tue, 3 Mar 2026 12:30:01 +0000 Subject: [PATCH 29/48] Add Plausible analytics (#1749) --- _templates/page.html | 8 ++++++++ conf.py | 6 ++++++ 2 files changed, 14 insertions(+) create mode 100644 _templates/page.html diff --git a/_templates/page.html b/_templates/page.html new file mode 100644 index 000000000..33ae2d56a --- /dev/null +++ b/_templates/page.html @@ -0,0 +1,8 @@ +{% extends "!page.html" %} + +{% block extrahead %} +{{ super() }} +{% if not READTHEDOCS %} + +{% endif %} +{% endblock %} diff --git a/conf.py b/conf.py index c38e33dd8..7c0dae346 100644 --- a/conf.py +++ b/conf.py @@ -1,4 +1,5 @@ import json +import os from urllib.request import urlopen extensions = [ @@ -37,6 +38,7 @@ "source_repository": "https://github.com/python/devguide", "source_branch": "main", } +templates_path = ['_templates'] html_static_path = ['_static'] html_css_files = [ 'devguide_overrides.css', @@ -50,6 +52,10 @@ # Set to '' to prevent appending "documentation" to the site title html_title = "" +html_context = { + "READTHEDOCS": bool(os.getenv("READTHEDOCS")), +} + linkcheck_allowed_redirects = { # Edit page r"https://docs.google.com/document/d/.*/": r"https://docs.google.com/document/d/.*/edit", # noqa: E501 From ae7f8bca4459295e1f45a87af17e37c62430d1c5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Filipe=20La=C3=ADns?= Date: Tue, 3 Mar 2026 15:02:55 +0000 Subject: [PATCH 30/48] Update experts entries for FFY00 (#1750) --- core-team/experts.rst | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/core-team/experts.rst b/core-team/experts.rst index ea807c42b..1a1643c1c 100644 --- a/core-team/experts.rst +++ b/core-team/experts.rst @@ -114,7 +114,7 @@ ftplib giampaolo* functools rhettinger* gc pitrou, pablogsal, nascheme getopt serhiy-storchaka* -getpath FFY00 +getpath FFY00* getpass gettext tomasr8 glob serhiy-storchaka* @@ -127,7 +127,7 @@ http idlelib kbkaiser (inactive), terryjreedy*, serwy (inactive), taleinat imaplib -importlib brettcannon +importlib brettcannon, FFY00* inspect 1st1 io benjaminp, stutzbach^ ipaddress pmoody^ @@ -144,7 +144,7 @@ marshal math rhettinger, stutzbach^ mimetypes mmap Yhg1s -modulefinder theller (inactive), jvr^ +modulefinder theller (inactive), jvr^, FFY00 msvcrt multiprocessing applio*, pitrou, jnoller^ (inactive), sbt^ (inactive), gpshead* netrc @@ -158,7 +158,7 @@ pathlib barneygale* pdb gaogaotiantian pickle avassalotti, serhiy-storchaka* pickletools avassalotti, serhiy-storchaka* -pkgutil +pkgutil FFY00* platform malemburg plistlib poplib @@ -179,7 +179,7 @@ readline Yhg1s reprlib resource Yhg1s rlcompleter -runpy ncoghlan +runpy ncoghlan, FFY00 sched secrets select @@ -188,7 +188,7 @@ shelve shlex shutil tarekziade, giampaolo signal gpshead -site +site FFY00* smtplib socket gpshead socketserver @@ -202,7 +202,7 @@ struct meadori subprocess astrand^ (inactive), giampaolo, gpshead* symtable benjaminp sys -sysconfig FFY00 +sysconfig FFY00* syslog jafo^* tabnanny tim-one (inactive) tarfile gustaebel @@ -230,7 +230,7 @@ unittest ezio-melotti, rbtcollins, gpshead, serhiy-storchaka* unittest.mock urllib orsenthil uuid -venv vsajip, FFY00 +venv vsajip, FFY00* warnings wave weakref freddrake, nascheme @@ -323,14 +323,14 @@ devguide merwok, ezio-melotti, willingc, Mariatta, hugovk, documentation ezio-melotti, merwok, JulienPalard, willingc, hugovk, AA-Turner, AlexWaygood* emoji Mariatta -extension modules encukou, ncoghlan +extension modules encukou, ncoghlan, FFY00 filesystem giampaolo -frozen modules ericsnowcurrently, gvanrossum, kumaraditya303 +frozen modules ericsnowcurrently, gvanrossum, kumaraditya303, FFY00 f-strings ericvsmith* GUI i18n malemburg, merwok, tomasr8 -import machinery brettcannon, ncoghlan, ericsnowcurrently, FFY00 -initialization FFY00 +import machinery brettcannon, ncoghlan, ericsnowcurrently, FFY00* +initialization FFY00* io benjaminp, stutzbach^, gpshead JIT brandtbucher*, savannahostrowski* locale malemburg @@ -339,7 +339,7 @@ memory management tim-one, malemburg, Yhg1s, nascheme memoryview networking giampaolo, gpshead object model benjaminp, Yhg1s -packaging tarekziade, malemburg, alexis^, merwok, dstufft, pfmoore, emmatyping +packaging tarekziade, malemburg, alexis^, merwok, dstufft, pfmoore, emmatyping, FFY00 pattern matching brandtbucher* PEG parser gvanrossum, pablogsal, lysnikolaou performance vstinner, serhiy-storchaka*, 1st1, rhettinger, markshannon, @@ -348,7 +348,7 @@ pip ncoghlan, dstufft, pfmoore, Marcus.Smith^, pradyunsg release management tarekziade, malemburg, benjaminp, warsaw, gvanrossum, anthonybaxter^, merwok, ned-deily, birkenfeld, JulienPalard, hugovk -runtime lifecycle ericsnowcurrently, kumaraditya303, zooba, ZeroIntensity, nascheme +runtime lifecycle ericsnowcurrently, kumaraditya303, zooba, ZeroIntensity, nascheme, FFY00 str.format ericvsmith* subinterpreters ericsnowcurrently, kumaraditya303, ZeroIntensity* symbol table JelleZijlstra, carljm From 9537d3d1a182efbc065eaf398eaac4b482b5e9c3 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Tue, 3 Mar 2026 20:10:49 +0200 Subject: [PATCH 31/48] Enable Plausible for RTD but not RTD previews (#1751) --- _templates/page.html | 2 +- conf.py | 6 +++++- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/_templates/page.html b/_templates/page.html index 33ae2d56a..d1c9a515a 100644 --- a/_templates/page.html +++ b/_templates/page.html @@ -2,7 +2,7 @@ {% block extrahead %} {{ super() }} -{% if not READTHEDOCS %} +{% if not is_deployment_preview %} {% endif %} {% endblock %} diff --git a/conf.py b/conf.py index 7c0dae346..cd846dd04 100644 --- a/conf.py +++ b/conf.py @@ -52,8 +52,12 @@ # Set to '' to prevent appending "documentation" to the site title html_title = "" +# Deployment preview information +# (See .readthedocs.yaml and https://docs.readthedocs.io/en/stable/reference/environment-variables.html) +is_deployment_preview = os.getenv("READTHEDOCS_VERSION_TYPE") == "external" + html_context = { - "READTHEDOCS": bool(os.getenv("READTHEDOCS")), + "is_deployment_preview": is_deployment_preview, } linkcheck_allowed_redirects = { From a0365490d753902036ba0e1f22e21d39539f6e29 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> Date: Tue, 3 Mar 2026 20:33:30 +0000 Subject: [PATCH 32/48] Update labels set by templates (#1755) --- .github/ISSUE_TEMPLATE/bug_report.yml | 2 +- .github/ISSUE_TEMPLATE/feature_request.yml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index b160c6ea1..f6d55b124 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -1,7 +1,7 @@ name: "Bug report" description: Create a report to help us improve the Python devguide title: "Bug: " -labels: ["bug"] +labels: ["type-bug"] assignees: [] body: diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml index a4413c137..7a7e9ec80 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.yml +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -1,7 +1,7 @@ name: "Feature request" description: Suggest an idea for the Python devguide title: "Feature: <title>" -labels: ["enhancement"] +labels: ["type-feature"] assignees: [] body: From 9f2df6d19ffe4b61cbd782bb6ccf037d05feb691 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> Date: Wed, 4 Mar 2026 12:31:01 +0000 Subject: [PATCH 33/48] Exclude docs translations from organization repo policy (GH-1690) --- developer-workflow/development-cycle.rst | 5 ++++- documentation/translations/coordinating.rst | 2 ++ 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/developer-workflow/development-cycle.rst b/developer-workflow/development-cycle.rst index 53a78772e..af198a400 100644 --- a/developer-workflow/development-cycle.rst +++ b/developer-workflow/development-cycle.rst @@ -232,7 +232,10 @@ This includes, for example: Before adding a new repository to the organization, open a discussion to seek consensus in the `Committers Discourse category <https://discuss.python.org/c/committers/5>`__. Once people are satisfied with that, ask the `Python steering council <https://github.com/python/steering-council>`__ -to grant permission. +to grant permission. Note that this process is not necessary for +:ref:`docs translations <translation-repo>` following +:pep:`PEP 545 <545#repository-for-po-files>`, which can be added at a +core team member’s discretion. Note that several repositories remain in the organization for historic reasons, and would probably not be appropriate to add today. diff --git a/documentation/translations/coordinating.rst b/documentation/translations/coordinating.rst index a7872b6ae..82cfce74f 100644 --- a/documentation/translations/coordinating.rst +++ b/documentation/translations/coordinating.rst @@ -64,6 +64,8 @@ to make your translation easier to find. In the entry you can also include links to guides or other resources for translators. +.. _translation-repo: + Repository ---------- From 50dd71b2e8544d48adcf759e6fff0175adc3b8ff Mon Sep 17 00:00:00 2001 From: Savannah Ostrowski <savannah@python.org> Date: Wed, 4 Mar 2026 11:00:34 -0800 Subject: [PATCH 34/48] Update WASI build instructions (#1752) --- getting-started/setup-building.rst | 33 +++++++++++++++++++++--------- 1 file changed, 23 insertions(+), 10 deletions(-) diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index ed7376a02..2204d6f94 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -379,6 +379,7 @@ compiler just like building for :ref:`Unix <unix-compiling>` as well as: 1. A C compiler that can target WebAssembly (for example, `WASI SDK`_) 2. A WASI host/runtime (for example, Wasmtime_) +3. A system install of Python 3.11 or newer to run the build scripts All of this is provided in the WASI :ref:`dev container <using-a-container>` (which you can select as an alternative container when using a @@ -401,31 +402,43 @@ to have a version of Python for the build system to use and another that's the build you ultimately care about (that is, the build Python is not meant for use by you directly, only the build system). -The easiest way to get a debug build of CPython for WASI is to use the -``Tools/wasm/wasi.py build`` command (which should be run w/ a recent version of -Python you have installed on your machine): +The easiest way to get a debug build of CPython for WASI is to run the +following command with Python 3.11 or newer: -.. tab:: Python 3.14+ +.. tab:: Python 3.15+ .. code-block:: shell - python3 Tools/wasm/wasi build --quiet -- --config-cache --with-pydebug + python Platforms/WASI build --quiet -- --config-cache --with-pydebug + +.. tab:: Python 3.14 + + .. code-block:: shell + + python Tools/wasm/wasi build --quiet -- --config-cache --with-pydebug .. tab:: Python 3.13 .. code-block:: shell - python3 Tools/wasm/wasi.py build --quiet -- --config-cache --with-pydebug + python Tools/wasm/wasi.py build --quiet -- --config-cache --with-pydebug That single command will configure and build both the build Python and the -WASI build in ``cross-build/build`` and ``cross-build/wasm32-wasip1``, -respectively. +WASI build in the ``cross-build/`` directory. You can also do each configuration and build step separately; the command above is a convenience wrapper around the following commands: +.. tab:: Python 3.15+ + + .. code-block:: shell + + $ python Platforms/WASI configure-build-python --quiet -- --config-cache --with-pydebug + $ python Platforms/WASI make-build-python --quiet + $ python Platforms/WASI configure-host --quiet -- --config-cache + $ python Platforms/WASI make-host --quiet -.. tab:: Python 3.14+ +.. tab:: Python 3.14 .. code-block:: shell @@ -448,7 +461,7 @@ is a convenience wrapper around the following commands: The ``configure-host`` command infers the use of ``--with-pydebug`` from the build Python. -Running the separate commands after ``wasi build`` is useful if you, for example, +Running the separate commands after ``build`` is useful if you, for example, only want to run the ``make-host`` step after making code changes. Once everything is complete, there will be a From 684b65438f637e264fe8bccf4d76325f26f8ba90 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> Date: Thu, 5 Mar 2026 08:28:26 +0000 Subject: [PATCH 35/48] Restructure index page (GH-1748) This moves a few sections around to been more introductory rather than jumping straight into the quickstart, drops less important/relevant sections to the bottom (i.e. the alternative implementations), removes the version section stub (it has been there for long enough), and updates a few little things along the way. --- index.rst | 233 +++++++++++++++++++++++++----------------------------- 1 file changed, 106 insertions(+), 127 deletions(-) diff --git a/index.rst b/index.rst index d1369cac3..1c15d824d 100644 --- a/index.rst +++ b/index.rst @@ -11,14 +11,72 @@ Python Developer's Guide This guide is a comprehensive resource for :ref:`contributing <contributing>` to Python_ -- for both new and experienced contributors. It is :ref:`maintained <devguide>` by the same -community that maintains Python. We welcome your contributions to Python! +community that maintains Python. We welcome your contributions! + + +.. _contributing: + +Contributing +------------ + +We encourage everyone to contribute to Python. To help you, we have put up this +developer's guide. If you still have questions after reviewing the material in +this guide, then the `Core Python Mentorship`_ group is available to help guide new +contributors through the process. + +Guide for contributing to Python: + +.. list-table:: + :widths: 10 10 10 + :header-rows: 1 + + * - Documentation + - Code + - Triage + * - + * :ref:`docquality` + * :ref:`documenting` + * :ref:`style-guide` + * :ref:`rst-primer` + * :ref:`translating` + * :ref:`devguide` + - + * :ref:`setup` + * :ref:`help` + * :ref:`pullrequest` + * :ref:`runtests` + * :ref:`fixingissues` + * :ref:`communication` + * :ref:`gitbootcamp` + * :ref:`devcycle` + - + * :ref:`tracker` + * :ref:`triaging` + * :ref:`helptriage` + * :ref:`experts` + * :ref:`labels` + * :ref:`gh-faq` + * :ref:`triage-team` + +We **recommend** that sections of this guide be read as needed. You +can stop where you feel comfortable and begin contributing immediately without +reading and understanding everything. If you do choose to skip +around within the guide, be aware that sections build on each other, +so you may find it necessary to backtrack to fill in +missing concepts and terminology. + +A number of individuals from the Python community have contributed to a series +of excellent guides at `Open Source Guides <https://opensource.guide/>`__. +For example, +`How to Contribute to Open Source <https://opensource.guide/how-to-contribute/>`__. + .. _quick-reference: Quick reference --------------- -Here are the basic steps needed to get set up and contribute a pull request. +Here are the basic steps needed to get set up and open a pull request. This is meant as a checklist, once you know the basics. For complete instructions please see the :ref:`setup guide <setup>`. @@ -70,9 +128,10 @@ instructions please see the :ref:`setup guide <setup>`. ./python.exe -m test -j8 - Note: :ref:`Most <mac-python.exe>` macOS systems use - :file:`./python.exe` in order to avoid filename conflicts with - the ``Python`` directory. + .. note:: + :ref:`Most <mac-python.exe>` macOS systems use + :file:`./python.exe` in order to avoid filename conflicts with + the ``Python`` directory. .. tab:: Windows @@ -85,40 +144,18 @@ instructions please see the :ref:`setup guide <setup>`. git checkout -b fix-issue-12345 main If an issue does not already exist, please `create it - <https://github.com/python/cpython/issues>`__. Trivial issues (for example, typo fixes) do - not require any issue to be created. - -6. Once you fixed the issue, run the tests, and the patchcheck: - - .. tab:: Unix - - .. code-block:: shell - - make patchcheck - - .. tab:: macOS - - .. code-block:: shell - - make patchcheck + <https://github.com/python/cpython/issues>`__. Trivial issues (for example, typos) do + not require an issue. - .. tab:: Windows - - .. code-block:: dosbatch - - .\python.bat Tools\patchcheck\patchcheck.py - - If everything is ok, commit. - -7. Push the branch on your fork on GitHub and :ref:`create a pull request - <pullrequest>`. Include the issue number using ``gh-NNNN`` in the - pull request description. For example: +6. Push the branch on your fork on GitHub and :ref:`create a pull request + <pullrequest>`. Include the issue number using ``gh-NNNNNN`` in the + pull request title. For example: .. code-block:: text gh-12345: Fix some bug in spam module -8. Add a News entry into the ``Misc/NEWS.d`` directory as individual file. The +7. Add a News entry into the ``Misc/NEWS.d/`` directory as individual file. The news entry can be created by using `blurb-it <https://blurb-it.herokuapp.com/>`__, or the :pypi:`blurb` tool and its ``blurb add`` command. Please read more about ``blurb`` in its @@ -130,58 +167,6 @@ instructions please see the :ref:`setup guide <setup>`. Agreement (CLA) as described in the :ref:`Licensing <cla>` section of this guide. -Quick links ------------ - -Here are some links that you probably will reference frequently while -contributing to Python: - -* `Issue tracker`_ -* `Buildbot status`_ -* :ref:`help` -* PEPs_ (Python Enhancement Proposals) -* :ref:`gitbootcamp` - -.. _contributing: - -Contributing ------------- - -We encourage everyone to contribute to Python and that's why we have put up this -developer's guide. If you still have questions after reviewing the material in -this guide, then the `Core Python Mentorship`_ group is available to help guide new -contributors through the process. - -A number of individuals from the Python community have contributed to a series -of excellent guides at `Open Source Guides <https://opensource.guide/>`__. - -Core developers and contributors alike will find the following guides useful: - -* `How to Contribute to Open Source <https://opensource.guide/how-to-contribute/>`__ -* `Building Welcoming Communities <https://opensource.guide/building-community/>`__ - -Guide for contributing to Python: - -======================== =================== ======================= ======================= -Contributors Documentarians Triagers Core team -======================== =================== ======================= ======================= -:ref:`setup` :ref:`docquality` :ref:`tracker` :ref:`responsibilities` -:ref:`help` :ref:`documenting` :ref:`triaging` :ref:`developers` -:ref:`pullrequest` :ref:`style-guide` :ref:`helptriage` :ref:`committing` -:ref:`runtests` :ref:`rst-primer` :ref:`experts` :ref:`devcycle` -:ref:`fixingissues` :ref:`translating` :ref:`labels` :ref:`motivations` -:ref:`communication` :ref:`devguide` :ref:`gh-faq` :ref:`experts` -:ref:`gitbootcamp` :ref:`triage-team` -:ref:`devcycle` -======================== =================== ======================= ======================= - -We **recommend** that the documents in this guide be read as needed. You -can stop where you feel comfortable and begin contributing immediately without -reading and understanding these documents all at once. If you do choose to skip -around within the documentation, be aware that it is written assuming preceding -documentation has been read so you may find it necessary to backtrack to fill in -missing concepts and terminology. - Proposing changes to Python itself ---------------------------------- @@ -200,36 +185,6 @@ happen and that process is also described as part of this guide: * :ref:`langchanges` -Other interpreter implementations ---------------------------------- - -This guide is specifically for contributing to the Python reference interpreter, -also known as CPython (while most of the standard library is written in Python, -the interpreter core is written in C and integrates most easily with the C and -C++ ecosystems). - -There are other Python implementations, each with a different focus. Like -CPython, they always have more things they would like to do than they have -developers to work on them. Some major examples that may be of interest are: - -* PyPy_: A Python interpreter focused on high speed (JIT-compiled) operation - on major platforms. -* GraalPy_: A Python interpreter which has first-class support for - embedding in Java, built on GraalVM. -* Jython_: A Python interpreter focused on good integration with the Java - Virtual Machine (JVM) environment. -* IronPython_: A Python interpreter focused on good integration with the - Common Language Runtime (CLR) provided by .NET and Mono. -* Stackless_: A Python interpreter focused on providing lightweight - microthreads while remaining largely compatible with CPython specific - extension modules. -* MicroPython_: A tiny Python interpreter with small subset of the Python - standard library that is optimised to run on microcontrollers and in - constrained environments. -* CircuitPython_: A fork of MicroPython designed to simplify experimenting - and learning to code on low-cost microcontroller boards. - - Key resources ------------- @@ -246,11 +201,14 @@ Key resources * Source code * `Browse online <https://github.com/python/cpython/>`__ - * `Snapshot of the *main* branch <https://github.com/python/cpython/archive/main.zip>`__ + * `Download a snapshot <https://github.com/python/cpython/archive/main.zip>`__ + of the ``main`` branch * PEPs_ (Python Enhancement Proposals) +* `The Python Discourse <https://discuss.python.org/>`__ * :ref:`help` * :ref:`developers` +* :ref:`gitbootcamp` .. _resources: @@ -268,30 +226,52 @@ Additional resources * :ref:`gdb` * :ref:`clang` - * Various tools with configuration files as found in the `Misc directory`_ - * Information about editors and their configurations can be found in the - `wiki <https://wiki.python.org/moin/PythonEditors>`__ + * Various tools with configuration files as found in the + :cpy-file:`Misc/` directory * `python.org maintenance`_ -* :ref:`Search this guide <search>` Code of conduct --------------- + Please note that all interactions on `Python Software Foundation <https://www.python.org/psf-landing/>`__-supported infrastructure is `covered <https://www.python.org/psf/records/board/minutes/2014-01-06/#management-of-the-psfs-web-properties>`__ by the `PSF Code of Conduct <https://policies.python.org/python.org/code-of-conduct/>`__, which includes all infrastructure used in the development of Python itself -(for example, mailing lists, issue trackers, GitHub, etc.). +(for example, Discourse, issue trackers, GitHub, and so on). In general this means everyone is expected to be open, considerate, and respectful of others no matter what their position is within the project. -Status of Python branches -------------------------- -Moved to :ref:`versions` +Other interpreter implementations +--------------------------------- + +This guide is specifically for contributing to the Python reference interpreter, +also known as CPython (while most of the standard library is written in Python, +the interpreter core is written in C and integrates most easily with the C and +C++ ecosystems). + +There are other Python implementations, each with a different focus. Like +CPython, they always have more things they would like to do than they have +developers to work on them. Some major examples that may be of interest are: + +* PyPy_: A Python interpreter focused on high speed (JIT-compiled) operation + on major platforms. +* GraalPy_: A Python interpreter which has first-class support for + embedding in Java, built on GraalVM. +* Jython_: A Python interpreter focused on good integration with the Java + Virtual Machine (JVM) environment. +* IronPython_: A Python interpreter focused on good integration with the + Common Language Runtime (CLR) provided by .NET and Mono. +* MicroPython_: A tiny Python interpreter with small subset of the Python + standard library that is optimised to run on microcontrollers and in + constrained environments. +* CircuitPython_: A fork of MicroPython designed to simplify experimenting + and learning to code on low-cost microcontroller boards. + .. _contents: @@ -312,8 +292,8 @@ Full table of contents versions contrib/index -.. _Buildbot status: https://www.python.org/dev/buildbot/ -.. _Misc directory: https://github.com/python/cpython/tree/main/Misc + +.. _Buildbot status: https://buildbot.python.org/ .. _PEPs: https://peps.python.org/ .. _python.org maintenance: https://pythondotorg.readthedocs.io/ .. _Python: https://www.python.org/ @@ -322,7 +302,6 @@ Full table of contents .. _GraalPy: https://www.graalvm.org/python/ .. _Jython: https://www.jython.org/ .. _IronPython: https://ironpython.net/ -.. _Stackless: https://github.com/stackless-dev/stackless/wiki/ .. _MicroPython: https://micropython.org/ .. _CircuitPython: https://circuitpython.org/ .. _Issue tracker: https://github.com/python/cpython/issues From 3158decf939c5cf26e059b110c8e7922fea73820 Mon Sep 17 00:00:00 2001 From: Seth Michael Larson <seth@python.org> Date: Thu, 5 Mar 2026 10:28:16 -0600 Subject: [PATCH 36/48] Add Petr Viktorin to PSRT (#1758) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Łukasz Langa <lukasz@langa.pl> --- developer-workflow/psrt.csv | 1 + 1 file changed, 1 insertion(+) diff --git a/developer-workflow/psrt.csv b/developer-workflow/psrt.csv index e21aac97b..2cfe5dbc4 100644 --- a/developer-workflow/psrt.csv +++ b/developer-workflow/psrt.csv @@ -12,6 +12,7 @@ Larry Hastings,larryhastings, Ned Deily,ned-deily,"Admin, Release Manager" Pablo Galindo Salgado,pablogsal,Release Manager Paul McMillan,paulmcmillan, +Petr Viktorin,encukou, Pradyun Gedam,pradyunsg, Savannah Ostrowski,savannahostrowski,Release Manager Serhiy Storchaka,serhiy-storchaka, From af6ec4fb8d8be2cee872bb550e6a1ae51ac636ca Mon Sep 17 00:00:00 2001 From: Seth Michael Larson <seth@python.org> Date: Thu, 5 Mar 2026 13:50:34 -0600 Subject: [PATCH 37/48] Add Stan Ulbrych to the PSRT (#1759) --- developer-workflow/psrt.csv | 1 + 1 file changed, 1 insertion(+) diff --git a/developer-workflow/psrt.csv b/developer-workflow/psrt.csv index 2cfe5dbc4..13b26f517 100644 --- a/developer-workflow/psrt.csv +++ b/developer-workflow/psrt.csv @@ -17,6 +17,7 @@ Pradyun Gedam,pradyunsg, Savannah Ostrowski,savannahostrowski,Release Manager Serhiy Storchaka,serhiy-storchaka, Seth Larson,sethmlarson,Admin +Stan Ulbrych,StanFromIreland, Steve Dower,zooba,Release Manager Thomas Wouters,Yhg1s,Release Manager Tim Peters,tim-one, From c6806606e98dbb7e719968745710fa9b5f5f325d Mon Sep 17 00:00:00 2001 From: Petr Viktorin <encukou@gmail.com> Date: Fri, 6 Mar 2026 14:40:52 +0100 Subject: [PATCH 38/48] Remove contrib/ (GH-1757) Add redirects, and remove the contrib/ directory. The current contents of contrib/ are available at https://github.com/python/devguide/tree/9f2df6d19ffe4b61cbd782bb6ccf037d05feb691/contrib. Ned's branch is at https://github.com/nedbat/devguide/tree/nedbat/contrib-refactor --- conf.py | 65 +++++++++--- contrib/code/developer-workflow.rst | 25 ----- contrib/code/development-tools.rst | 19 ---- contrib/code/git.rst | 11 -- contrib/code/index.rst | 30 ------ contrib/code/pull-request-lifecycle.rst | 21 ---- contrib/code/setup.rst | 12 --- contrib/code/testing.rst | 20 ---- contrib/contrib-plan.rst | 47 --------- contrib/core-team/committing.rst | 11 -- contrib/core-team/experts.rst | 10 -- contrib/core-team/index.rst | 24 ----- contrib/core-team/join-team.rst | 10 -- contrib/core-team/motivations.rst | 10 -- contrib/core-team/responsibilities.rst | 10 -- contrib/core-team/team-log.rst | 10 -- contrib/doc/devguide.rst | 12 --- contrib/doc/help-documenting.rst | 12 --- contrib/doc/index.rst | 29 ------ contrib/doc/markup.rst | 12 --- contrib/doc/pull-request-lifecycle.rst | 21 ---- contrib/doc/start-documenting.rst | 12 --- contrib/doc/style-guide.rst | 12 --- contrib/doc/translating.rst | 12 --- contrib/index.rst | 112 --------------------- contrib/intro/index.rst | 53 ---------- contrib/project/channels.rst | 16 --- contrib/project/conduct.rst | 16 --- contrib/project/directory-structure.rst | 17 ---- contrib/project/generative-ai.rst | 10 -- contrib/project/github.rst | 15 --- contrib/project/governance.rst | 25 ----- contrib/project/index.rst | 29 ------ contrib/project/outreach.rst | 12 --- contrib/project/roles.rst | 17 ---- contrib/security.rst | 13 --- contrib/triage/index.rst | 14 --- contrib/triage/issue-tracker.rst | 9 -- contrib/triage/labels.rst | 9 -- contrib/triage/reviewing.rst | 13 --- contrib/triage/triage-team.rst | 9 -- contrib/triage/triaging.rst | 9 -- contrib/user-success.rst | 14 --- contrib/workflows/codespaces.rst | 17 ---- contrib/workflows/compile.rst | 22 ---- contrib/workflows/get-source.rst | 19 ---- contrib/workflows/index.rst | 25 ----- contrib/workflows/install-dependencies.rst | 17 ---- contrib/workflows/install-git.rst | 17 ---- contrib/workflows/regenerate.rst | 28 ------ contrib/workflows/troubleshooting.rst | 17 ---- index.rst | 1 - 52 files changed, 50 insertions(+), 982 deletions(-) delete mode 100644 contrib/code/developer-workflow.rst delete mode 100644 contrib/code/development-tools.rst delete mode 100644 contrib/code/git.rst delete mode 100644 contrib/code/index.rst delete mode 100644 contrib/code/pull-request-lifecycle.rst delete mode 100644 contrib/code/setup.rst delete mode 100644 contrib/code/testing.rst delete mode 100644 contrib/contrib-plan.rst delete mode 100644 contrib/core-team/committing.rst delete mode 100644 contrib/core-team/experts.rst delete mode 100644 contrib/core-team/index.rst delete mode 100644 contrib/core-team/join-team.rst delete mode 100644 contrib/core-team/motivations.rst delete mode 100644 contrib/core-team/responsibilities.rst delete mode 100644 contrib/core-team/team-log.rst delete mode 100644 contrib/doc/devguide.rst delete mode 100644 contrib/doc/help-documenting.rst delete mode 100644 contrib/doc/index.rst delete mode 100644 contrib/doc/markup.rst delete mode 100644 contrib/doc/pull-request-lifecycle.rst delete mode 100644 contrib/doc/start-documenting.rst delete mode 100644 contrib/doc/style-guide.rst delete mode 100644 contrib/doc/translating.rst delete mode 100644 contrib/index.rst delete mode 100644 contrib/intro/index.rst delete mode 100644 contrib/project/channels.rst delete mode 100644 contrib/project/conduct.rst delete mode 100644 contrib/project/directory-structure.rst delete mode 100644 contrib/project/generative-ai.rst delete mode 100644 contrib/project/github.rst delete mode 100644 contrib/project/governance.rst delete mode 100644 contrib/project/index.rst delete mode 100644 contrib/project/outreach.rst delete mode 100644 contrib/project/roles.rst delete mode 100644 contrib/security.rst delete mode 100644 contrib/triage/index.rst delete mode 100644 contrib/triage/issue-tracker.rst delete mode 100644 contrib/triage/labels.rst delete mode 100644 contrib/triage/reviewing.rst delete mode 100644 contrib/triage/triage-team.rst delete mode 100644 contrib/triage/triaging.rst delete mode 100644 contrib/user-success.rst delete mode 100644 contrib/workflows/codespaces.rst delete mode 100644 contrib/workflows/compile.rst delete mode 100644 contrib/workflows/get-source.rst delete mode 100644 contrib/workflows/index.rst delete mode 100644 contrib/workflows/install-dependencies.rst delete mode 100644 contrib/workflows/install-git.rst delete mode 100644 contrib/workflows/regenerate.rst delete mode 100644 contrib/workflows/troubleshooting.rst diff --git a/conf.py b/conf.py index cd846dd04..0cb17ca74 100644 --- a/conf.py +++ b/conf.py @@ -179,6 +179,56 @@ "tracker.rst": "triage/issue-tracker.rst", "gh-labels.rst": "triage/labels.rst", "triaging.rst": "triage/triaging.rst", + # Contributing guide draft pages + "contrib/code/git.rst": "getting-started/git-boot-camp.rst", + "contrib/code/pull-request-lifecycle.rst": "getting-started/pull-request-lifecycle.rst", + "contrib/code/setup.rst": "getting-started/setup-building.rst", + "contrib/code/testing.rst": "testing/index.rst", + "contrib/code/developer-workflow.rst": "developer-workflow/index.rst", + "contrib/code/index.rst": "index.rst", + "contrib/code/development-tools.rst": "development-tools/index.rst", + "contrib/doc/devguide.rst": "documentation/devguide.rst", + "contrib/doc/help-documenting.rst": "documentation/help-documenting.rst", + "contrib/doc/markup.rst": "documentation/markup.rst", + "contrib/doc/pull-request-lifecycle.rst": "getting-started/pull-request-lifecycle.rst", + "contrib/doc/start-documenting.rst": "documentation/start-documenting.rst", + "contrib/doc/style-guide.rst": "documentation/style-guide.rst", + "contrib/doc/translating.rst": "documentation/translations/index.rst", + "contrib/doc/index.rst": "documentation/index.rst", + "contrib/intro/index.rst": "index.rst", + "contrib/project/channels.rst": "developer-workflow/communication-channels.rst", + "contrib/project/conduct.rst": "index.rst", + "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/outreach.rst": "index.rst", + "contrib/project/directory-structure.rst": "getting-started/setup-building.rst", + "contrib/project/index.rst": "index.rst", + "contrib/security.rst": "index.rst", + "contrib/triage/issue-tracker.rst": "triage/issue-tracker.rst", + "contrib/triage/labels.rst": "triage/labels.rst", + "contrib/triage/reviewing.rst": "triage/triaging.rst", + "contrib/triage/triage-team.rst": "triage/triage-team.rst", + "contrib/triage/triaging.rst": "triage/triaging.rst", + "contrib/triage/index.rst": "triage/index.rst", + "contrib/user-success.rst": "index.rst", + "contrib/core-team/committing.rst": "core-team/committing.rst", + "contrib/core-team/experts.rst": "core-team/experts.rst", + "contrib/core-team/index.rst": "core-team/index.rst", + "contrib/core-team/join-team.rst": "core-team/join-team.rst", + "contrib/core-team/motivations.rst": "core-team/motivations.rst", + "contrib/core-team/responsibilities.rst": "core-team/responsibilities.rst", + "contrib/core-team/team-log.rst": "core-team/team-log.rst", + "contrib/workflows/codespaces.rst": "getting-started/setup-building.rst", + "contrib/workflows/compile.rst": "getting-started/setup-building.rst", + "contrib/workflows/get-source.rst": "getting-started/setup-building.rst", + "contrib/workflows/index.rst": "getting-started/setup-building.rst", + "contrib/workflows/install-dependencies.rst": "getting-started/setup-building.rst", + "contrib/workflows/install-git.rst": "getting-started/setup-building.rst", + "contrib/workflows/regenerate.rst": "getting-started/setup-building.rst", + "contrib/workflows/troubleshooting.rst": "getting-started/setup-building.rst", + "contrib/index.rst": "index.rst", } intersphinx_mapping = { @@ -202,21 +252,6 @@ # prolog and epilogs rst_prolog = f""" -.. |draft| replace:: - This is part of a **Draft** of the Python Contributor's Guide. - Text in square brackets are notes about content to fill in. - Currently, the devguide and this new Contributor's Guide co-exist in the - repo. We are using Sphinx include directives to demonstrate the re-organization. - The final Contributor's Guide will replace the devguide with content in only one - place. - We welcome help with this! - -.. |purpose| replace:: - The :ref:`contrib-plan` page has more details about the current state of this draft - and **how you can help**. See more info about the Contributor Guide in the - discussion forum: `Refactoring the DevGuide`_. - -.. _Refactoring the DevGuide: https://discuss.python.org/t/refactoring-the-devguide-into-a-contribution-guide/63409 .. |main_version| replace:: {_main_version} diff --git a/contrib/code/developer-workflow.rst b/contrib/code/developer-workflow.rst deleted file mode 100644 index 416ca2c02..000000000 --- a/contrib/code/developer-workflow.rst +++ /dev/null @@ -1,25 +0,0 @@ -==================== -Development workflow -==================== - -.. important:: - - |draft| - - |purpose| - -[This is the existing :ref:`dev-workflow` page from the devguide] - -.. toctree:: - :maxdepth: 5 - - ../../developer-workflow/communication-channels - ../../developer-workflow/development-cycle - ../../developer-workflow/stdlib - ../../developer-workflow/extension-modules - ../../developer-workflow/c-api - ../../developer-workflow/lang-changes - ../../developer-workflow/grammar - ../../developer-workflow/porting - ../../developer-workflow/sbom - ../../developer-workflow/psrt diff --git a/contrib/code/development-tools.rst b/contrib/code/development-tools.rst deleted file mode 100644 index 769bba2b0..000000000 --- a/contrib/code/development-tools.rst +++ /dev/null @@ -1,19 +0,0 @@ -================= -Development tools -================= - -.. important:: - - |draft| - - |purpose| - -[This is the existing :ref:`development-tools` page from the devguide.] - -.. toctree:: - :maxdepth: 5 - - ../../development-tools/clinic/index - ../../development-tools/gdb - ../../development-tools/clang - ../../development-tools/warnings diff --git a/contrib/code/git.rst b/contrib/code/git.rst deleted file mode 100644 index 7c7aaa57b..000000000 --- a/contrib/code/git.rst +++ /dev/null @@ -1,11 +0,0 @@ -======== -Git tips -======== - -.. important:: - - |draft| - - |purpose| - -[More git help for advanced things needed by code contributors.] diff --git a/contrib/code/index.rst b/contrib/code/index.rst deleted file mode 100644 index 768095066..000000000 --- a/contrib/code/index.rst +++ /dev/null @@ -1,30 +0,0 @@ -.. _c_code: - -================== -Code contributions -================== - -.. important:: - - |draft| - - |purpose| - -[The main page for code contributors.] - -[We'll include code-focused content from the :ref:`main devguide page <devguide-main>`: Quick -reference, Quick links, Proposing changes, and so on.] - -[The existing :ref:`internals` section of the devguide will be fully -migrated into the Python repo.] - - -.. toctree:: - :maxdepth: 5 - - setup - git - pull-request-lifecycle - developer-workflow - testing - development-tools diff --git a/contrib/code/pull-request-lifecycle.rst b/contrib/code/pull-request-lifecycle.rst deleted file mode 100644 index 30c0fd590..000000000 --- a/contrib/code/pull-request-lifecycle.rst +++ /dev/null @@ -1,21 +0,0 @@ -.. _code-pull-request-lifecycle: - -====================== -Pull request lifecycle -====================== - -.. important:: - - |draft| - - |purpose| - - -[Details of pull requests for code contributions. The existing -:ref:`pull-request-lifecycle` page is long and includes many details. -Some only apply to code contributions, but many are common to all -contributions. Should we keep a common page, with extra steps here, or -should this page have all of the details even if they are duplicated -elsewhere?] - -[See :ref:`docs-pull-request-lifecycle` for the documentation half of this conundrum.] diff --git a/contrib/code/setup.rst b/contrib/code/setup.rst deleted file mode 100644 index 2d14bb0d9..000000000 --- a/contrib/code/setup.rst +++ /dev/null @@ -1,12 +0,0 @@ -================== -Setup and building -================== - -.. important:: - - |draft| - - |purpose| - -[More setup and build instructions specifically for code contributors, building -on the basics from the :ref:`Getting Started <getting-started>` section.] diff --git a/contrib/code/testing.rst b/contrib/code/testing.rst deleted file mode 100644 index 575d1477a..000000000 --- a/contrib/code/testing.rst +++ /dev/null @@ -1,20 +0,0 @@ -===================== -Testing and buildbots -===================== - -.. important:: - - |draft| - - |purpose| - -[This is the existing :ref:`testing` page from the devguide.] - -.. toctree:: - :maxdepth: 5 - - ../../testing/run-write-tests - ../../testing/silence-warnings - ../../testing/coverage - ../../testing/buildbots - ../../testing/new-buildbot-worker diff --git a/contrib/contrib-plan.rst b/contrib/contrib-plan.rst deleted file mode 100644 index 65e386e2b..000000000 --- a/contrib/contrib-plan.rst +++ /dev/null @@ -1,47 +0,0 @@ -.. _contrib-plan: - -================================== -[Plan for the Contributor's Guide] -================================== - -.. important:: - - |draft| - - |purpose| - -We are in the process of updating and refactoring the devguide to be a -Contributor's Guide. It will highlight the different kinds of contribution -possible, and how to succeed at each kind. - -Currently, the Contibutor's Guide is a draft in this new last section of the -devguide. We welcome feedback, but please understand that some of the current -content is moving or skeletal. - -Repo structure -============== - -While the reorganization is happening, we are keeping the old devguide as it -is. The new Contributor's Guide is represented in this last section, but will -eventually be the only content in the guide. To avoid copying content, we're -using Sphinx include directives to display existing devguide content in its new -Contributor's Guide location. That is not how the eventual Guide will be -built. Once we are ready to make the Contributor's Guide real, we will -rearrange content into its new location. - -How to help -=========== - -To help, you can: - -- `Write an issue`_ detailing a change you'd like to see here. -- `Make a pull request`_ in this repo to add content. -- Join us in the `Python Docs Discord`_ to collaborate with other docs-minded - community members. -- Get in touch with the `Docs Editorial Board`_ to discuss larger documentation - concerns. - -.. _Write an issue: https://github.com/python/devguide/issues -.. _Make a pull request: https://github.com/python/devguide/pulls -.. _Python Docs Discord: https://discord.gg/qcfPbnM2zH -.. _Docs Editorial Board: https://python.github.io/editorial-board/ diff --git a/contrib/core-team/committing.rst b/contrib/core-team/committing.rst deleted file mode 100644 index 5b639cd5a..000000000 --- a/contrib/core-team/committing.rst +++ /dev/null @@ -1,11 +0,0 @@ -.. important:: - - |draft| - - |purpose| - - -[This is the existing core developers :ref:`committing` page from the devguide. We'll -adjust "core developer" to "core team" where appropriate.] - -.. include:: ../../core-team/committing.rst diff --git a/contrib/core-team/experts.rst b/contrib/core-team/experts.rst deleted file mode 100644 index aa16f10bd..000000000 --- a/contrib/core-team/experts.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. important:: - - |draft| - - |purpose| - - -[This is the existing core team :ref:`experts` page from the devguide.] - -.. include:: ../../core-team/experts.rst diff --git a/contrib/core-team/index.rst b/contrib/core-team/index.rst deleted file mode 100644 index 2ca21344b..000000000 --- a/contrib/core-team/index.rst +++ /dev/null @@ -1,24 +0,0 @@ -.. important:: - - |draft| - - |purpose| - - -.. _c_core-team: - -========= -Core team -========= - -[This is mostly re-organized from the :ref:`core-team` section of the devguide] - -.. toctree:: - :maxdepth: 5 - - responsibilities - committing - experts - team-log - motivations - join-team diff --git a/contrib/core-team/join-team.rst b/contrib/core-team/join-team.rst deleted file mode 100644 index 932216f7c..000000000 --- a/contrib/core-team/join-team.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. important:: - - |draft| - - |purpose| - - -[This is the existing core team :ref:`join-core-team` page from the devguide.] - -.. include:: ../../core-team/join-team.rst diff --git a/contrib/core-team/motivations.rst b/contrib/core-team/motivations.rst deleted file mode 100644 index 38ba31023..000000000 --- a/contrib/core-team/motivations.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. important:: - - |draft| - - |purpose| - - -[This is the existing core team :ref:`motivations` page from the devguide.] - -.. include:: ../../core-team/motivations.rst diff --git a/contrib/core-team/responsibilities.rst b/contrib/core-team/responsibilities.rst deleted file mode 100644 index d6902bd78..000000000 --- a/contrib/core-team/responsibilities.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. important:: - - |draft| - - |purpose| - - -[This is the existing core team :ref:`responsibilities` page from the devguide.] - -.. include:: ../../core-team/responsibilities.rst diff --git a/contrib/core-team/team-log.rst b/contrib/core-team/team-log.rst deleted file mode 100644 index ecfe856a4..000000000 --- a/contrib/core-team/team-log.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. important:: - - |draft| - - |purpose| - - -[This is the existing core team :ref:`team-log` page from the devguide.] - -.. include:: ../../core-team/team-log.rst diff --git a/contrib/doc/devguide.rst b/contrib/doc/devguide.rst deleted file mode 100644 index 2c83e5200..000000000 --- a/contrib/doc/devguide.rst +++ /dev/null @@ -1,12 +0,0 @@ -================================== -Helping with the Developer's Guide -================================== - -.. important:: - - |draft| - - |purpose| - - -[This is the existing :ref:`devguide` page from the devguide.] diff --git a/contrib/doc/help-documenting.rst b/contrib/doc/help-documenting.rst deleted file mode 100644 index befb4b246..000000000 --- a/contrib/doc/help-documenting.rst +++ /dev/null @@ -1,12 +0,0 @@ -========================== -Helping with documentation -========================== - -.. important:: - - |draft| - - |purpose| - - -[This is the existing :ref:`help-documenting` page from the devguide.] diff --git a/contrib/doc/index.rst b/contrib/doc/index.rst deleted file mode 100644 index dc8ec9307..000000000 --- a/contrib/doc/index.rst +++ /dev/null @@ -1,29 +0,0 @@ -.. _c_docs: - -=========================== -Documentation contributions -=========================== - -.. important:: - - |draft| - - |purpose| - - -[The main page for documentation contributors.] - -[We'll include docs-focused content from the :ref:`main devguide page <devguide-main>`: Quick -reference, Quick links, and so on.] - - -.. toctree:: - :maxdepth: 5 - - start-documenting - help-documenting - style-guide - markup - pull-request-lifecycle - translating - devguide diff --git a/contrib/doc/markup.rst b/contrib/doc/markup.rst deleted file mode 100644 index 96b9faad5..000000000 --- a/contrib/doc/markup.rst +++ /dev/null @@ -1,12 +0,0 @@ -======================= -reStructuredText markup -======================= - -.. important:: - - |draft| - - |purpose| - - -[This is the existing :ref:`markup` page from the devguide.] diff --git a/contrib/doc/pull-request-lifecycle.rst b/contrib/doc/pull-request-lifecycle.rst deleted file mode 100644 index a62e63728..000000000 --- a/contrib/doc/pull-request-lifecycle.rst +++ /dev/null @@ -1,21 +0,0 @@ -.. _docs-pull-request-lifecycle: - -====================== -Pull request lifecycle -====================== - -.. important:: - - |draft| - - |purpose| - - -[Details of pull requests for documentation contributions. The existing -:ref:`pull-request-lifecycle` page is long and includes many details. -Some only apply to code contributions, but many are common to all -contributions. Should we keep a common page, with documentation tweaks here, or -should this page have only the documentation details even if they are duplicated -elsewhere?] - -[See :ref:`code-pull-request-lifecycle` for the code half of this conundrum.] diff --git a/contrib/doc/start-documenting.rst b/contrib/doc/start-documenting.rst deleted file mode 100644 index c5cf96161..000000000 --- a/contrib/doc/start-documenting.rst +++ /dev/null @@ -1,12 +0,0 @@ -=============== -Getting started -=============== - -.. important:: - - |draft| - - |purpose| - - -[This is the existing documentation :ref:`start-documenting` page from the devguide.] diff --git a/contrib/doc/style-guide.rst b/contrib/doc/style-guide.rst deleted file mode 100644 index 87762f3e0..000000000 --- a/contrib/doc/style-guide.rst +++ /dev/null @@ -1,12 +0,0 @@ -=========== -Style guide -=========== - -.. important:: - - |draft| - - |purpose| - - -[This is the existing documentation :ref:`style-guide` page from the devguide.] diff --git a/contrib/doc/translating.rst b/contrib/doc/translating.rst deleted file mode 100644 index baface2f0..000000000 --- a/contrib/doc/translating.rst +++ /dev/null @@ -1,12 +0,0 @@ -=========== -Translating -=========== - -.. important:: - - |draft| - - |purpose| - - -[This is the existing :ref:`translating` page from the devguide.] diff --git a/contrib/index.rst b/contrib/index.rst deleted file mode 100644 index 0e7c79ca1..000000000 --- a/contrib/index.rst +++ /dev/null @@ -1,112 +0,0 @@ -.. _c_root: - -================================== -Python Contributor's Guide (draft) -================================== - -.. include:: /include/activate-tab.rst - -.. important:: - - |draft| - - |purpose| - - -[Open question: how to divide content between this Introduction and the -:ref:`introduction <c_intro>`?] - -This guide is a comprehensive resource for :ref:`contributing <contributing>` -to Python_ -- for both new and experienced contributors. It is :ref:`maintained -<devguide>` by the same community that maintains Python. We welcome your -contributions to Python! - -We encourage everyone to contribute to Python. This guide should have -everything you need to get started and be productive. If you still have -questions after reviewing the material in this guide, the `Core Python -Mentorship`_ group is available to help you through the process. - -There are a number of ways to contribute including code, documentation, and -triaging issues. We've organized this guide to provide specifics based on the -type of activity you'll be engaged in. - - -Using this guide -================ - -We recommend reading this guide 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 this guide, be aware -that it is written assuming preceding sections have been read so you may need -to backtrack to fill in missing concepts and terminology. - -No matter what kind of contribution you'll be making, you should start with -these common sections: - -* :ref:`c_intro` -* :ref:`c_project` - -Then choose a path based on your type of activity: - -*[The original table on the devguide home had a fourth column for Core -Developers. That made the table wider and more confusing. I don't think core -team members need a quick intro path since they will have been through the -devguide before.]* - -*[I haven't adjusted the links in the table yet other than to add a link to the -major section at the top of each column.]* - -.. list-table:: - :widths: 10 10 10 - :header-rows: 1 - - * - :ref:`Documentation <c_docs>` - - :ref:`Code <c_code>` - - :ref:`Triaging <c_triage>` - * - - * :ref:`docquality` - * :ref:`documenting` - * :ref:`style-guide` - * :ref:`rst-primer` - * :ref:`translating` - * :ref:`devguide` - - - * :ref:`setup` - * :ref:`help` - * :ref:`pullrequest` - * :ref:`runtests` - * :ref:`fixingissues` - * :ref:`communication` - * :ref:`gitbootcamp` - * :ref:`devcycle` - - - * :ref:`tracker` - * :ref:`triaging` - * :ref:`helptriage` - * :ref:`experts` - * :ref:`labels` - * :ref:`gh-faq` - * :ref:`triage-team` - -Core team members will find guidance in the :ref:`c_core-team` section. - -Contents -======== - -.. toctree:: - :maxdepth: 3 - - contrib-plan - intro/index - project/index - triage/index - doc/index - code/index - core-team/index - user-success - security - workflows/index - - -.. _Python: https://www.python.org/ -.. _Core Python Mentorship: https://www.python.org/dev/core-mentorship/ diff --git a/contrib/intro/index.rst b/contrib/intro/index.rst deleted file mode 100644 index 98fa30fc3..000000000 --- a/contrib/intro/index.rst +++ /dev/null @@ -1,53 +0,0 @@ -.. _c_intro: - -============ -Introduction -============ - -.. important:: - - |draft| - - |purpose| - - - -[Open question: how to divide content between this Introduction and the -:ref:`home page <c_root>`?] - -Welcome! - -New to open source? -=================== - -Python is an open source project, with culture and techniques from the broader -open source world. You might find it helpful to read about open source in -general. A number of individuals from the Python community have contributed to -a series of excellent guides at `Open Source Guides -<https://opensource.guide/>`__. - -Anyone will find the following guides useful: - -* `How to Contribute to Open Source <https://opensource.guide/how-to-contribute/>`__ -* `Building Welcoming Communities <https://opensource.guide/building-community/>`__ - - -Healthy collaboration -===================== - -[Importance of healthy inclusive collaboration] - -[While code is a large part of the project's success, project management, documentation, governance, sprint outreach, etc. matter.] - -[We respect the individual skills people bring to the project and strive to create and maintain a culture of inclusion.] - -About this guide -================ - -Types of contribution -===================== - -[Pathways for contributors] - -Helping with this guide -======================= diff --git a/contrib/project/channels.rst b/contrib/project/channels.rst deleted file mode 100644 index 711dbe587..000000000 --- a/contrib/project/channels.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. important:: - - |draft| - - |purpose| - - -====================== -Communication channels -====================== - -* Repos -* Discourse -* Discord -* Mailing lists (deprioritize) -* Where to get help diff --git a/contrib/project/conduct.rst b/contrib/project/conduct.rst deleted file mode 100644 index 37fe3bbfa..000000000 --- a/contrib/project/conduct.rst +++ /dev/null @@ -1,16 +0,0 @@ -=============== -Code of Conduct -=============== - -.. important:: - - |draft| - - |purpose| - - -[Brief summary of the code of conduct, with links to official source.] - -* Standard for communication -* How to report -* Enforcement details diff --git a/contrib/project/directory-structure.rst b/contrib/project/directory-structure.rst deleted file mode 100644 index 0cebb25f7..000000000 --- a/contrib/project/directory-structure.rst +++ /dev/null @@ -1,17 +0,0 @@ -.. important:: - - |draft| - - |purpose| - -.. _c_directory_structure: - -=================== -Directory structure -=================== - -[This is the :ref:`build_directory_structure` section from the devguide.] - -.. include:: ../../getting-started/setup-building.rst - :start-after: c_directory_structure_start - :end-before: c_directory_structure_end diff --git a/contrib/project/generative-ai.rst b/contrib/project/generative-ai.rst deleted file mode 100644 index 6cb5b62ff..000000000 --- a/contrib/project/generative-ai.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. important:: - - |draft| - - |purpose| - - -[This is the existing :ref:`generative-ai` page from the devguide.] - -.. include:: ../../getting-started/generative-ai.rst diff --git a/contrib/project/github.rst b/contrib/project/github.rst deleted file mode 100644 index fe45c6b8b..000000000 --- a/contrib/project/github.rst +++ /dev/null @@ -1,15 +0,0 @@ -.. important:: - - |draft| - - |purpose| - -====== -GitHub -====== - -[Where are the actual artifacts?] - -* Main CPython repos -* Core workflow repos -* Infrastructure repos diff --git a/contrib/project/governance.rst b/contrib/project/governance.rst deleted file mode 100644 index a4bc66ff1..000000000 --- a/contrib/project/governance.rst +++ /dev/null @@ -1,25 +0,0 @@ -.. important:: - - |draft| - - |purpose| - - -========== -Governance -========== - -[How decisions are made, who is involved, how to participate.] - -Steering Council -================ - -Documentation Editorial Board -============================= - -Typing Council -============== - - -Others? -======= diff --git a/contrib/project/index.rst b/contrib/project/index.rst deleted file mode 100644 index 9d3c89b9a..000000000 --- a/contrib/project/index.rst +++ /dev/null @@ -1,29 +0,0 @@ -.. _c_project: - -=================== -The CPython project -=================== - -.. important:: - - |draft| - - |purpose| - - -[Give the reader an understanding of the project as a whole. What are the -moving parts, who is involved, how do they interact?] - -* Structure - -.. toctree:: - :maxdepth: 5 - - conduct - roles - governance - generative-ai.rst - github - directory-structure.rst - channels - outreach diff --git a/contrib/project/outreach.rst b/contrib/project/outreach.rst deleted file mode 100644 index d43aa8e9d..000000000 --- a/contrib/project/outreach.rst +++ /dev/null @@ -1,12 +0,0 @@ -======== -Outreach -======== - -.. important:: - - |draft| - - |purpose| - - -* Sprints diff --git a/contrib/project/roles.rst b/contrib/project/roles.rst deleted file mode 100644 index 8336fe465..000000000 --- a/contrib/project/roles.rst +++ /dev/null @@ -1,17 +0,0 @@ -===== -Roles -===== - -.. important:: - - |draft| - - |purpose| - - -[Quick overview of the roles people play. Core team has its own section.] - -* Core team -* Triager -* Contributors - * types of contributions diff --git a/contrib/security.rst b/contrib/security.rst deleted file mode 100644 index db40b4a16..000000000 --- a/contrib/security.rst +++ /dev/null @@ -1,13 +0,0 @@ -========================================= -Security and infrastructure contributions -========================================= - -.. important:: - - |draft| - - |purpose| - -* Security -* Infrastructure -* Core workflow diff --git a/contrib/triage/index.rst b/contrib/triage/index.rst deleted file mode 100644 index 0a547d9d7..000000000 --- a/contrib/triage/index.rst +++ /dev/null @@ -1,14 +0,0 @@ -.. _c_triage: - -=================== -Issues and triaging -=================== - -.. toctree:: - :maxdepth: 5 - - issue-tracker - triaging - labels - reviewing - triage-team diff --git a/contrib/triage/issue-tracker.rst b/contrib/triage/issue-tracker.rst deleted file mode 100644 index a5777bc81..000000000 --- a/contrib/triage/issue-tracker.rst +++ /dev/null @@ -1,9 +0,0 @@ -.. important:: - - |draft| - - |purpose| - -[This is the existing :ref:`issue-tracker` page from the devguide] - -.. include:: ../../triage/issue-tracker.rst diff --git a/contrib/triage/labels.rst b/contrib/triage/labels.rst deleted file mode 100644 index c36481733..000000000 --- a/contrib/triage/labels.rst +++ /dev/null @@ -1,9 +0,0 @@ -.. important:: - - |draft| - - |purpose| - -[This is the existing :ref:`labels` page from the devguide] - -.. include:: ../../triage/labels.rst diff --git a/contrib/triage/reviewing.rst b/contrib/triage/reviewing.rst deleted file mode 100644 index 060f6b78d..000000000 --- a/contrib/triage/reviewing.rst +++ /dev/null @@ -1,13 +0,0 @@ -.. important:: - - |draft| - - |purpose| - - -========= -Reviewing -========= - -* How? Etiquette? -* How to request a review? diff --git a/contrib/triage/triage-team.rst b/contrib/triage/triage-team.rst deleted file mode 100644 index a9b59056a..000000000 --- a/contrib/triage/triage-team.rst +++ /dev/null @@ -1,9 +0,0 @@ -.. important:: - - |draft| - - |purpose| - -[This is the existing :ref:`triage-team` page from the devguide] - -.. include:: ../../triage/triage-team.rst diff --git a/contrib/triage/triaging.rst b/contrib/triage/triaging.rst deleted file mode 100644 index 22e1ccc65..000000000 --- a/contrib/triage/triaging.rst +++ /dev/null @@ -1,9 +0,0 @@ -.. important:: - - |draft| - - |purpose| - -[This is the existing :ref:`triaging` page from the devguide] - -.. include:: ../../triage/triaging.rst diff --git a/contrib/user-success.rst b/contrib/user-success.rst deleted file mode 100644 index 2a9ef5d4e..000000000 --- a/contrib/user-success.rst +++ /dev/null @@ -1,14 +0,0 @@ -======================================= -Accessibility, design, and user success -======================================= - -.. important:: - - |draft| - - |purpose| - - -* Accessibility -* Design -* User success diff --git a/contrib/workflows/codespaces.rst b/contrib/workflows/codespaces.rst deleted file mode 100644 index eb97ef7c2..000000000 --- a/contrib/workflows/codespaces.rst +++ /dev/null @@ -1,17 +0,0 @@ -.. important:: - - |draft| - - |purpose| - -.. _c_using_codespaces: - -======================= -Using GitHub Codespaces -======================= - -[This is the :ref:`using-codespaces` section from the devguide.] - -.. include:: ../../getting-started/setup-building.rst - :start-after: c_codespaces_start - :end-before: c_codespaces_end diff --git a/contrib/workflows/compile.rst b/contrib/workflows/compile.rst deleted file mode 100644 index 18157b717..000000000 --- a/contrib/workflows/compile.rst +++ /dev/null @@ -1,22 +0,0 @@ -.. important:: - - |draft| - - |purpose| - -.. _c_compiling: - -================= -Compile and build -================= - -.. note:: - [This is the :ref:`compiling` section from the devguide. I think this page - is too long and could be split by build target, but we can leave that for a - later time.] - -.. include:: ../../getting-started/setup-building.rst - :start-after: c_compile_and_build_start - :end-before: c_compile_and_build_end - -.. include:: ../../links.rst diff --git a/contrib/workflows/get-source.rst b/contrib/workflows/get-source.rst deleted file mode 100644 index ed56fe4e1..000000000 --- a/contrib/workflows/get-source.rst +++ /dev/null @@ -1,19 +0,0 @@ -.. important:: - - |draft| - - |purpose| - -.. _c_checkout: - -=================== -Get the source code -=================== - -.. note:: - [This is the :ref:`checkout` section from the devguide. We might need to edit - it to clarify that some steps are only needed for code contribution.] - -.. include:: ../../getting-started/setup-building.rst - :start-after: c_get_source_code_start - :end-before: c_get_source_code_end diff --git a/contrib/workflows/index.rst b/contrib/workflows/index.rst deleted file mode 100644 index 2c6ccf2bc..000000000 --- a/contrib/workflows/index.rst +++ /dev/null @@ -1,25 +0,0 @@ -.. _c_workflows: - -========= -Workflows -========= - -.. important:: - - |draft| - - |purpose| - - -This section contains details of workflows needed for all kinds of -contribution. - -.. toctree:: - - install-git.rst - get-source.rst - install-dependencies.rst - compile.rst - regenerate.rst - troubleshooting.rst - codespaces.rst diff --git a/contrib/workflows/install-dependencies.rst b/contrib/workflows/install-dependencies.rst deleted file mode 100644 index 9a511c6da..000000000 --- a/contrib/workflows/install-dependencies.rst +++ /dev/null @@ -1,17 +0,0 @@ -.. important:: - - |draft| - - |purpose| - -.. _c_build-dependencies: - -==================== -Install Dependencies -==================== - -[This is the :ref:`build-dependencies` section from the devguide.] - -.. include:: ../../getting-started/setup-building.rst - :start-after: c_install_dependencies_start - :end-before: c_install_dependencies_end diff --git a/contrib/workflows/install-git.rst b/contrib/workflows/install-git.rst deleted file mode 100644 index e3d738b2a..000000000 --- a/contrib/workflows/install-git.rst +++ /dev/null @@ -1,17 +0,0 @@ -.. important:: - - |draft| - - |purpose| - -.. _c_vcsetup: - -=========== -Install Git -=========== - -[This is the :ref:`vcsetup` section from the devguide.] - -.. include:: ../../getting-started/setup-building.rst - :start-after: c_install_git_start - :end-before: c_install_git_end diff --git a/contrib/workflows/regenerate.rst b/contrib/workflows/regenerate.rst deleted file mode 100644 index b5bca7dca..000000000 --- a/contrib/workflows/regenerate.rst +++ /dev/null @@ -1,28 +0,0 @@ -.. important:: - - |draft| - - |purpose| - -.. _c_regenerating: - -=============================== -Regenerating auto-created files -=============================== - -.. note:: - [These are two similar sections from the is the :ref:`setup-building` section from the devguide.] - -Regenerate ``configure`` -======================== - -.. include:: ../../getting-started/setup-building.rst - :start-after: c_regenerate_configure_start - :end-before: c_regenerate_configure_end - -Regenerate the ABI dump -======================= - -.. include:: ../../getting-started/setup-building.rst - :start-after: c_regenerate_abi_start - :end-before: c_regenerate_abi_end diff --git a/contrib/workflows/troubleshooting.rst b/contrib/workflows/troubleshooting.rst deleted file mode 100644 index 68aa80158..000000000 --- a/contrib/workflows/troubleshooting.rst +++ /dev/null @@ -1,17 +0,0 @@ -.. important:: - - |draft| - - |purpose| - -.. _c_build_troubleshooting: - -=========== -Install Git -=========== - -[This is the :ref:`build_troubleshooting` section from the devguide.] - -.. include:: ../../getting-started/setup-building.rst - :start-after: c_build_troubleshooting_start - :end-before: c_build_troubleshooting_end diff --git a/index.rst b/index.rst index 1c15d824d..18aca244e 100644 --- a/index.rst +++ b/index.rst @@ -290,7 +290,6 @@ Full table of contents core-team/index internals versions - contrib/index .. _Buildbot status: https://buildbot.python.org/ From cf022dfcc89579a9fa5240ab0432fd8eb226692f Mon Sep 17 00:00:00 2001 From: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> Date: Fri, 6 Mar 2026 20:27:22 +0000 Subject: [PATCH 39/48] Remove `:platform:` doc, add `.. availability::` (GH-1744) --- documentation/markup.rst | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/documentation/markup.rst b/documentation/markup.rst index 24f359bb1..863fe3444 100644 --- a/documentation/markup.rst +++ b/documentation/markup.rst @@ -357,11 +357,10 @@ module being documented. Each module should be documented in its own file. Normally this markup appears after the title heading of that file; a typical file might start like this:: - :mod:`parrot` -- Dead parrot access - =================================== + :mod:`!parrot` -- Dead parrot access + ==================================== .. module:: parrot - :platform: Unix, Windows :synopsis: Analyze and reanimate dead parrots. .. describe:: module @@ -370,12 +369,6 @@ file might start like this:: or submodule. The name should be fully qualified (that is, including the package name for submodules). - The ``platform`` option, if present, is a comma-separated list of the - platforms on which the module is available (if it is available on all - platforms, the option should be omitted). The keys are short identifiers; - examples that are in use include "IRIX", "Mac", "Windows", and "Unix". It is - important to use a key which has already been used when applicable. - The ``synopsis`` option should consist of one sentence describing the module's purpose -- it is currently only used in the Global Module Index. @@ -1030,6 +1023,17 @@ Paragraph-level markup These directives create short paragraphs and can be used inside information units as well as normal text: +.. describe:: availability + + This directive documents the platforms on which a module or feature + is available. For example:: + + .. availability:: Unix, not WASI, not Android. + + :: + + .. availability:: Linux >= 3.0 with glibc >= 2.14. + .. describe:: note An especially important bit of information about an API that a user should be From 7c37b966115ff935f9a87a227f247dbb5ae054ad Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Sun, 8 Mar 2026 00:16:49 +0200 Subject: [PATCH 40/48] Update mailing list links (#1741) --- developer-workflow/c-api.rst | 5 ++--- developer-workflow/communication-channels.rst | 9 ++++----- 2 files changed, 6 insertions(+), 8 deletions(-) diff --git a/developer-workflow/c-api.rst b/developer-workflow/c-api.rst index e7f129a27..427d9fd96 100644 --- a/developer-workflow/c-api.rst +++ b/developer-workflow/c-api.rst @@ -395,9 +395,8 @@ If following these guidelines would hurt performance, add a fast function API. If anything is unclear, or you have a good reason to break the guidelines, -consider discussing the change at the `capi-sig`_ mailing list. - -.. _capi-sig: https://mail.python.org/mailman3/lists/capi-sig.python.org/ +consider discussing the change in the `C API category +<https://discuss.python.org/c/core-dev/c-api/>`__ on Discourse. Adding a new definition to the Limited API ------------------------------------------ diff --git a/developer-workflow/communication-channels.rst b/developer-workflow/communication-channels.rst index 43c00b9e1..78fbf21df 100644 --- a/developer-workflow/communication-channels.rst +++ b/developer-workflow/communication-channels.rst @@ -51,7 +51,7 @@ Mailing lists .. _python-committers: https://mail.python.org/mailman3/lists/python-committers.python.org/ .. _python-dev: https://mail.python.org/mailman3/lists/python-dev.python.org/ - .. _python-ideas: https://mail.python.org/mailman3/lists/python-ideas.python.org + .. _python-ideas: https://mail.python.org/archives/list/python-ideas@python.org/ General Python questions should go to `python-list`_ or `tutor`_ or similar resources, such as `Stack Overflow`_ or the ``#python`` IRC channel @@ -62,13 +62,12 @@ issue tracker is the place to discuss and work on improvements to the CPython core development workflow. A complete list of Python mailing lists can be found at -https://mail.python.org/mailman/listinfo (older lists, using Mailman2) or -https://mail.python.org/mailman3/ (newer lists, using Mailman3). Some lists may also +https://mail.python.org/mailman3/. Some lists may also be mirrored at `GMANE <https://gmane.io/>`__ and can be read and posted to in various ways, including via web browsers, NNTP newsreaders, and RSS feed readers. -.. _python-list: https://mail.python.org/mailman/listinfo/python-list -.. _tutor: https://mail.python.org/mailman/listinfo/tutor +.. _python-list: https://mail.python.org/mailman3/lists/python-list.python.org/ +.. _tutor: https://mail.python.org/mailman3/lists/tutor.python.org/ .. _Stack Overflow: https://stackoverflow.com/ .. _Libera.Chat: https://libera.chat/ From fb62ccd1bdf528a226391ed0177ddbe03b028462 Mon Sep 17 00:00:00 2001 From: Petr Viktorin <encukou@gmail.com> Date: Mon, 9 Mar 2026 13:13:57 +0100 Subject: [PATCH 41/48] Version chart: Add a border for the planned branch (#1763) --- _tools/release_cycle_template.svg.jinja | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/_tools/release_cycle_template.svg.jinja b/_tools/release_cycle_template.svg.jinja index 9f23814a9..ffc54919e 100644 --- a/_tools/release_cycle_template.svg.jinja +++ b/_tools/release_cycle_template.svg.jinja @@ -26,6 +26,9 @@ width: 100%; --blob-border-width: 1.6px; + + --status-bg-color: #CCC; + --status-border-color: #888; } .background { fill: var(--svg-color-background-primary); @@ -88,6 +91,9 @@ --status-bg-color: #2222EE; --status-border-color: #008888; } + .release-cycle-status-planned { + /* Use grey defaults */ + } .release-cycle-blob { fill: var(--status-bg-color); stroke: transparent; From 5a4dd49489218f87808c090520cd09e07aba82dc Mon Sep 17 00:00:00 2001 From: Seth Michael Larson <seth@python.org> Date: Mon, 9 Mar 2026 10:18:14 -0500 Subject: [PATCH 42/48] Add Emma Smith to the PSRT (GH-1764) --- developer-workflow/psrt.csv | 1 + 1 file changed, 1 insertion(+) diff --git a/developer-workflow/psrt.csv b/developer-workflow/psrt.csv index 13b26f517..81147eb29 100644 --- a/developer-workflow/psrt.csv +++ b/developer-workflow/psrt.csv @@ -3,6 +3,7 @@ Benjamin Peterson,benjaminp, Donald Stufft,dstufft, Dustin Ingram,di, Ee Durbin,ewdurbin,Admin +Emma Smith,emmatyping, Glyph Lefkowitz,glyph, Gregory P. Smith,gpshead, Hugo van Kemenade,hugovk,Release Manager From 24b0b24df7a5fac832a6e1be86c698c5b152bc26 Mon Sep 17 00:00:00 2001 From: Ned Batchelder <ned@nedbatchelder.com> Date: Thu, 12 Mar 2026 10:10:46 -0400 Subject: [PATCH 43/48] update the link guidance now that we suppress them automatically (#1762) Also use linklint on the devguide itself. --- conf.py | 1 + documentation/style-guide.rst | 13 +++++++------ requirements.txt | 1 + 3 files changed, 9 insertions(+), 6 deletions(-) diff --git a/conf.py b/conf.py index 0cb17ca74..1d8893722 100644 --- a/conf.py +++ b/conf.py @@ -3,6 +3,7 @@ from urllib.request import urlopen extensions = [ + 'linklint.ext', 'notfound.extension', 'sphinx.ext.extlinks', 'sphinx.ext.intersphinx', diff --git a/documentation/style-guide.rst b/documentation/style-guide.rst index 4d2ca0d70..5ca2960ce 100644 --- a/documentation/style-guide.rst +++ b/documentation/style-guide.rst @@ -193,18 +193,19 @@ 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. -Do not use a link when the link would point to the current unit. It's natural -to use the name of a function in the documentation for the function, but a link -on that function name that simply reloads the section the user is already -reading is useless and distracting. +We use the :pypi:`linklint Sphinx extension <linklint>` 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. Do not use links in section headers. They distract from the title of the section. The term will be mentioned in the paragraph text and can be linked from there. -Sphinx provides ways to automatically add links to references, and a way to +Sphinx automatically adds links to references, and provides a way to suppress the link. Using roles like ``:func:`map``` will link to the -documentation for ``map``. You can suppress the link while keeping the +documentation for ``map``. If automatic link suppression isn't enough, +you can suppress the link while keeping the semantic presentation of the function name by adding an exclamation point prefix: ``:func:`!map```. See :ref:`roles` for more details. diff --git a/requirements.txt b/requirements.txt index 7c2bbd806..3b40508f6 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,5 +1,6 @@ furo>=2022.6.4 jinja2 +linklint sphinx-autobuild>=2024.9.19 sphinx-inline-tabs>=2023.4.21 sphinx-lint==1.0.2 From f2d8b2e64e40e4b38a0a3ed867c4fc2c387cf443 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Date: Fri, 13 Mar 2026 06:24:25 -0400 Subject: [PATCH 44/48] Move inactive experts to emeritus status (#1635) Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> --- core-team/experts.rst | 323 +++++++++++++++++++++++++++++++++--------- 1 file changed, 258 insertions(+), 65 deletions(-) diff --git a/core-team/experts.rst b/core-team/experts.rst index 1a1643c1c..5ed9c7441 100644 --- a/core-team/experts.rst +++ b/core-team/experts.rst @@ -24,9 +24,6 @@ Unless a name is followed by a '*', you should never assign an issue to that person. Names followed by a '*' may be assigned issues involving the module or topic. -Names followed by a '^' indicate old bugs.python.org usernames, for people -that did not transition to GitHub. - The Platform and Interest Area tables list broader fields in which various people have expertise. These people can also be contacted for help, opinions, and decisions when issues involve their areas. @@ -71,10 +68,10 @@ calendar cmath cmd code -codecs malemburg, doerwalter +codecs malemburg codeop collections rhettinger* -collections.abc rhettinger*, stutzbach^ +collections.abc rhettinger* colorsys compileall carljm compression.bz2 @@ -82,27 +79,27 @@ compression.gzip compression.lzma compression.zlib Yhg1s, gpshead*, emmatyping compression.zstd emmatyping* -concurrent.futures pitrou, brianquinlan, gpshead* +concurrent.futures pitrou, gpshead* configparser ambv* contextlib ncoghlan, 1st1 contextvars -copy avassalotti, serhiy-storchaka* -copyreg avassalotti, serhiy-storchaka* +copy serhiy-storchaka* +copyreg serhiy-storchaka* cProfile -csv smontanaro (inactive), serhiy-storchaka* -ctypes theller (inactive), abalkin, amauryfa, meadori +csv serhiy-storchaka* +ctypes curses Yhg1s dataclasses ericvsmith*, carljm -datetime abalkin, pganssle +datetime pganssle dbm decimal facundobatista, rhettinger -difflib tim-one (inactive) +difflib dis 1st1 -doctest tim-one (inactive) -email warsaw, bitdancer*, maxking +doctest +email warsaw, bitdancer* encodings malemburg ensurepip ncoghlan, dstufft, pradyunsg, pfmoore -enum eliben*, warsaw, ethanfurman* +enum warsaw, ethanfurman* errno Yhg1s faulthandler vstinner, gpshead, ZeroIntensity* fcntl Yhg1s @@ -120,20 +117,18 @@ gettext tomasr8 glob serhiy-storchaka* grp hashlib tiran, gpshead*, picnixz -heapq rhettinger*, stutzbach^ +heapq rhettinger* hmac tiran, gpshead*, picnixz html ezio-melotti* http -idlelib kbkaiser (inactive), terryjreedy*, serwy (inactive), - taleinat +idlelib terryjreedy*, taleinat imaplib importlib brettcannon, FFY00* inspect 1st1 -io benjaminp, stutzbach^ -ipaddress pmoody^ +io benjaminp +ipaddress itertools rhettinger* -json etrepum (inactive), ezio-melotti, rhettinger, - serhiy-storchaka* +json ezio-melotti, rhettinger, serhiy-storchaka* keyword libmpdec linecache @@ -141,29 +136,29 @@ locale malemburg logging vsajip mailbox marshal -math rhettinger, stutzbach^ +math rhettinger mimetypes mmap Yhg1s -modulefinder theller (inactive), jvr^, FFY00 +modulefinder FFY00 msvcrt -multiprocessing applio*, pitrou, jnoller^ (inactive), sbt^ (inactive), gpshead* +multiprocessing pitrou, gpshead* netrc numbers operator -optparse mitsuhiko, serhiy-storchaka* +optparse serhiy-storchaka* os os.path serhiy-storchaka* parser pablogsal pathlib barneygale* pdb gaogaotiantian -pickle avassalotti, serhiy-storchaka* -pickletools avassalotti, serhiy-storchaka* +pickle serhiy-storchaka* +pickletools serhiy-storchaka* pkgutil FFY00* platform malemburg plistlib poplib posix larryhastings, gpshead -pprint freddrake +pprint profile pstats pty Yhg1s* @@ -183,65 +178,65 @@ runpy ncoghlan, FFY00 sched secrets select -selectors neologix^, giampaolo +selectors giampaolo shelve shlex -shutil tarekziade, giampaolo +shutil giampaolo signal gpshead site FFY00* smtplib socket gpshead socketserver -sqlite3 ghaering^, erlend-aasland* -ssl jackjansen, tiran, dstufft, alex +sqlite3 erlend-aasland* +ssl tiran, dstufft, alex stat tiran -statistics stevendaprano, rhettinger +statistics rhettinger string stringprep -struct meadori -subprocess astrand^ (inactive), giampaolo, gpshead* +struct +subprocess giampaolo, gpshead* symtable benjaminp sys sysconfig FFY00* -syslog jafo^* -tabnanny tim-one (inactive) -tarfile gustaebel +syslog +tabnanny +tarfile tempfile serhiy-storchaka* termios Yhg1s test ezio-melotti, serhiy-storchaka* textwrap threading pitrou, gpshead -time abalkin, pganssle +time pganssle timeit -tkinter gpolo^, serhiy-storchaka* +tkinter serhiy-storchaka* token -tokenize meadori +tokenize tomllib hauntsaninja* -trace abalkin +trace traceback iritkatriel tracemalloc vstinner tty Yhg1s* -turtle gregorlingl^, willingc +turtle willingc turtledemo terryjreedy* types 1st1 typing gvanrossum, JelleZijlstra*, AlexWaygood*, carljm, sobolevn* unicodedata malemburg, ezio-melotti -unittest ezio-melotti, rbtcollins, gpshead, serhiy-storchaka* +unittest ezio-melotti, gpshead, serhiy-storchaka* unittest.mock urllib orsenthil uuid venv vsajip, FFY00* warnings wave -weakref freddrake, nascheme +weakref nascheme webbrowser -winreg stutzbach^ +winreg winsound -wsgiref pjenvey +wsgiref xml.dom xml.dom.minidom xml.dom.pulldom -xml.etree eliben*, scoder +xml.etree scoder xml.parsers.expat xml.sax xml.sax.handler @@ -249,7 +244,7 @@ xml.sax.saxutils xml.sax.xmlreader xmlrpc zipapp pfmoore -zipfile alanmcintyre^, serhiy-storchaka, Yhg1s, gpshead +zipfile serhiy-storchaka, Yhg1s, gpshead zipimport Yhg1s* zoneinfo pganssle ==================== ============================================= @@ -284,16 +279,11 @@ Platform Maintainers =================== =========== AIX ayappanec Android mhsmith -Cygwin jlt63^, stutzbach^ Emscripten hoodmane, pmp-p, rdb, rth, ryanking13 -FreeBSD -HP-UX iOS freakboy3742, ned-deily -JVM/Java frank.wierzbicki^ Linux macOS ronaldoussoren, ned-deily, freakboy3742 NetBSD1 -OS2/EMX aimacintyre^ Solaris/OpenIndiana jcea, kulikjak Windows tjguk, zooba, pfmoore =================== =========== @@ -324,30 +314,30 @@ documentation ezio-melotti, merwok, JulienPalard, willingc, hugovk, AA-Turner, AlexWaygood* emoji Mariatta extension modules encukou, ncoghlan, FFY00 -filesystem giampaolo +filesystem frozen modules ericsnowcurrently, gvanrossum, kumaraditya303, FFY00 f-strings ericvsmith* GUI i18n malemburg, merwok, tomasr8 import machinery brettcannon, ncoghlan, ericsnowcurrently, FFY00* initialization FFY00* -io benjaminp, stutzbach^, gpshead +io benjaminp, gpshead JIT brandtbucher*, savannahostrowski* locale malemburg -mathematics malemburg, stutzbach^, rhettinger, serhiy-storchaka +mathematics malemburg, rhettinger, serhiy-storchaka memory management tim-one, malemburg, Yhg1s, nascheme memoryview -networking giampaolo, gpshead +networking gpshead object model benjaminp, Yhg1s -packaging tarekziade, malemburg, alexis^, merwok, dstufft, pfmoore, emmatyping, FFY00 +packaging malemburg, merwok, dstufft, pfmoore, emmatyping, FFY00 pattern matching brandtbucher* PEG parser gvanrossum, pablogsal, lysnikolaou performance vstinner, serhiy-storchaka*, 1st1, rhettinger, markshannon, brandtbucher, carljm, Fidget-Spinner, AlexWaygood*, nascheme -pip ncoghlan, dstufft, pfmoore, Marcus.Smith^, pradyunsg -release management tarekziade, malemburg, benjaminp, warsaw, - gvanrossum, anthonybaxter^, merwok, ned-deily, - birkenfeld, JulienPalard, hugovk +pip ncoghlan, dstufft, pfmoore, pradyunsg +release management malemburg, benjaminp, warsaw, + gvanrossum, merwok, ned-deily, + JulienPalard, hugovk runtime lifecycle ericsnowcurrently, kumaraditya303, zooba, ZeroIntensity, nascheme, FFY00 str.format ericvsmith* subinterpreters ericsnowcurrently, kumaraditya303, ZeroIntensity* @@ -355,12 +345,215 @@ symbol table JelleZijlstra, carljm testing ezio-melotti test coverage threads gpshead -time and dates malemburg, abalkin, pganssle +time and dates malemburg, pganssle Unicode malemburg, ezio-melotti, benjaminp version control merwok, ezio-melotti ================== ========================================================== +Experts Emeritus +================ + +Names followed by a '^' indicate old bugs.python.org usernames, for people +that did not transition to GitHub. + +Stdlib +------ + +.. list-table:: + + * - Module + - Expert + + * - codecs + - doerwalter + + * - collections.abc + - stutzbach^ + + * - concurrent.futures + - brianquinlan + + * - copy + - avassalotti + + * - copyreg + - avassalotti + + * - csv + - smontanaro + + * - ctypes + - theller, abalkin, amauryfa, meadori + + * - datetime + - abalkin + + * - difflib + - tim-one + + * - doctest + - tim-one + + * - email + - maxking + + * - enum + - eliben + + * - heapq + - stutzbach + + * - idlelib + - kbkaiser, serwy + + * - io + - stutzbach^ + + * - ipaddress + - pmoody^ + + * - json + - etrepum + + * - math + - stutzbach^ + + * - modulefinder + - theller, jvr^ + + * - multiprocessing + - applio, jnoller^, sbt^ + + * - optparse + - mitsuhiko + + * - pickle + - avassalotti + + * - pickletools + - avassalotti + + * - pprint + - freddrake + + * - selectors + - neologix^ + + * - shutil + - tarekziade + + * - sqlite3 + - ghaering^ + + * - ssl + - jackjansen + + * - statistics + - stevendaprano + + * - struct + - meadori + + * - subprocess + - astrand^ + + * - syslog + - jafo^ + + * - tabnanny + - tim-one + + * - tarfile + - gustaebel + + * - time + - abalkin + + * - tkinter + - gpolo^ + + * - tokenize + - meadori + + * - trace + - abalkin + + * - turtle + - gregorlingl^ + + * - unittest + - rbtcollins + + * - weakref + - freddrake + + * - winreg + - stutzbach^ + + * - wsgiref + - pjenvey + + * - xml.etree + - eliben + + * - zipfile + - alanmcintyre^ + +Platforms +--------- + +.. list-table:: + + * - Platform + - Expert + + * - AIX + - edelsohn + + * - Cygwin + - jlt63^, stutzbach^ + + * - JVM/Java + - frank.wierzbicki^ + + * - OS2/EMX + - aimacintyre^ + + +Miscellaneous +------------- + +.. list-table:: + + * - Interest Area + - Expert + + * - filesystem + - giampaolo + + * - io + - stutzbach^ + + * - mathematics + - stutzbach^ + + * - networking + - giampaolo + + * - packaging + - tarekziade, alexis^ + + * - pip + - Marcus.Smith^ + + * - release management + - tarekziade, anthonybaxter^, birkenfeld + + * - time and dates + - abalkin + + Documentation translations ========================== From a290d108f7238ff9be77a0518b3a5030e11186fe Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Fri, 13 Mar 2026 17:59:27 +0200 Subject: [PATCH 45/48] Remove modules with no expert (#1766) * Remove modules with no expert * Sentence case headers * Flip order: positive first --- core-team/experts.rst | 96 ++----------------------------------------- 1 file changed, 4 insertions(+), 92 deletions(-) diff --git a/core-team/experts.rst b/core-team/experts.rst index 5ed9c7441..87d3ba4c7 100644 --- a/core-team/experts.rst +++ b/core-team/experts.rst @@ -20,9 +20,9 @@ following is added to an issue or pull request, they will be notified automatically. The :cpy-file:`.github/CODEOWNERS` file is also used to indicate maintainers that will be automatically added as reviewers to pull requests. +Names followed by a '*' may be assigned issues involving the module or topic. Unless a name is followed by a '*', you should never assign an issue to -that person. Names followed by a '*' may be assigned issues involving the -module or topic. +that person. The Platform and Interest Area tables list broader fields in which various people have expertise. These people can also be contacted for help, @@ -49,53 +49,29 @@ Stdlib ==================== ============================================= Module Maintainers ==================== ============================================= -__future__ __main__ gvanrossum, ncoghlan -_thread -abc annotationlib JelleZijlstra* argparse savannahostrowski*, serhiy-storchaka* -array ast benjaminp, pablogsal, isidentical, JelleZijlstra, eclips4 asyncio 1st1, asvetlov, gvanrossum, graingert, kumaraditya303, willingc -atexit -base64 -bdb -binascii bisect rhettinger* -builtins -calendar -cmath -cmd -code codecs malemburg -codeop collections rhettinger* collections.abc rhettinger* -colorsys compileall carljm -compression.bz2 -compression.gzip -compression.lzma compression.zlib Yhg1s, gpshead*, emmatyping compression.zstd emmatyping* concurrent.futures pitrou, gpshead* configparser ambv* contextlib ncoghlan, 1st1 -contextvars copy serhiy-storchaka* copyreg serhiy-storchaka* -cProfile csv serhiy-storchaka* -ctypes curses Yhg1s dataclasses ericvsmith*, carljm datetime pganssle -dbm decimal facundobatista, rhettinger -difflib dis 1st1 -doctest email warsaw, bitdancer* encodings malemburg ensurepip ncoghlan, dstufft, pradyunsg, pfmoore @@ -103,50 +79,31 @@ enum warsaw, ethanfurman* errno Yhg1s faulthandler vstinner, gpshead, ZeroIntensity* fcntl Yhg1s -filecmp -fileinput fnmatch serhiy-storchaka* -fractions ftplib giampaolo* functools rhettinger* gc pitrou, pablogsal, nascheme getopt serhiy-storchaka* getpath FFY00* -getpass gettext tomasr8 glob serhiy-storchaka* -grp hashlib tiran, gpshead*, picnixz heapq rhettinger* hmac tiran, gpshead*, picnixz html ezio-melotti* -http idlelib terryjreedy*, taleinat -imaplib importlib brettcannon, FFY00* inspect 1st1 io benjaminp -ipaddress itertools rhettinger* json ezio-melotti, rhettinger, serhiy-storchaka* -keyword -libmpdec -linecache locale malemburg logging vsajip -mailbox -marshal math rhettinger -mimetypes mmap Yhg1s modulefinder FFY00 -msvcrt multiprocessing pitrou, gpshead* -netrc -numbers -operator optparse serhiy-storchaka* -os os.path serhiy-storchaka* parser pablogsal pathlib barneygale* @@ -155,64 +112,36 @@ pickle serhiy-storchaka* pickletools serhiy-storchaka* pkgutil FFY00* platform malemburg -plistlib -poplib posix larryhastings, gpshead -pprint -profile -pstats pty Yhg1s* -pwd py_compile carljm pyclbr isidentical pydoc AA-Turner, serhiy-storchaka* queue rhettinger* -quopri random rhettinger re ezio-melotti, serhiy-storchaka* readline Yhg1s -reprlib resource Yhg1s -rlcompleter runpy ncoghlan, FFY00 -sched -secrets -select selectors giampaolo -shelve -shlex shutil giampaolo signal gpshead site FFY00* -smtplib socket gpshead -socketserver sqlite3 erlend-aasland* ssl tiran, dstufft, alex stat tiran statistics rhettinger -string -stringprep -struct subprocess giampaolo, gpshead* symtable benjaminp -sys sysconfig FFY00* -syslog -tabnanny -tarfile tempfile serhiy-storchaka* termios Yhg1s test ezio-melotti, serhiy-storchaka* -textwrap threading pitrou, gpshead time pganssle -timeit tkinter serhiy-storchaka* -token -tokenize tomllib hauntsaninja* -trace traceback iritkatriel tracemalloc vstinner tty Yhg1s* @@ -222,27 +151,10 @@ types 1st1 typing gvanrossum, JelleZijlstra*, AlexWaygood*, carljm, sobolevn* unicodedata malemburg, ezio-melotti unittest ezio-melotti, gpshead, serhiy-storchaka* -unittest.mock urllib orsenthil -uuid venv vsajip, FFY00* -warnings -wave weakref nascheme -webbrowser -winreg -winsound -wsgiref -xml.dom -xml.dom.minidom -xml.dom.pulldom xml.etree scoder -xml.parsers.expat -xml.sax -xml.sax.handler -xml.sax.saxutils -xml.sax.xmlreader -xmlrpc zipapp pfmoore zipfile serhiy-storchaka, Yhg1s, gpshead zipimport Yhg1s* @@ -293,7 +205,7 @@ Miscellaneous ============= ================== ========================================================== -Interest Area Maintainers +Interest area Maintainers ================== ========================================================== algorithms rhettinger*, serhiy-storchaka argument clinic larryhastings, AlexWaygood*, erlend-aasland, @@ -351,7 +263,7 @@ version control merwok, ezio-melotti ================== ========================================================== -Experts Emeritus +Experts emeritus ================ Names followed by a '^' indicate old bugs.python.org usernames, for people From a235d1ab8b03d164ac31a26c4127c0df7295fb05 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> Date: Fri, 13 Mar 2026 18:00:15 +0000 Subject: [PATCH 46/48] Add PSRT emeritus table (#1767) --- .github/CODEOWNERS | 2 +- developer-workflow/psrt-emeritus.csv | 0 developer-workflow/psrt.rst | 14 ++++++++++++++ 3 files changed, 15 insertions(+), 1 deletion(-) create mode 100644 developer-workflow/psrt-emeritus.csv diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index eba83ca39..06213bdf4 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 +developer-workflow/psrt*.csv @warsaw @ewdurbin @ned-deily @sethmlarson diff --git a/developer-workflow/psrt-emeritus.csv b/developer-workflow/psrt-emeritus.csv new file mode 100644 index 000000000..e69de29bb diff --git a/developer-workflow/psrt.rst b/developer-workflow/psrt.rst index 543e09358..dee901726 100644 --- a/developer-workflow/psrt.rst +++ b/developer-workflow/psrt.rst @@ -15,6 +15,8 @@ list of members and admins, included in the table below: :file: psrt.csv :encoding: "utf-8" +See also the :ref:`members emeritus list <psrt-members-emeritus>`. + How can I join the PSRT? ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -268,3 +270,15 @@ please feel free to adapt them as needed for the current context. * https://www.cve.org/CVERecord?id={CVE-YYYY-XXXX} * {pull request URL} + +.. _psrt-members-emeritus: + +Members emeritus +---------------- + +Members who have previously served on the PSRT. + +.. csv-table:: + :header: "Name", "GitHub username", "Notes" + :file: psrt-emeritus.csv + :encoding: "utf-8" From 7d2a93dd57f6c62eb74768df47c380fec8cf49e8 Mon Sep 17 00:00:00 2001 From: stratakis <cstratak@redhat.com> Date: Tue, 17 Mar 2026 13:43:17 +0100 Subject: [PATCH 47/48] Overhaul buildbot worker setup documentation (GH-1761) Re-read and verify the current docs after setting up the aarch64 buildbots again: Rewrite the Linux buildbot worker setup instructions with per-distro nested tabs Add recommended buildbot.tac settings, FreeBSD rc.d instructions, and pip/manual setup for distros without available buildbot packages. Plus some minor fixups for other OSes. --- testing/new-buildbot-worker.rst | 432 ++++++++++++++++++++++++-------- 1 file changed, 325 insertions(+), 107 deletions(-) diff --git a/testing/new-buildbot-worker.rst b/testing/new-buildbot-worker.rst index 8c3f99acb..aea43a782 100644 --- a/testing/new-buildbot-worker.rst +++ b/testing/new-buildbot-worker.rst @@ -60,28 +60,219 @@ Setting up the buildbot worker Conventional always-on machines ------------------------------- -You need a recent version of the `buildbot <https://buildbot.net/>`__ software, -and you will probably want a separate 'buildbot' user to run the buildbot -software. You may also want to set the buildbot up using a virtual -environment, depending on how you manage your system. We won't cover how to that -here; it doesn't differ from setting up a virtual environment for any other -software, but you'll need to modify the sequence of steps below as appropriate -if you choose that path. +You need a recent version of the `buildbot <https://buildbot.net/>`__ worker +software. On most platforms the distribution's package manager provides the +``buildbot-worker`` package, which also creates a dedicated service account, +systemd unit (or equivalent), and the necessary directories. For platforms +where no package exists, ``pip install buildbot-worker`` is the fallback, but +you will need to create the service account, directories, and service unit +manually. You may also want to set the buildbot up using a virtual +environment, depending on how you manage your system; you'll need to adjust +the steps below as appropriate if you choose that path. .. tab:: Linux - * If your package manager provides the buildbot worker software, that is - probably the best way to install it; it may create the buildbot user for - you, in which case you can skip the next step. Otherwise, do ``pip install - buildbot-worker`` or ``pip3 install buildbot-worker``. - * Create a ``buildbot`` user (using, eg: ``useradd``) if necessary. - * Log in as the buildbot user. + .. tab:: Fedora / RHEL / CentOS - In a terminal window for the buildbot user, issue the following commands (you - can put the ``buildarea`` wherever you want to):: + **Fedora**:: - mkdir buildarea - buildbot-worker create-worker buildarea buildbot-api.python.org:9020 workername workerpasswd + dnf install buildbot-worker + + **RHEL 8** (requires EPEL):: + + subscription-manager repos --enable codeready-builder-for-rhel-8-$(arch)-rpms + dnf install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm + dnf install buildbot-worker + + **RHEL 9** (requires EPEL):: + + subscription-manager repos --enable codeready-builder-for-rhel-9-$(arch)-rpms + dnf install https://dl.fedoraproject.org/pub/epel/epel-release-latest-9.noarch.rpm + dnf install buildbot-worker + + **CentOS Stream 9 / 10** (requires CRB + EPEL):: + + dnf config-manager --set-enabled crb + dnf install epel-release epel-next-release + dnf install buildbot-worker + + The RPM creates a ``buildbot-worker`` system user, installs a + templated systemd unit ``buildbot-worker@.service``, and creates + ``/var/lib/buildbot/worker/`` as the base directory for worker + instances. + + .. tip:: + + If your system has most of its disk space on ``/home`` rather than + on the root partition, create the worker data under ``/home`` and + symlink it so the packaged systemd unit still works:: + + mkdir -p /home/buildbot-worker/worker + ln -s /home/buildbot-worker/worker /var/lib/buildbot/worker + + Adjust ownership and paths to match your distro's conventions. + + Create the worker (replace ``WORKERNAME`` and ``WORKERPASSWD`` with + the credentials provided to you from your buildmaster-config issue):: + + sudo -u buildbot-worker buildbot-worker create-worker \ + /var/lib/buildbot/worker/WORKERNAME \ + buildbot-api.python.org:9020 WORKERNAME WORKERPASSWD + + Edit ``info/admin``, ``info/host``, and ``buildbot.tac`` in the worker + directory (see below for recommended settings). + + Enable and start the service:: + + systemctl enable --now buildbot-worker@WORKERNAME.service + + .. tab:: Debian / Ubuntu + + :: + + apt install buildbot-worker + + The package creates a ``buildbot`` system user, installs a templated + systemd unit ``buildbot-worker@.service``, and creates + ``/var/lib/buildbot/workers/`` as the base directory for worker + instances. + + .. tip:: + + If your system has most of its disk space on ``/home`` rather than + on the root partition, create the worker data under ``/home`` and + symlink it so the packaged systemd unit still works:: + + mkdir -p /home/buildbot/workers + ln -s /home/buildbot/workers /var/lib/buildbot/workers + + Adjust ownership and paths to match your distro's conventions. + + Create the worker (replace ``WORKERNAME`` and ``WORKERPASSWD`` with + the credentials provided to you from your buildmaster-config issue):: + + sudo -u buildbot buildbot-worker create-worker \ + /var/lib/buildbot/workers/WORKERNAME \ + buildbot-api.python.org:9020 WORKERNAME WORKERPASSWD + + Edit ``info/admin``, ``info/host``, and ``buildbot.tac`` in the worker + directory (see below for recommended settings). + + Enable and start the service:: + + systemctl enable --now buildbot-worker@WORKERNAME.service + + .. tab:: Other / pip + + For distros without a ``buildbot-worker`` package, install via pip:: + + pip install buildbot-worker + + **NixOS** users should use the built-in ``services.buildbot-worker`` + NixOS module; see the + `nixpkgs module source <https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/services/continuous-integration/buildbot/worker.nix>`__ + for available options. + + **Arch Linux** has buildbot packages in the AUR, but they are + currently unmaintained. Using pip is more reliable. + + pip does **not** create a system user, directories, or service unit. + Set these up manually. On distros with ``useradd``:: + + useradd --system --shell /sbin/nologin \ + --home-dir /var/lib/buildbot/worker --create-home buildbot-worker + + On Alpine Linux (BusyBox):: + + adduser -S -D -H -h /var/lib/buildbot/worker -s /sbin/nologin buildbot-worker + + Then create the directories:: + + mkdir -p /var/lib/buildbot/worker + chown buildbot-worker:buildbot-worker /var/lib/buildbot/worker + + Create the worker (replace ``WORKERNAME`` and ``WORKERPASSWD`` with + the credentials provided to you from your buildmaster-config issue):: + + sudo -u buildbot-worker buildbot-worker create-worker \ + /var/lib/buildbot/worker/WORKERNAME \ + buildbot-api.python.org:9020 WORKERNAME WORKERPASSWD + + Edit ``info/admin``, ``info/host``, and ``buildbot.tac`` in the worker + directory (see below for recommended settings). + + On systemd-based distros, a service unit must also be installed; see + the service management section below. + + +.. tab:: Unix + + .. tab:: FreeBSD + + :: + + pkg install devel/py-buildbot-worker + + The package creates a ``buildbot`` system user, installs an + ``rc.d`` service with profile support, and creates + ``/var/db/buildbot/workers/`` as the base directory for worker + instances. + + Create the worker (replace ``WORKERNAME`` and ``WORKERPASSWD`` with + the credentials provided to you from your buildmaster-config issue):: + + su -m buildbot -c "buildbot-worker create-worker \ + /var/db/buildbot/workers/WORKERNAME \ + buildbot-api.python.org:9020 WORKERNAME WORKERPASSWD" + + Edit ``info/admin``, ``info/host``, and ``buildbot.tac`` in the worker + directory (see below for recommended settings). + + Enable and start the service. The rc.d script uses profile names as + shell variable identifiers, so pick a short name without hyphens + (it does not need to match the worker name):: + + sysrc buildbot_worker_enable=YES + sysrc buildbot_worker_profiles="myworker" + sysrc buildbot_worker_myworker_enable=YES + sysrc buildbot_worker_myworker_basedir=/var/db/buildbot/workers/WORKERNAME + service buildbot-worker start + + .. tab:: OpenBSD + + :: + + pkg_add buildbot-worker + + The package creates a ``_buildslave`` system user, installs an + ``rc.d`` service, and creates ``/var/buildslave/`` as the default + worker directory. + + Create the worker (replace ``WORKERNAME`` and ``WORKERPASSWD`` with + the credentials provided to you from your buildmaster-config issue):: + + su -m _buildslave -c "buildbot-worker create-worker \ + /var/buildslave \ + buildbot-api.python.org:9020 WORKERNAME WORKERPASSWD" + + Edit ``info/admin``, ``info/host``, and ``buildbot.tac`` in the worker + directory (see below for recommended settings). + + Enable and start the service:: + + rcctl enable buildbot_worker + rcctl start buildbot_worker + + The ``rc.d`` script supports a single worker. To run multiple + workers, create each in a subdirectory and point the service flags + at the desired one (or create additional ``rc.d`` scripts):: + + su -m _buildslave -c "buildbot-worker create-worker \ + /var/buildslave/WORKERNAME \ + buildbot-api.python.org:9020 WORKERNAME WORKERPASSWD" + rcctl enable buildbot_worker + rcctl set buildbot_worker flags /var/buildslave/WORKERNAME + rcctl start buildbot_worker .. tab:: macOS @@ -95,7 +286,7 @@ if you choose that path. can put the ``buildarea`` wherever you want to):: mkdir buildarea - buildbot-worker create-worker buildarea buildbot-api.python.org:9020 workername workerpasswd + buildbot-worker create-worker buildarea buildbot-api.python.org:9020 WORKERNAME WORKERPASSWD .. tab:: Windows @@ -129,89 +320,124 @@ if you choose that path. .. code-block:: mkdir buildarea - buildbot-worker create-worker buildarea buildbot-api.python.org:9020 workername workerpasswd + buildbot-worker create-worker buildarea buildbot-api.python.org:9020 WORKERNAME WORKERPASSWD + + +The ``info/admin`` file in the worker directory should contain your contact +information, and ``info/host`` should describe the host configuration. This +information is displayed on the buildbot web interface. Since these pages are +publicly visible, consider obfuscating your email address (for example, +``user AT example.com``) to avoid spam from web scrapers. + +The recommended ``buildbot.tac`` settings are: + +* ``keepalive = 60`` -- the buildmaster uses a 60-second keepalive interval; + the default of ``600`` is too high and can cause spurious disconnections. +* ``delete_leftover_dirs = 1`` -- automatically cleans up build directories + that the master no longer needs. +.. tip:: -Once this initial worker setup completes, you should edit the files -``buildarea/info/admin`` and ``buildarea/info/host`` to provide your contact -info and information on the host configuration, respectively. This information -will be presented in the buildbot web pages that display information about the -builders running on your worker. + Build directories and ``twistd.log`` rotations can accumulate over time. + Monitor free disk space on the partition that holds the worker directory, + even with ``delete_leftover_dirs`` enabled. + +Service management +~~~~~~~~~~~~~~~~~~ You will also want to make sure that the worker is started when the machine reboots: .. tab:: Linux - * For systemd based distributions, you can create a systemd unit file in order - to manage the service. Create the unit file named ``buildbot-worker.service`` - under ``/home/buildbot/.config/systemd/user/`` and change the paths according to where the - buildbot-worker binary resides. You can verify its location by running - ``which buildbot-worker``. - If you installed the buildbot-worker through - your package manager it would be:: + .. tab:: Distro package + + If you installed via a distro package (Fedora, RHEL, CentOS, Debian, + or Ubuntu), the service was already enabled in the installation + step above. + + .. tab:: Manual systemd + + If you installed via pip, you need to install a systemd unit yourself. + The upstream buildbot project provides a + `contributed template unit <https://github.com/buildbot/buildbot/blob/master/worker/contrib/systemd/buildbot-worker%40.service>`__ + along with + `sysusers.d and tmpfiles.d configs <https://github.com/buildbot/buildbot/tree/master/common/contrib/systemd>`__. + + Create ``/etc/systemd/system/buildbot-worker@.service`` with the + following contents:: - [Unit] - Description=Buildbot Worker - Wants=network-online.target - After=network-online.target local-fs.target + [Unit] + Description=Buildbot Worker %i + Documentation=man:buildbot-worker(1) https://docs.buildbot.net/ + After=network.target + ConditionDirectoryNotEmpty=/var/lib/buildbot/worker/%i + ConditionFileNotEmpty=/var/lib/buildbot/worker/%i/buildbot.tac - [Service] - Type=forking - PIDFile=/home/buildbot/buildarea/twistd.pid - WorkingDirectory=/home/buildbot/buildarea - ExecStart=/usr/bin/buildbot-worker start - ExecReload=/usr/bin/buildbot-worker restart - ExecStop=/usr/bin/buildbot-worker stop - Restart=always - User=buildbot + [Service] + Type=simple + User=buildbot-worker + Group=buildbot-worker + WorkingDirectory=/var/lib/buildbot/worker/ + StateDirectory=buildbot/worker + ExecStart=/usr/local/bin/buildbot-worker start --nodaemon %i + Restart=always + ProtectSystem=full + ProtectHome=yes + PrivateDevices=yes + PrivateTmp=yes - [Install] - WantedBy=multi-user.target + [Install] + WantedBy=multi-user.target + Adjust ``User``, ``Group``, ``WorkingDirectory``, and the + ``ExecStart`` path to match your setup. If your worker data is + symlinked from ``/home`` (see the filesystem layout tip above), + change ``ProtectHome=yes`` to ``ProtectHome=no`` so systemd can + follow the symlink. Then:: - If you installed the buildbot-worker through pip, the systemd unit - file should look like this:: + systemctl daemon-reload + systemctl enable --now buildbot-worker@WORKERNAME.service - [Unit] - Description=Buildbot Worker - Wants=network-online.target - After=network-online.target local-fs.target + .. tab:: SysV init - [Service] - Type=forking - PIDFile=/home/buildbot/buildarea/twistd.pid - WorkingDirectory=/home/buildbot/buildarea - ExecStart=/usr/local/bin/buildbot-worker start - ExecReload=/usr/local/bin/buildbot-worker restart - ExecStop=/usr/local/bin/buildbot-worker stop - Restart=always - User=buildbot + For distros without systemd (such as Alpine Linux with OpenRC), + upstream provides a + `SysV init script <https://github.com/buildbot/buildbot/blob/master/worker/contrib/init-scripts/buildbot-worker.init.sh>`__ + with a + `default configuration file <https://github.com/buildbot/buildbot/blob/master/worker/contrib/init-scripts/buildbot-worker.default>`__. + Install these as ``/etc/init.d/buildbot-worker`` and + ``/etc/default/buildbot-worker`` respectively, then configure the + worker instances in the default file. - [Install] - WantedBy=multi-user.target + .. tab:: cron job + If neither systemd nor a SysV init script is practical, you can use + a cron job. Add the following line to ``/etc/crontab``:: - Then enable lingering for the buildbot user via the - ``loginctl enable-linger buildbot`` command and you can start - the service through a login shell of the buildbot user - via the ``systemctl --user enable --now buildbot-worker.service`` - command. + @reboot buildbot-worker restart /path/to/workerdir - Note that using a systemd unit file, might produce some SELinux warnings on systems - where the enforcing mode is enabled, usually related to the ``twistd.pid`` file. - If the service fails to start, you should check the output of - ``systemctl status buildbot-worker.service`` as well as the - ``/var/log/audit/audit.log`` file (for example, through - ``sealert -a /var/log/audit/audit.log``) for potential issues and remedies. + Note that ``restart`` is used rather than ``start`` in case a crash + has left a ``twistd.pid`` file behind. - * Alternatively you can create a cronjob. Add the following line to ``/etc/crontab``:: +.. tab:: Unix - @reboot buildbot-worker restart /path/to/buildarea + If you installed via a package on FreeBSD or OpenBSD, the service + was already enabled in the installation step above. To manage it + manually: - Note that we use ``restart`` rather than ``start`` in case a crash has - left a ``twistd.pid`` file behind. + On FreeBSD:: + service buildbot-worker status + service buildbot-worker restart + + On OpenBSD:: + + rcctl check buildbot_worker + rcctl restart buildbot_worker + + If you installed via pip, you will need to write an ``rc.d`` script + or use the cron job approach described in the Linux tab. .. tab:: macOS @@ -222,14 +448,11 @@ machine reboots: * Place the following script, named ``run_worker.sh``, into that directory:: #!/bin/bash - export PATH=/usr/local/bin:/Library/Frameworks/Python.framework/Versions/2.7/bin:$PATH + export PATH=/usr/local/bin:/Library/Frameworks/Python.framework/Versions/Current/bin:$PATH export LC_CTYPE=en_US.utf-8 cd /Users/buildbot/buildarea twistd --nodaemon --python=buildbot.tac --logfile=buildbot.log --prefix=worker - If you use pip with Apple's system python, add '/System' to the front of - the path to the Python bin directory. - * Place a file with the following contents into ``/Library/LaunchDaemons``: .. code-block:: xml @@ -274,9 +497,10 @@ machine reboots: service as described in the `buildbot documentation <https://docs.buildbot.net/current/manual/installation/misc.html#launching-worker-as-windows-service>`__. -To start the worker running for your initial testing, you can do:: +If you have not already started the worker through a service manager, you +can start it manually for initial testing:: - buildbot-worker start buildarea + buildbot-worker start /path/to/workerdir Then you can either wait for someone to make a commit, or you can pick a builder associated with your worker from the `list of builders @@ -288,13 +512,7 @@ by tests that fail. Unfortunately we do not currently have a way to notify you only of failures on your builders, so doing periodic spot checks is also a good idea. -.. note:: - If your buildbot worker is disconnecting regularly, it may be a symptom of the - default ``keepalive`` value (``600`` for 10 minutes) being `set - <https://docs.buildbot.net/latest/manual/installation/worker.html#cmdoption-buildbot-worker-create-worker-keepalive>`__ - too high. You can change it to a lower value (for example, ``180`` for 3 minutes) - in the ``buildbot.tac`` file found in your build area. - +---- Latent workers -------------- @@ -357,7 +575,7 @@ Necessary tasks include, obviously, keeping the buildbot running. Currently the system for notifying buildbot owners when their workers go offline is not working; this is something we hope to resolve. So currently it is helpful if you periodically check the status of your worker. We will also contact you -via your contact address in ``buildarea/info/admin`` when we notice there is a +via your contact address in ``info/admin`` when we notice there is a problem that has not been resolved for some period of time and you have not responded to a posting on the python-buildbots list about it. @@ -386,19 +604,19 @@ a table listing all of the outbound ports used by the buildbot and the python test suite (this list may not be complete as new tests may have been added since this table was last vetted): -======= =================== ================================================ -Port Host Description -======= =================== ================================================ -20, 21 ftp.debian.org test_urllib2net -53 your DNS server test_socket, and others implicitly -80 python.org (several tests) +======= ========================== ================================================ +Port Host Description +======= ========================== ================================================ +20, 21 ftp.debian.org test_urllib2net +53 your DNS server test_socket, and others implicitly +80 python.org (several tests) example.com -119 news.gmane.org test_nntplib (Python versions < 3.13) -443 (various) test_ssl -465 smtp.gmail.com test_smtpnet -587 smtp.gmail.com test_smtpnet -9020 python.org connection to buildmaster -======= =================== ================================================ +119 news.gmane.org test_nntplib (Python versions < 3.13) +443 (various) test_ssl +465 smtp.gmail.com test_smtpnet +587 smtp.gmail.com test_smtpnet +9020 buildbot-api.python.org connection to buildmaster +======= ========================== ================================================ Many tests will also create local TCP sockets and connect to them, usually using either ``localhost`` or ``127.0.0.1``. @@ -417,9 +635,9 @@ buildbot are at least: * 30 GB free disk space Many tests won't run in this configuration, since they require -substantially more memory, but these resources should be sufficient to ensure -that Python compiles correctly on the platform and can run part of the test -suite. +substantially more memory, but these resources should be sufficient. +Builders with minimal settings might need more maintenance: they check +that Python's resource-hungry tests are tagged and skipped correctly. Security considerations From 7a807ebce5194615d449dbae781dc6fb405df333 Mon Sep 17 00:00:00 2001 From: Seth Michael Larson <seth@python.org> Date: Wed, 18 Mar 2026 14:30:39 -0500 Subject: [PATCH 48/48] Fill PSRT emeritus list (#1768) --- developer-workflow/psrt-emeritus.csv | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/developer-workflow/psrt-emeritus.csv b/developer-workflow/psrt-emeritus.csv index e69de29bb..f9d26bfba 100644 --- a/developer-workflow/psrt-emeritus.csv +++ b/developer-workflow/psrt-emeritus.csv @@ -0,0 +1,10 @@ +Anthony Baxter,,Release Manager +Christian Heimes,tiran, +Georg Brandl,birkenfeld, +Huzaifa Sidhpurwala,, +Jesse Noller,, +Kushal Das,kushaldas, +Mark Hammond,mhammond, +Nam Nguyen,, +Neal Norwitz,, +Trent Mick,,