diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 06213bdf40..9c2d9d9e4a 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -5,4 +5,4 @@ # https://git-scm.com/docs/gitignore#_pattern_format # PSRT member list owned by PSRT admins. -developer-workflow/psrt*.csv @warsaw @ewdurbin @ned-deily @sethmlarson +security/psrt*.csv @warsaw @ewdurbin @ned-deily @sethmlarson diff --git a/.readthedocs.yml b/.readthedocs.yml index 26e5be9672..3e13033540 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -13,9 +13,14 @@ build: tools: python: "3" - commands: - - asdf plugin add uv - - asdf install uv latest - - asdf global uv latest - - make dirhtml BUILDDIR=_readthedocs - - mv _readthedocs/dirhtml _readthedocs/html + jobs: + post_checkout: + - git fetch --unshallow || true + build: + html: + - asdf plugin add uv + - asdf install uv latest + - asdf global uv latest + - make dirhtml BUILDDIR=_readthedocs + - mkdir -p $READTHEDOCS_OUTPUT + - mv _readthedocs/dirhtml $READTHEDOCS_OUTPUT/html diff --git a/conf.py b/conf.py index 1d88937227..fb032b895c 100644 --- a/conf.py +++ b/conf.py @@ -10,10 +10,13 @@ 'sphinx.ext.todo', 'sphinx_copybutton', 'sphinx_inline_tabs', + 'sphinx_last_updated_by_git', 'sphinxext.opengraph', 'sphinxext.rediraffe', ] +html_last_updated_fmt = '%b %d, %Y' + # The master toctree document. master_doc = 'index' @@ -147,6 +150,9 @@ "langchanges.rst": "developer-workflow/lang-changes.rst", "porting.rst": "developer-workflow/porting.rst", "stdlibchanges.rst": "developer-workflow/stdlib.rst", + # Security + "developer-workflow/psrt.rst": "security/psrt.rst", + "developer-workflow/sbom.rst": "security/sbom.rst", # Documentation "docquality.rst": "documentation/help-documenting.rst", "documenting.rst": "documentation/start-documenting.rst", @@ -160,6 +166,7 @@ "gitbootcamp.rst": "getting-started/git-boot-camp.rst", "pullrequest.rst": "getting-started/pull-request-lifecycle.rst", "setup.rst": "getting-started/setup-building.rst", + "getting-started/generative-ai.rst": "getting-started/ai-tools.rst", # CPython Internals "compiler.rst": "internals.rst", "exploring.rst": "internals.rst", @@ -202,7 +209,7 @@ "contrib/project/github.rst": "index.rst", "contrib/project/governance.rst": "index.rst", "contrib/project/roles.rst": "index.rst", - "contrib/project/generative-ai.rst": "getting-started/generative-ai.rst", + "contrib/project/generative-ai": "getting-started/ai-tools.rst", "contrib/project/outreach.rst": "index.rst", "contrib/project/directory-structure.rst": "getting-started/setup-building.rst", "contrib/project/index.rst": "index.rst", diff --git a/core-team/committing.rst b/core-team/committing.rst index c606df3839..1209d6ae1e 100644 --- a/core-team/committing.rst +++ b/core-team/committing.rst @@ -35,7 +35,7 @@ to enter the public source tree. Ask yourself the following questions: Check :ref:`pull-request-lifecycle` and :ref:`helptriage` to review what is expected of a pull request. -* **Does the change break backwards-compatibility without a strong reason?** +* **Does the change break backwards compatibility without a strong reason?** :ref:`Run the entire test suite ` to make sure that everything still passes. If there is a change to the semantics, then there needs to be a strong reason, because it will cause some peoples' code to break. @@ -79,6 +79,31 @@ to enter the public source tree. Ask yourself the following questions: :ref:`what-s-new-and-news-entries` +Merging the pull request +------------------------ + +Once the pull request is ready, you (the core team member) can merge it. +If other people have been substantially involved in the review, it can be good +to wait for their approval even if a core team member has already approved the +pull request. + +The CPython repo is configured to only accept squashes. You will squash the +pull request. + +Commit message +^^^^^^^^^^^^^^ + +GitHub defaults the squashed commit message to a combined list of all of the +individual commit messages in the pull request. Do not leave those. They often +are too noisy and provide little context, especially since devs know their +work will be eventually squashed, so intermediate commit messages while +working on the pull request are not interesting. + +If you think it is important, you can summarize the collaborative work that +went into the pull request, but it is not necessary. The pull request and/or +original issue are still available for detailed investigations of history. + + Working with Git_ ----------------- diff --git a/core-team/core-team.csv b/core-team/core-team.csv index 46dfd81530..b7f25e1618 100644 --- a/core-team/core-team.csv +++ b/core-team/core-team.csv @@ -1,3 +1,4 @@ +Chris Eibl,chris-eibl,2026-05-10,, Stan Ulbrych,StanFromIreland,2026-03-26,, Itamar Oren,itamaro,2026-02-16,, Emma Smith,emmatyping,2025-07-31,, diff --git a/core-team/motivations.rst b/core-team/motivations.rst index d0e5a0cc18..7babb5f7da 100644 --- a/core-team/motivations.rst +++ b/core-team/motivations.rst @@ -115,7 +115,7 @@ participating in the CPython core development process: As a core team member, she is primarily interested in helping to ensure Python's continued suitability for educational, testing and data analysis use cases, as well as in encouraging good architectural practices when assembling Python - applications and test harnesses from open source components. + applications and test harnesses from open-source components. Note: prior to August 2023, Alyssa used her birth name (Nick Coghlan). Some records (for example, mailing list archives, version control history) will still reference that name. @@ -175,14 +175,14 @@ participating in the CPython core development process: available, working on the infrastructure that supports CPython development, specifically the Roundup-based bug tracker and the buildbot system. - David currently does both proprietary and open source development work, + David currently does both proprietary and open-source development work, primarily in Python, through the company in which he is a partner, `Murray & Walker, Inc `__. He has done contract work focused specifically on CPython development both through the PSF (the kickstart of the email Unicode API development) and directly funded by interested corporations (additional development work on email funded by QNX, and work on CPython ICC support funded by Intel). He would like to - spend more of his (and his company's) time on open source work, and so is + spend more of his (and his company's) time on open-source work, and so is actively seeking additional such contract opportunities. .. topic:: Antoine Pitrou (France) @@ -202,7 +202,7 @@ participating in the CPython core development process: concurrent programming. As a professional, Antoine has been first specializing in network - programming, and more lately in open source data science infrastructure. + programming, and more lately in open-source data science infrastructure. He has made numerous contributions to Numba, Dask and is currently working full time on Apache Arrow as a technical leader at QuantStack. @@ -269,7 +269,7 @@ participating in the CPython core development process: Carol is focused on Python's usage in education and scientific research. She is interested in distributed computing, organizational development, - operational workflows, and sustainability of open source projects. + operational workflows, and sustainability of open-source projects. .. _goals-of-the-motivations-page: @@ -282,7 +282,7 @@ strongly suggest that the current core development process is bottlenecked on core team time. This is most clearly indicated in the first metrics graph, which shows both the number of open issues and the number of pull requests awaiting review growing steadily over time, despite CPython being one of the most -active open source projects in the world. This bottleneck then impacts not only +active open-source projects in the world. This bottleneck then impacts not only resolving open issues and accepting submitted pull requests, but also the process of identifying, nominating and mentoring new core team members. diff --git a/core-team/responsibilities.rst b/core-team/responsibilities.rst index 9f5c62b728..130e763d56 100644 --- a/core-team/responsibilities.rst +++ b/core-team/responsibilities.rst @@ -123,7 +123,7 @@ to better assess the sustainability of current contributions to CPython core development, and also serves as a referral list for organisations seeking commercial Python support from the core development community. -And finally, enjoy yourself! Contributing to open source software should be fun +And finally, enjoy yourself! Contributing to open-source software should be fun (overall). If you find yourself no longer enjoying the work then either take a break or figure out what you need to do to make it enjoyable again. diff --git a/developer-workflow/communication-channels.rst b/developer-workflow/communication-channels.rst index 78fbf21dff..101bb06122 100644 --- a/developer-workflow/communication-channels.rst +++ b/developer-workflow/communication-channels.rst @@ -22,6 +22,38 @@ in return. .. _Diversity Statement: https://www.python.org/psf/diversity/ +.. _multicultural-communication: + +Communicating across cultures and languages +=========================================== + +Not every contributor writes English as a first language, and phrasing that +feels neutral in one culture can read as blunt or rude in another. + +**Practice active listening.** Try to focus on understanding the message before reacting. + +**Confirm understanding.** Ask open-ended questions and paraphrase to avoid +misunderstandings. If you're unsure what someone meant, ask: "I want to make +sure I understand: are you saying X?" + +**Use translation tools freely.** If English isn't your first language, +translation software or AI tools may help you check that your message has the +tone you intend. Getting the phrasing wrong can make a reasonable point sound +more aggressive than it is. + +**Watch out for rhetorical questions.** They read as hostile in text even when +that's not the intent at all: + +* Instead of "Why do you think it is wrong?!", try "That doesn't sound right + to me. Here's why: …" +* Instead of "Did you even read the docs?", try "The relevant documentation + is at …" + +**Be patient with newcomers.** If someone doesn't know how things work here, +point them to the right docs or give them the context they need. Criticism +without guidance isn't helpful. + + .. _mailinglists: Mailing lists @@ -238,7 +270,7 @@ that way. You can find their blogs (and various other developers who use Python) at `Planet Python `__. -Setting expectations for open source participation +Setting expectations for open-source participation ================================================== Burn-out is common in open source due to a misunderstanding of what users, contributors, diff --git a/developer-workflow/extension-modules.rst b/developer-workflow/extension-modules.rst index 4d8c0ffca1..cab46c834b 100644 --- a/developer-workflow/extension-modules.rst +++ b/developer-workflow/extension-modules.rst @@ -547,7 +547,7 @@ Now that the configuration is in place, it remains to compile the project: .. tip:: - Use ``make -jN`` to speed-up compilation by utilizing as many CPU cores + Use ``make -jN`` to speed up compilation by utilizing as many CPU cores as possible, where *N* is as many CPU cores you want to spare (and have memory for). Be careful using ``make -j`` with no argument, as this puts no limit on the number of jobs, and compilation can sometimes use up a diff --git a/developer-workflow/index.rst b/developer-workflow/index.rst index 9919398e62..e04fc8a8b3 100644 --- a/developer-workflow/index.rst +++ b/developer-workflow/index.rst @@ -15,5 +15,3 @@ Development workflow c-api grammar porting - sbom - psrt diff --git a/developer-workflow/stdlib.rst b/developer-workflow/stdlib.rst index b683e55e96..ec10977221 100644 --- a/developer-workflow/stdlib.rst +++ b/developer-workflow/stdlib.rst @@ -126,7 +126,7 @@ If the module you want to propose adding to the stdlib meets the requirements, you may propose its inclusion by following the :abbr:`PEP (Python Enhancement Proposal)` process. See :pep:`1` for details, -and the :pep:`PEP index <0>` for previously-accepted PEPs +and the :pep:`PEP index <0>` for previously accepted PEPs that have proposed a module for inclusion. If the PEP is accepted, then the module will be added to the stdlib diff --git a/development-tools/warnings.rst b/development-tools/warnings.rst index b30d811311..1026082528 100644 --- a/development-tools/warnings.rst +++ b/development-tools/warnings.rst @@ -29,7 +29,7 @@ What to do if a warning check fails GitHub CI --------------------------------------------- The :cpy-file:`Tools/build/check_warnings.py` tool will fail if the compiler generates -more or less warnings than expected for a given source file as defined in the +more or fewer warnings than expected for a given source file as defined in the platform-specific warning ignore file. The warning ignore file is either :cpy-file:`Tools/build/.warningignore_ubuntu` or :cpy-file:`Tools/build/.warningignore_macos` depending on the platform. @@ -44,7 +44,7 @@ If a warning check fails with: warning ignore file. If the file exists in the warning ignore file increment the count by the number of newly introduced warnings. -* Unexpected improvements (less warnings) +* Unexpected improvements (fewer warnings) * Document in the PR that the change reduces the number of compiler warnings. Decrement the count in the platform-specific warning diff --git a/documentation/markup.rst b/documentation/markup.rst index 5ba8e4c7af..282b80f911 100644 --- a/documentation/markup.rst +++ b/documentation/markup.rst @@ -225,7 +225,7 @@ Explicit markup --------------- "Explicit markup" is used in reST for most constructs that need special -handling, such as footnotes, specially-highlighted paragraphs, comments, and +handling, such as footnotes, specially highlighted paragraphs, comments, and generic directives. An explicit markup block begins with a line starting with ``..`` followed by diff --git a/documentation/style-guide.rst b/documentation/style-guide.rst index 28e4f21682..73618f9aec 100644 --- a/documentation/style-guide.rst +++ b/documentation/style-guide.rst @@ -84,6 +84,11 @@ free-threaded lock (GIL) optional (per :pep:`703`). Avoid using "No-GIL" to avoid double negatives (for example, "non-no-GIL"). +open source + Follow the usual English rules for compound words. When used as an + adjective, hyphenate: "open-source software". When used as a noun, don't use + a hypen: "open source is a collaboration model.." + POSIX The name assigned to a particular group of standards. This is always uppercase. @@ -92,7 +97,7 @@ Python The name of our favorite programming language is always capitalized. reST - For "reStructuredText," an easy to read, plaintext markup syntax + For "reStructuredText," an easy to read, plain-text markup syntax used to produce Python documentation. When spelled out, it is always one word and both forms start with a lowercase 'r'. diff --git a/getting-started/ai-tools.rst b/getting-started/ai-tools.rst new file mode 100644 index 0000000000..e7d94d3517 --- /dev/null +++ b/getting-started/ai-tools.rst @@ -0,0 +1,64 @@ +.. _ai-tools: +.. _generative-ai: + +============================= +Guidelines for using AI tools +============================= + +The person submitting an issue or PR is responsible for its content, +regardless of whether AI tools were used in its creation. Generative AI +tools can produce output quickly, but discretion, good judgment, and +critical thinking are the foundation of all good contributions. We value +good code, concise accurate documentation, and well scoped PRs without +unneeded code churn. + +Considerations for success +========================== + +Authors must review the work done by AI tooling in detail to ensure it +actually makes sense before proposing it as a PR or filing it as an issue. + +We expect PR authors and those filing issues to be able to explain their +proposed changes in their own words. + +Disclosure of the use of AI tools in the PR description is appreciated, +while not required. Be prepared to explain how the tool was used and what +changes it made. + +Whether you are using AI tools or not, keep the following principles in +mind for the quality of your contribution: + +- Consider whether the change is necessary +- Make minimal, focused changes +- Follow existing coding style and patterns +- Write tests that exercise the change +- Keep backwards compatibility with prior releases in mind. Existing + tests may be ensuring specific API behaviors are maintained. + +Pay close attention to AI generated recommendations for testing changes. +Provide input about Python's testing principles when guiding an AI model. +Always review the output before opening a pull request or issue, +including proposed PR or issue titles and descriptions. + +Acceptable uses +=============== + +Some of the acceptable uses of generative AI include: + +- Assistance with writing comments, especially in a non-native language +- Gaining understanding of existing code +- Supplementing contributor knowledge for code, tests, and documentation + +Unacceptable uses +================= + +Maintainers may close issues and PRs that are not useful or productive, +regardless of whether AI tools were used or not. + +If a contributor repeatedly opens unproductive issues or PRs, they may be +blocked from contributing to the project because it is disruptive and +disrespectful of the maintainers time. + +It is not acceptable to alter or bypass existing tests, or remove desired +functionality, in order to make a failing test pass. Such changes are not +a real fix. diff --git a/getting-started/generative-ai.rst b/getting-started/generative-ai.rst deleted file mode 100644 index e4aa3e7586..0000000000 --- a/getting-started/generative-ai.rst +++ /dev/null @@ -1,40 +0,0 @@ -.. _generative-ai: - -============= -Generative AI -============= - -Generative AI tools have evolved rapidly, and their suggested results can be helpful. As with using any tool, the resulting contribution is -the responsibility of the contributor. We value good code, concise accurate documentation, and avoiding unneeded code -churn. Discretion, good judgment, and critical thinking are the foundation of all good contributions, regardless of the -tools used in their creation. - -Acceptable uses -=============== - -Some of the acceptable uses of generative AI include: - -- Assistance with writing comments, especially in a non-native language -- Gaining understanding of existing code -- Supplementing contributor knowledge for code, tests, and documentation - -Unacceptable uses -================= - -Maintainers may close issues and PRs that are not useful or productive, including -those that are fully generated by AI. If a contributor repeatedly opens unproductive -issues or PRs, they may be blocked. - -Considerations for success -========================== -- While AI assisted tools such as autocompletion can enhance productivity, they sometimes rewrite entire code blocks instead of making small, focused edits. - This can make it more difficult to review changes and to fully understand both the original intent of the code and the rationale behind the new modifications. - Maintaining consistency with the original code helps preserve clarity, traceability, and meaningful reviews and also helps us avoid unnecessary code churn. -- Sometimes AI assisted tools make failing unit tests pass by altering or bypassing the tests rather than addressing the underlying problem in the code. - Such changes do not represent a real fix. Authors must review the work done by AI tooling in detail to ensure it actually makes sense before proposing it as a PR. -- Keep the following principles for the quality of your contributions in mind whether you use generative AI or not: - - - Consider whether the change is necessary - - Make minimal, focused changes - - Follow existing coding style and patterns - - Write tests that exercise the change diff --git a/getting-started/git-boot-camp.rst b/getting-started/git-boot-camp.rst index 6376a190ca..47f49f3d69 100644 --- a/getting-started/git-boot-camp.rst +++ b/getting-started/git-boot-camp.rst @@ -462,12 +462,19 @@ Or set up a Git alias: git config --global alias.pr '!sh -c "git fetch upstream pull/${1}/head:pr_${1} && git switch pr_${1}" -' -.. tab:: Windows +.. tab:: Windows cmd .. code-block:: dosbatch git config --global alias.pr "!sh -c 'git fetch upstream pull/${1}/head:pr_${1} && git switch pr_${1}' -" +.. tab:: Windows Powershell + + .. code-block:: shell + + git config --global alias.pr '!f() { git fetch upstream pull/$1/head:pr_$1 && git checkout pr_$1; }; f' + + The alias only needs to be done once. After the alias is set up, you can get a local copy of a pull request as follows:: diff --git a/getting-started/index.rst b/getting-started/index.rst index 05ee67a3bc..48037ad38d 100644 --- a/getting-started/index.rst +++ b/getting-started/index.rst @@ -12,4 +12,4 @@ Getting started git-boot-camp pull-request-lifecycle getting-help - generative-ai + ai-tools diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index 6acc7ee578..3590e09c3f 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -83,7 +83,7 @@ You will only need to execute these steps once per machine: (You can use both SSH-based or HTTPS-based URLs.) -.. Step 6 and 7 are are duplicated in bootcamp as well. +.. Step 6 and 7 are duplicated in bootcamp as well. Please update these steps in both places. 6. Add an ``upstream`` remote, then configure ``git`` @@ -191,6 +191,15 @@ Configuration is typically:: More flags are available to ``configure``, but this is the minimum you should do to get a pydebug build of CPython. +.. tip:: + To speed up repeated ``configure`` runs, use ``--config-cache`` (equivalent to ``--cache-file=config.cache``, short: ``-C``):: + + $ ./configure --config-cache --with-pydebug + + This caches results in a :file:`config.cache` file. If you switch compilers or + significantly change your build environment, delete :file:`config.cache` before + re-running ``configure``. + .. note:: You might need to run ``make clean`` before or after re-running ``configure`` in a particular build directory. @@ -522,39 +531,52 @@ The simplest way to build Emscripten is to run: .. code-block:: sh - python3 Platforms/emscripten build all --emsdk-cache=./cross-build/emsdk + export EMSDK_CACHE=$PWD/cross-build/emsdk + python3 Platforms/emscripten install-emscripten + python3 Platforms/emscripten build all -This will: +``install-emscripten`` downloads and installs the version of the Emscripten SDK +required, placing it in the ``EMSDK_CACHE`` directory. +``build all`` will: 1. Build a copy of Python that can run on the host machine (the "build" python); -2. Download a copy of the Emscripten SDK matching the version required by the - version of Python being compiled; -3. Ensure that a required version of Node is installed; -4. Download the code for all the binary dependencies of Python (such as - ``libFFI`` and ``xz``), and compile them for Emscripten; and -5. Build a copy of Python that can run on Emscripten (the "host" python). - -If you omit the ``--emsdk-cache`` environment variable, the build script will +2. Use nvm_ to ensure that the needed version of Node is installed; +3. Download the code for all the binary dependencies of Python (such as + ``libffi`` and ``mpdecimal``), and compile them for Emscripten; and +4. Build a copy of Python that can run on Emscripten (the "host" python). + +The built binary dependencies are cached inside the Emscripten cache directory. +Once built for a given Emscripten version, they will not be rebuilt on +subsequent runs unless there is a change in the version or build script for the +dependency. + +It is assumed that nvm_ is installed in ``${HOME}/.nvm``. If you don't have nvm +installed or don't want to use it, you can pass ``--host-runner node`` to the +``build`` command. The argument should either be the name of an executable that +can be found on the ``PATH`` or a relative or absolute path to an executable. + +If you omit the ``EMSDK_CACHE`` environment variable, the build script will assume that the current environment has the Emscripten tools available. You are responsible for downloading and activating those tools in your environment. The version of Emscripten and Node that is required to build Python is defined in the :cpy-file:`Platforms/emscripten/config.toml` configuration file. -There are three environment variables that can be used to control the operation of +There are two environment variables that can be used to control the operation of the ``Platforms/emscripten`` build script: -* ``EMSDK_CACHE`` controls the location of the emscripten SDK. You can use this instead - environment variable instead of passing the ``--emsdk-cache`` flag. -* ``CACHE_DIR`` defines the location where downloaded artefacts, such - as precompiled ``libFFI`` and ``xz`` binaries, will be stored. -* ``CROSS_BUILD_DIR`` defines the name of the ``cross-build`` directory - that will be used for builds. This can be useful if you need to maintain - builds of multiple versions of Python. +* ``EMSDK_CACHE`` (or the ``--emsdk-cache`` flag) controls the location of the + Emscripten SDK cache directory. You can use this environment variable instead + of passing the ``--emsdk-cache`` flag. When set, the build script will + validate that the required Emscripten version is present in the cache and will + exit with an error if it is not; run ``install-emscripten`` to populate the + cache. +* ``CROSS_BUILD_DIR`` (or the ``--cross-build-dir`` flag) defines the location + of the ``cross-build`` directory that will be used for builds. This can be + useful if you need to maintain builds of multiple versions of Python + side by side. It is possible (but not necessary) to enable ``ccache`` for Emscripten builds -by setting the ``EM_COMPILER_WRAPPER`` environment, but this step will only -take effect if it is done **after** ``emsdk_env.sh`` is sourced (otherwise, the -sourced script removes the environment variable): +by setting the ``EM_COMPILER_WRAPPER`` environment variable: .. code-block:: sh @@ -571,8 +593,9 @@ Emscripten build in ``cross-build/build`` and ``cross-build/wasm32-emscripten/build/python/``, respectively. The ``Platforms/emscripten`` script has a number of other entry points that allow for -fine-grained execution of each part of an iOS build; run ``python3 -Platforms/emscripten --help`` for more details. +fine-grained execution of each part of an Emscripten build; run +``python3 Platforms/emscripten --help`` for more details. + Once the build is complete, you can run Python code using: @@ -592,6 +615,7 @@ through web browsers) are available in the CPython repository at .. _Emscripten: https://emscripten.org/ .. _WebAssembly: https://webassembly.org +.. _nvm: https://github.com/nvm-sh/nvm#intro Android ------- @@ -833,7 +857,7 @@ some of CPython's modules (for example, ``zlib``). For **Homebrew**, install dependencies using ``brew``:: - $ brew install pkg-config openssl@3 xz gdbm tcl-tk mpdecimal zstd + $ brew bundle --file=Misc/Brewfile .. tab:: Python 3.11+ @@ -841,7 +865,8 @@ some of CPython's modules (for example, ``zlib``). $ GDBM_CFLAGS="-I$(brew --prefix gdbm)/include" \ GDBM_LIBS="-L$(brew --prefix gdbm)/lib -lgdbm" \ - ./configure --with-pydebug \ + ./configure --config-cache \ + --with-pydebug \ --with-openssl="$(brew --prefix openssl@3)" .. tab:: Python 3.10 @@ -850,7 +875,8 @@ some of CPython's modules (for example, ``zlib``). $ CPPFLAGS="-I$(brew --prefix gdbm)/include -I$(brew --prefix xz)/include" \ LDFLAGS="-L$(brew --prefix gdbm)/lib -L$(brew --prefix xz)/lib" \ - ./configure --with-pydebug \ + ./configure --config-cache \ + --with-pydebug \ --with-openssl="$(brew --prefix openssl@3)" \ --with-tcltk-libs="$(pkg-config --libs tcl tk)" \ --with-tcltk-includes="$(pkg-config --cflags tcl tk)" \ @@ -872,7 +898,8 @@ some of CPython's modules (for example, ``zlib``). $ GDBM_CFLAGS="-I$(dirname $(dirname $(which port)))/include" \ GDBM_LIBS="-L$(dirname $(dirname $(which port)))/lib -lgdbm" \ - ./configure --with-pydebug \ + ./configure --config-cache \ + --with-pydebug \ --with-system-libmpdec .. tab:: Python 3.11-3.12 @@ -881,7 +908,8 @@ some of CPython's modules (for example, ``zlib``). $ GDBM_CFLAGS="-I$(dirname $(dirname $(which port)))/include" \ GDBM_LIBS="-L$(dirname $(dirname $(which port)))/lib -lgdbm" \ - ./configure --with-pydebug + ./configure --config-cache \ + --with-pydebug And finally, run ``make``:: diff --git a/index.rst b/index.rst index 18aca244e1..23ed08e151 100644 --- a/index.rst +++ b/index.rst @@ -40,6 +40,7 @@ Guide for contributing to Python: * :ref:`rst-primer` * :ref:`translating` * :ref:`devguide` + * :ref:`ai-tools` - * :ref:`setup` * :ref:`help` @@ -49,6 +50,7 @@ Guide for contributing to Python: * :ref:`communication` * :ref:`gitbootcamp` * :ref:`devcycle` + * :ref:`ai-tools` - * :ref:`tracker` * :ref:`triaging` @@ -95,13 +97,13 @@ instructions please see the :ref:`setup guide `. .. code-block:: shell - ./configure --with-pydebug && make -j $(nproc) + ./configure --config-cache --with-pydebug && make -j $(nproc) .. tab:: macOS .. code-block:: shell - ./configure --with-pydebug && make -j8 + ./configure --config-cache --with-pydebug && make -j8 .. tab:: Windows @@ -288,6 +290,7 @@ Full table of contents testing/index development-tools/index core-team/index + security/index internals versions diff --git a/requirements.txt b/requirements.txt index 3b40508f67..5dfb12f146 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,11 +1,12 @@ -furo>=2022.6.4 +furo>=2025.12.19 jinja2 linklint -sphinx-autobuild>=2024.9.19 -sphinx-inline-tabs>=2023.4.21 +sphinx-autobuild>=2025.8.25 +sphinx-inline-tabs>=2025.12.21.14 +sphinx-last-updated-by-git>=0.3.8 sphinx-lint==1.0.2 -sphinx-notfound-page>=1.0.0 -sphinx_copybutton>=0.3.3 +sphinx-notfound-page>=1.1.0 +sphinx_copybutton>=0.5.2 sphinxext-opengraph>=0.13.0 sphinxext-rediraffe -Sphinx>=8.2.3 +Sphinx>=9.1.0 diff --git a/security/index.rst b/security/index.rst new file mode 100644 index 0000000000..cbc1eb4e46 --- /dev/null +++ b/security/index.rst @@ -0,0 +1,11 @@ +.. _security: + +======== +Security +======== + +.. toctree:: + :maxdepth: 5 + + psrt + sbom diff --git a/developer-workflow/psrt-emeritus.csv b/security/psrt-emeritus.csv similarity index 100% rename from developer-workflow/psrt-emeritus.csv rename to security/psrt-emeritus.csv diff --git a/developer-workflow/psrt.csv b/security/psrt.csv similarity index 93% rename from developer-workflow/psrt.csv rename to security/psrt.csv index da67432d9b..d794029825 100644 --- a/developer-workflow/psrt.csv +++ b/security/psrt.csv @@ -2,6 +2,7 @@ Adam Turner,AA-Turner, Barry Warsaw,warsaw,Admin Bénédikt Tran,picnixz, Benjamin Peterson,benjaminp, +Damian Shaw,notatallshaw, Donald Stufft,dstufft, Dustin Ingram,di, Ee Durbin,ewdurbin,Admin @@ -10,6 +11,7 @@ Glyph Lefkowitz,glyph, Gregory P. Smith,gpshead, Hugo van Kemenade,hugovk,Release Manager Jacob Coffee,JacobCoffee, +Kirill Podoprigora,eclips4, Larry Hastings,larryhastings, Łukasz Langa,ambv,Release Manager Ned Deily,ned-deily,"Admin, Release Manager" diff --git a/developer-workflow/psrt.rst b/security/psrt.rst similarity index 99% rename from developer-workflow/psrt.rst rename to security/psrt.rst index c2501e44b7..6b53700d89 100644 --- a/developer-workflow/psrt.rst +++ b/security/psrt.rst @@ -4,6 +4,8 @@ Python Security Response Team (PSRT) The Python Security Response Team (PSRT) is responsible for handling vulnerability reports for CPython and pip. +To report security issues: https://www.python.org/dev/security/ + Members ------- diff --git a/developer-workflow/sbom.rst b/security/sbom.rst similarity index 100% rename from developer-workflow/sbom.rst rename to security/sbom.rst diff --git a/testing/index.rst b/testing/index.rst index 55bdd3d08b..6e65c5fdf9 100644 --- a/testing/index.rst +++ b/testing/index.rst @@ -10,5 +10,6 @@ Testing and buildbots run-write-tests silence-warnings coverage + oss-fuzz buildbots new-buildbot-worker diff --git a/testing/oss-fuzz.rst b/testing/oss-fuzz.rst new file mode 100644 index 0000000000..ec2449a4fd --- /dev/null +++ b/testing/oss-fuzz.rst @@ -0,0 +1,55 @@ +OSS-Fuzz for CPython +==================== + +CPython uses `OSS-Fuzz `__, Google's +continuous fuzzing service for open-source projects, to find bugs and +security vulnerabilities by feeding semi-random data to various APIs. + +CPython has two OSS-Fuzz projects: + +* `cpython3 `__: + The fuzz targets, seed corpora, and dictionaries can be found in the + :cpy-file:`Modules/_xxtestfuzz/` directory of CPython. This project + is maintained for existing fuzz targets; add new targets to + ``python3-libraries``. + +* `python3-libraries `__: + The fuzz targets, seed corpora, and dictionaries can be found in the + :github:`python/library-fuzzers` repository. Access to the repository is + managed through the `@python/fuzzers + `__ team on GitHub. + +OSS-Fuzz bug reports are private when filed, so access to crash details and +reproducer test cases is limited to those listed in the ``auto_ccs`` fields of +the OSS-Fuzz project configuration files. Those listed can log into +https://oss-fuzz.com/ with their Google account to view crash details, +reproducer test cases, and project statistics. +If you need access, contact the ``@python/fuzzers`` team. +Completed issues, and issues that remain unresolved after 90 days, are publicly +visible in the `OSS-Fuzz issue tracker +`__. + +Coverage and target statistics are available in the OSS-Fuzz Introspector +project profiles for `cpython3 `__ and +`python3-libraries `__. + +In addition, `CIFuzz `__ +runs the fuzz targets on GitHub Actions for PRs to the ``main`` branch changing +relevant files. + +.. seealso:: + + The `libFuzzer `__ documentation for + details about the fuzzing engine used by OSS-Fuzz. + + +Adding new targets +------------------ + +Add new targets to the ``python3-libraries`` project. For more +information, see the documentation in the :github:`python/library-fuzzers` +repository. + +If the new target covers a standard library module, update the relevant CIFuzz +path configuration so pull requests touching that module trigger fuzzing. See +the ``LIBRARY_FUZZER_PATHS`` set in :cpy-file:`Tools/build/compute-changes.py`. diff --git a/triage/issue-tracker.rst b/triage/issue-tracker.rst index 4dd0815e4c..31673d9435 100644 --- a/triage/issue-tracker.rst +++ b/triage/issue-tracker.rst @@ -124,7 +124,8 @@ Disagreement with a resolution on the issue tracker As humans, we will have differences of opinions from time to time. First and foremost, please be respectful that care, thought, and volunteer time went into -the resolution. +the resolution. Keep in mind that contributors come from many different cultural +and linguistic backgrounds; see :ref:`multicultural-communication`. With this in mind, take some time to consider any comments made in association with the resolution of the issue. On reflection, the resolution steps may seem