diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 06213bdf40..305a38980a 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -5,4 +5,4 @@ # https://git-scm.com/docs/gitignore#_pattern_format # PSRT member list owned by PSRT admins. -developer-workflow/psrt*.csv @warsaw @ewdurbin @ned-deily @sethmlarson +security/psrt*.csv @warsaw @JacobCoffee @ned-deily @sethmlarson @stanfromireland diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 23f03616cf..1c0343afa3 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -10,6 +10,11 @@ updates: actions: patterns: - "*" + cooldown: + # https://blog.yossarian.net/2025/11/21/We-should-all-be-using-dependency-cooldowns + # Cooldowns protect against supply chain attacks by avoiding the + # highest-risk window immediately after new releases. + default-days: 14 - package-ecosystem: pip directory: "/" @@ -21,3 +26,5 @@ updates: pip: patterns: - "*" + cooldown: + default-days: 14 diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index b85a45c1bb..302992d47a 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -5,6 +5,8 @@ on: [pull_request, push, workflow_dispatch] env: FORCE_COLOR: 1 +permissions: {} + jobs: test: name: Check build, markup, and links @@ -12,12 +14,15 @@ jobs: timeout-minutes: 10 steps: - - uses: actions/checkout@v6 - - uses: actions/setup-python@v6 + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0 with: python-version: "3" - name: Install uv - uses: hynek/setup-cached-uv@v2 + uses: hynek/setup-cached-uv@34e35d30f1ebc7421a5cc733bca38dcc62603960 # v2.6.0 + - uses: sphinx-doc/github-problem-matcher@1f74d6599f4a5e89a20d3c99aab4e6a70f7bda0f # v1.1 - name: Build docs run: make html - name: Link check diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index 4622f995aa..264a11f5a0 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/lint.yml @@ -2,14 +2,22 @@ name: Lint on: [push, pull_request, workflow_dispatch] +permissions: {} + +env: + FORCE_COLOR: 1 + RUFF_OUTPUT_FORMAT: github + jobs: lint: runs-on: ubuntu-latest timeout-minutes: 10 steps: - - uses: actions/checkout@v6 - - uses: actions/setup-python@v6 + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0 with: python-version: "3.x" - - uses: pre-commit/action@v3.0.1 + - uses: j178/prek-action@4e14d07f9231acabce116ccfca13b13dd9755ece # v3.0.0 diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index c5beee4a37..07fdda903c 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -1,6 +1,6 @@ repos: - repo: https://github.com/astral-sh/ruff-pre-commit - rev: v0.5.7 + rev: v0.15.14 hooks: - id: ruff name: Run Ruff (lint) @@ -9,7 +9,7 @@ repos: name: Run Ruff (format) - repo: https://github.com/pre-commit/pre-commit-hooks - rev: v4.5.0 + rev: v6.0.0 hooks: - id: check-case-conflict - id: check-merge-conflict @@ -18,8 +18,13 @@ repos: - id: end-of-file-fixer - id: trailing-whitespace + - repo: https://github.com/zizmorcore/zizmor-pre-commit + rev: v1.25.2 + hooks: + - id: zizmor + - repo: https://github.com/sphinx-contrib/sphinx-lint - rev: v0.9.1 + rev: v1.0.2 hooks: - id: sphinx-lint args: [--enable=default-role] 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/_static/devguide_overrides.css b/_static/devguide_overrides.css index 625a9dda2d..abe61bcdcd 100644 --- a/_static/devguide_overrides.css +++ b/_static/devguide_overrides.css @@ -27,3 +27,9 @@ table.docutils td { vertical-align: top; } + +/* For the video in index.rst */ +[role="main"] .compact-video { + max-width: 500px; + margin-inline: auto; +} diff --git a/_static/psrt-coordinator-triage.html b/_static/psrt-coordinator-triage.html index af5936a6cb..1190c95d78 100644 --- a/_static/psrt-coordinator-triage.html +++ b/_static/psrt-coordinator-triage.html @@ -17,15 +17,15 @@ │ field to Coordinator │ └────────────┬───────────┘ │ - ┌────────────▼───────────┐ - │ Coordinator determines │ - ┌───┤ whether report... ┼───┐ - │ └────────────┬───────────┘ │ + ┌────────────▼────────────┐ + │ Coordinator determines │ + ┌───┤ whether report... ┼──┐ + │ └────────────┬────────────┘ │ │ │ │ -┌────────────▼─┐ ┌────────────▼───────────┐ ┌─▼─────────────┐ -│..is a invalid│ │ ..is a bug, but not │ │..is a security│ -│ or non-issue│ │ security relevant │ │ issue │ -└────────────┬─┘ └────────────┬───────────┘ └─┬─────────────┘ +┌────────────▼──┐ ┌───────────▼───────────┐ ┌─▼─────────────┐ +│..is an invalid│ │ ..is a bug, but not │ │..is a security│ +│ or non-issue │ │ security relevant │ │ issue │ +└────────────┬──┘ └───────────┬───────────┘ └─┬─────────────┘ │ │ │ │ ┌────────────▼───────────┐ │ │ │ Coordinator opens a │ │ diff --git a/conf.py b/conf.py index 1d88937227..7e0ea0810a 100644 --- a/conf.py +++ b/conf.py @@ -3,17 +3,21 @@ from urllib.request import urlopen extensions = [ - 'linklint.ext', 'notfound.extension', 'sphinx.ext.extlinks', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx_copybutton', 'sphinx_inline_tabs', + 'sphinx_last_updated_by_git', + 'sphinx_linklint.ext', + 'sphinxcontrib.youtube', 'sphinxext.opengraph', 'sphinxext.rediraffe', ] +html_last_updated_fmt = '%b %d, %Y' + # The master toctree document. master_doc = 'index' @@ -147,6 +151,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 +167,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 +210,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", @@ -268,6 +276,7 @@ "gh-label": (f"{_repo}/labels/%s", "%s"), "github": ("https://github.com/%s", "%s"), "github-user": ("https://github.com/%s", "@%s"), + "gh-python-team": ("https://github.com/orgs/python/teams/%s", "@python/%s"), "pypi": ("https://pypi.org/project/%s/", "%s"), "pypi-org": ("https://pypi.org/org/%s/", "%s"), } diff --git a/core-team/committing.rst b/core-team/committing.rst index c606df3839..cf8b36b366 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. @@ -68,7 +68,9 @@ to enter the public source tree. Ask yourself the following questions: if they haven't. For further questions about the CLA process, write to contributors@python.org. -* **Were** ``What's New in Python`` **and** ``Misc/NEWS.d/next`` **updated?** +* .. _updating-news-and-what-s-new-in-python: + + **Were** ``What's New in Python`` **and** ``Misc/NEWS.d/next`` **updated?** If the change is particularly interesting for end users (for example, new features, significant improvements, or backwards-incompatible changes), then an entry in the ``What's New in Python`` document (in ``Doc/whatsnew/``) should @@ -79,6 +81,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_ ----------------- @@ -124,44 +151,12 @@ bug fixes or security fixes. In almost all cases the fixes should first originate on ``main`` and then be ported back to older branches. -.. _branch-merge: +.. _backport-pr-title: Backporting changes to an older version ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -If it is determined that a pull request needs to be backported into one or -more of the maintenance branches, then a core team member can apply the label -``needs backport to X.Y`` to the pull request. - -After the pull request has been merged, miss-islington (bot) will first try to -do the backport automatically. If miss-islington is unable to do it, -then the pull request author or the core team member who merged it should look into -backporting it themselves, using the backport generated by cherry_picker.py_ -as a starting point. - -You can get the commit hash from the original pull request, or you can use -``git log`` on the ``main`` branch. To display the 10 most recent commit -hashes and their first line of the commit, use the following command:: - - git log -10 --oneline - -.. _backport-pr-title: - -You can prefix the backport pull request with the branch, and reference -the pull request number from ``main``. Here is an example:: - - [3.9] gh-12345: Fix the Spam Module (GH-NNNN) - -Here "gh-12345" is the GitHub *issue* number, and "GH-NNNN" is the -number of the original *pull request*. -Note that cherry_picker.py_ adds the branch prefix automatically. - -Once the backport pull request has been created, remove the -``needs backport to X.Y`` label from the original pull request. (Only -members of the core team and :ref:`Python Triage Team ` -can apply labels to GitHub pull requests). - -.. _cherry_picker.py: https://github.com/python/cherry-picker +This section has moved to :ref:`branch-merge`. Reverting a merged pull request diff --git a/core-team/core-team.csv b/core-team/core-team.csv index 46dfd81530..67a28fc338 100644 --- a/core-team/core-team.csv +++ b/core-team/core-team.csv @@ -1,3 +1,7 @@ +Nathan Goldbaum,ngoldbaum,2026-09-01,, +Pieter Eendebak,eendebakpt,2026-07-08,, +Seth Larson,sethmlarson,2026-06-12,, +Chris Eibl,chris-eibl,2026-05-10,, Stan Ulbrych,StanFromIreland,2026-03-26,, Itamar Oren,itamaro,2026-02-16,, Emma Smith,emmatyping,2025-07-31,, diff --git a/core-team/experts.rst b/core-team/experts.rst index 47e1d76107..8152cb09e2 100644 --- a/core-team/experts.rst +++ b/core-team/experts.rst @@ -53,7 +53,7 @@ __main__ gvanrossum, ncoghlan annotationlib JelleZijlstra* argparse savannahostrowski*, serhiy-storchaka* ast benjaminp, pablogsal, isidentical, JelleZijlstra, eclips4 -asyncio 1st1, asvetlov, gvanrossum, graingert, kumaraditya303, willingc +asyncio 1st1, asvetlov, gvanrossum, graingert, kumaraditya303 bisect rhettinger* codecs malemburg collections rhettinger* @@ -145,7 +145,6 @@ tomllib hauntsaninja* traceback iritkatriel tracemalloc vstinner tty Yhg1s* -turtle willingc turtledemo terryjreedy* types 1st1 typing gvanrossum, JelleZijlstra*, AlexWaygood*, carljm, sobolevn* @@ -180,23 +179,9 @@ PEG Generator gvanrossum, pablogsal, lysnikolaou Platforms ========= -For official contacts for supported platforms, see :pep:`11`. - -Platforms listed here are not necessarily supported by CPython. -Some of the experts listed here maintain and distribute Python -for “their” platform as a third-party project. +The **Platforms experts list** has moved to :ref:`ports`. -=================== =========== -Platform Maintainers -=================== =========== -AIX ayappanec -Android mhsmith -Emscripten hoodmane, pmp-p, rdb, rth, ryanking13 -iOS freakboy3742, ned-deily -macOS ronaldoussoren, ned-deily, freakboy3742 -Solaris/OpenIndiana jcea, kulikjak -Windows tjguk, zooba, pfmoore -=================== =========== +For official contacts for supported platforms, see :pep:`11`. Miscellaneous @@ -217,9 +202,9 @@ context managers ncoghlan core workflow Mariatta, ezio-melotti, hugovk, AA-Turner cryptography gpshead, dstufft, picnixz database malemburg -devguide merwok, ezio-melotti, willingc, Mariatta, hugovk, +devguide merwok, ezio-melotti, Mariatta, hugovk, AA-Turner, StanFromIreland -documentation ezio-melotti, merwok, JulienPalard, willingc, hugovk, +documentation ezio-melotti, merwok, JulienPalard, hugovk, AA-Turner, AlexWaygood*, StanFromIreland emoji Mariatta extension modules encukou, ncoghlan, FFY00 diff --git a/core-team/join-team.rst b/core-team/join-team.rst index 20ce9e4c98..a0177a4601 100644 --- a/core-team/join-team.rst +++ b/core-team/join-team.rst @@ -30,8 +30,8 @@ After a candidate has demonstrated consistent contributions, commit privileges are granted through these steps: #. A core team member (submitter, usually the mentor) starts a poll - (see the :ref:`template ` below) in - the `Committers category`_ on the `Python Discourse`_. + (see the :ref:`template ` below) with + the `Promotion tag in the Committers category`_ on the `Python Discourse`_. - open for 7 days - results shown only upon closing @@ -53,16 +53,46 @@ are granted through these steps: #. Once the candidate has provided the pertinent details, the approver will: - - Enable the various new privileges. - - Remove the new committer from the triage team, if applicable. + - Enable new permissions for the new committer, and remove redundant ones + if applicable. + If you don't have admin rights, ping the given contact. + + .. list-table:: + :header-rows: 1 + :align: left + + * - Service + - Add to + - Remove from + - Contact + * - GitHub + - :gh-python-team:`python-core` + - :gh-python-team:`python-triage` + - :gh-python-team:`organization-owners` + * - Discourse + - `committers `__ + - --- + - `admins `__ + * - Core Discord + - "Core Developer" + - "Triager" + - ``@Server Admin`` + * - Docs Discord + - "Core Team" + - --- + - | ``@encukou`` (Petr) + | ``@justbinary`` (Stan) + + (Some of these are unofficial spaces managed as a courtesy. + Adjust the list to taste.) + - Add their details to `🔒 python/voters `__. - Once the python/voters update is merged, regenerate the public team membership list at :ref:`developers`. See "Public list of members" in the ``voters`` README. - - Post an announcement in the `Committers Discourse category - `__. The past few announcements - were in the form of a separate post on the already open topic with - the poll. + - Post an announcement to the Discourse topic with the promotional poll. + The topic should be in the `Promotion tag in the Committers category`_. + Getting a python.org email address ---------------------------------- @@ -114,3 +144,4 @@ The important options in the poll builder set to get this result: .. _Code of Conduct: https://policies.python.org/python.org/code-of-conduct/ .. _Committers category: https://discuss.python.org/c/committers/5 .. _Python Discourse: https://discuss.python.org +.. _Promotion tag in the Committers category: https://discuss.python.org/tags/c/committers/5/promotion/31 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/core-team/team-log.rst b/core-team/team-log.rst index 77639ebf1d..3b438abc49 100644 --- a/core-team/team-log.rst +++ b/core-team/team-log.rst @@ -18,10 +18,8 @@ Procedure for granting or dropping access ----------------------------------------- To be granted the ability to manage who is a committer, you must be a -team maintainer of the `Python core team`_ on GitHub. Once you have +team maintainer of the :gh-python-team:`python-core` team on GitHub. Once you have that privilege you can add people to the team. They will be asked to accept the membership which they can do by visiting https://github.com/python and clicking on the appropriate button that will be displayed to them in the upper part of the page. - -.. _Python core team: https://github.com/orgs/python/teams/python-core diff --git a/developer-workflow/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/development-cycle.rst b/developer-workflow/development-cycle.rst index af198a4007..17bd8c2111 100644 --- a/developer-workflow/development-cycle.rst +++ b/developer-workflow/development-cycle.rst @@ -74,12 +74,15 @@ produced from a maintenance branch are called **bugfix** or **maintenance** releases; the terms are used interchangeably. These releases have a **micro version** number greater than zero. -The only changes allowed to occur in a maintenance branch without debate are -bug fixes, test improvements, and edits to the documentation. +Changes backported to a maintenance branch fall into two groups. *Low-risk* +changes (bug fixes, test improvements, and documentation edits) may be +backported without debate. *Higher-risk* changes (new features, semantic +changes, and performance improvements) can introduce regressions, so they are +not backported as a matter of course. Also, a general rule for maintenance branches is that compatibility must not be broken at any point between sibling micro releases (3.12.1, 3.12.2, -etc.). For both rules, only rare exceptions are accepted and **must** be -discussed first. +etc.). For both rules, only rare exceptions are accepted, and each requires a +strong case agreed upon in discussion beforehand. Backporting changes reduces the risk of future conflicts. For documentation, it increases the visibility of improvements, @@ -143,7 +146,7 @@ Stages Based on what stage the :ref:`in-development ` version of Python is in, the responsibilities of a core team member change in regards to commits -to the :abbr:`VCS (version control system)`. +to the VCS (version control system). Pre-alpha @@ -300,12 +303,14 @@ Current owners +----------------------+--------------------------------+-----------------+ | Jacob Coffee | PSF Infrastructure Engineer | JacobCoffee | +----------------------+--------------------------------+-----------------+ -| Łukasz Langa | CPython Developer in Residence | ambv | +| Petr Viktorin | CPython Developer in Residence | encukou | ++----------------------+--------------------------------+-----------------+ +| Łukasz Langa | | ambv | +----------------------+--------------------------------+-----------------+ Certain actions (blocking spam accounts, inviting new users, adjusting organization-level settings) can only `be performed`_ by owners of the Python -organization on GitHub. The ``@python/organization-owners`` team can be +organization on GitHub. The :gh-python-team:`organization-owners` team can be mentioned to request assistance from an organization owner. .. _be performed: https://docs.github.com/en/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization#permissions-for-organization-roles @@ -346,7 +351,7 @@ Current administrators | Pablo Galindo | Python 3.10 and 3.11 Release Manager, | pablogsal | | | Maintainer of buildbot.python.org | | +--------------------+----------------------------------------------------------+-------------------+ -| Łukasz Langa | PSF CPython Developer in Residence 2021-present | ambv | +| Łukasz Langa | | ambv | +--------------------+----------------------------------------------------------+-------------------+ | Brett Cannon | | brettcannon | +--------------------+----------------------------------------------------------+-------------------+ @@ -356,6 +361,8 @@ Current administrators +--------------------+----------------------------------------------------------+-------------------+ | Seth Larson | PSF Security Developer-in-Residence | sethmlarson | +--------------------+----------------------------------------------------------+-------------------+ +| Petr Viktorin | CPython Developer in Residence | encukou | ++--------------------+----------------------------------------------------------+-------------------+ Repository release manager role policy ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 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/porting.rst b/developer-workflow/porting.rst index f308e6c14b..63bb45cc7b 100644 --- a/developer-workflow/porting.rst +++ b/developer-workflow/porting.rst @@ -1,9 +1,131 @@ .. _porting: -========================= +============================ +Porting and platform support +============================ + +The Python interpreter runs on an underlying *platform* -- the operating system +(for example, Linux, Windows or macOS), processor (like Intel/AMD, ARM), +C compiler and library, and other "lower level" details. + +CPython is *officially supported* on several platforms, on which the core team +has adequate knowledge and resources to test releases and fix bugs. +See :pep:`11` for details. + +Other platforms are unsupported *by the core team*, but might be supported +by others -- as a volunteer project, by a company that wants Python on "their" +system, or just as a one-off experiment. +See :pep:`PEP 11 <11#unsupported-platforms>` for the policy on merging code for +unsupported platforms into the main CPython repository. + + +.. _ports: + +Ports and contacts +================== + +The table below lists relevant third-party projects, +their maintainers, and links to information that's relevant when triaging +platform-specific issues. +Officially supported platforms are also included when there is relevant +information for them (beyond :pep:`11`), or to group similar platforms. + +It is OK to @mention the listed GitHub usernames to draw maintainers' attention +or request their opinion on platform-specific issues. +Maintainers must only be listed with their permission, and they may remove +themselves at any time. + +Third-party projects should only be listed if they benefit substantially +more people than the maintainers. + +Links should be for the port specifically (not the platform itself), +and relevant for porting work and fixing platform-specific issues +(no homepage/marketing links). + +.. list-table:: + :header-rows: 1 + + * - Platform + - Maintainers + - Information + * - **AIX** + - :github-user:`ayappanec` + - + * - **Android** [t3]_ + - :github-user:`mhsmith` + - `Usage `__, + `Limitations `__, + :cpy-file:`Platforms/Android` + * - **iOS** [t3]_ + - :github-user:`freakboy3742`, :github-user:`ned-deily` + - `Usage `__, + `Limitations `__, + :cpy-file:`Platforms/Apple` + * - **Linux** [t1]_ + - + - + * - \- Fedora + - :github-user:`hroncok`, :github-user:`befeleme` + - `Config & patches `_, + `Bugs `__, + `Maintenance guide `__ + * - \- Debian + - :github-user:`stefanor` + - `Config & patches `_, + `Bugs `__, + `Wiki `__ + * - \- Ubuntu + - :github-user:`stefanor` + - `Config & patches `_ (by version), + `Bugs `__ + * - \- Alpine + - + - `Config & patches `_ + * - **macOS** [t1]_ + - :gh-python-team:`macos-team`, :github-user:`freakboy3742` + - `Usage `__, + :cpy-file:`Platforms/Apple` + * - **Solaris**/OpenIndiana + - :github-user:`jcea`, :github-user:`kulikjak` + - + * - **WebAssembly** + - + - `Limitations `__ + * - \- WASI [t2]_ + - + - :cpy-file:`WASI ` + * - \- Emscripten [t3]_ + - :github-user:`pmp-p`, :github-user:`rdb`, :github-user:`hoodmane` + - :cpy-file:`emscripten ` + * - \- Pyodide + - :github-user:`ryanking13`, :github-user:`agriyakhetarpal` + - + * - **Windows** [t1]_ + - :gh-python-team:`windows-team`, :github-user:`pfmoore` + - `Usage `__, + :cpy-file:`PC`, + :cpy-file:`PCbuild` + * - **Cross-Platform** + - + - + * - \- conda-forge + - + - `Recipe `_ + +.. [t1] Specific variants have official :pep:`Tier 1 support <11#tier-1>` +.. [t2] Specific variants have official :pep:`Tier 2 support <11#tier-2>` +.. [t3] Specific variants have official :pep:`Tier 3 support <11#tier-3>` + + Porting to a new platform ========================= +Porting CPython to an entirely new platform is an adventure. +If you try it, consider keeping notes -- and updating this guide, if you +find something that might be relevant to others. +Since each platform is different, this guide can only give you a +few rough tips. + The first step is to familiarize yourself with the development toolchain on the platform in question, notably the C compiler. Make sure you can compile and run a hello-world program using the target compiler. @@ -12,23 +134,39 @@ Next, learn how to compile and run the Python interpreter on a platform to which it has already been ported; preferably Unix, but Windows will do, too. The build process for Python, in particular the ``Makefile`` in the source distribution, will give you a hint on which files to compile -for Python. Not all source files are relevant: some are platform-specific, -and others are only used in emergencies (for example, ``getopt.c``). +for Python. Not all source files are relevant: some are platform-specific, +and others are only used in emergencies (for example, +:cpy-file:`Python/getopt.c`). It is not recommended to start porting Python without at least a medium-level understanding of your target platform; how it is generally used, how to write platform-specific apps, and so on. Also, some Python knowledge is required, or you will be unable to verify that your port is working correctly. -You will need a ``pyconfig.h`` file tailored for your platform. You can -start with ``pyconfig.h.in``, read the comments, and turn on definitions that -apply to your platform. Also, you will need a ``config.c`` file, which lists -the built-in modules you support. Again, starting with -``Modules/config.c.in`` is recommended. +On systems with a UNIX shell, run the included :cpy-file:`configure` script. +This should generate all required files, including a :file:`Makefile`. +If it does not, you will need to debug it (or reimplement it). +Note that the script is generated from :cpy-file:`configure.ac` using GNU +Autotools. +(CPython pins a specific version for reproducibility, but other versions may +work fine.) + +The main files that ``configure`` generates -- and which you might want to +check -- are: -Finally, you will run into some things that are not supported on your -target platform. Forget about the ``posix`` module in the beginning. You can -simply comment it out of the ``config.c`` file. +* A :file:`pyconfig.h` file tailored for your platform. + If you need to create this manually, start with :cpy-file:`pyconfig.h.in`, + read the comments, and turn on definitions that apply to your platform. +* A :file:`config.c` file, which lists the built-in modules you support. + Until you get dynamic extension loading to work, all compiled modules + you need to import will need to be listed here. + The file is generated from :cpy-file:`Modules/config.c.in`. +* A :file:`Makefile` with instructions to put everything together. + If one isn't generated, try compiling all the ``*.c`` files, and fix the + errors -- or omit files that don't look important. + For example, forget about the ``posix`` module + (:cpy-file:`Modules/posixmodule.c`) in the beginning: don't compile it, + and comment it out of the :file:`config.c` file. Keep working on it until you get a ``>>>`` prompt. You may have to disable the importing of ``site.py`` by passing the ``-S`` option. When you have a prompt, @@ -38,6 +176,9 @@ At some point you will want to use the ``os`` module; this is the time to start thinking about what to do with the ``posix`` module. It is okay to simply comment out functions in the ``posix`` module that cause problems; the remaining ones will be quite useful. +You can use the same approach for other modules too, of course. Before you are done, it is highly recommended to run the Python regression test suite, as described in :ref:`runtests`. +You will probably need to skip tests that do not make sense; for inspiration +look at how that's done for the WASI platform. diff --git a/developer-workflow/stdlib.rst b/developer-workflow/stdlib.rst index b683e55e96..691fd8e4bd 100644 --- a/developer-workflow/stdlib.rst +++ b/developer-workflow/stdlib.rst @@ -109,7 +109,7 @@ Python). This prevents a divergence between the code that is included in the stdlib and that which is released outside the stdlib (typically done to provide the module to older versions of Python). It also removes the burden of forcing the core team to have to redirect bug reports or changes to an external issue -tracker and :abbr:`VCS (version control system)`. +tracker and VCS (version control system). Someone involved with the development of the module must promise to help maintain the module in the stdlib for two years. @@ -124,9 +124,9 @@ Proposal process If the module you want to propose adding to the stdlib meets the requirements, you may propose its inclusion -by following the :abbr:`PEP (Python Enhancement Proposal)` process. +by following the PEP (Python Enhancement Proposal) process. See :pep:`1` for details, -and the :pep:`PEP index <0>` for previously-accepted PEPs +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/clinic/howto.rst b/development-tools/clinic/howto.rst index 359c53e903..8c713a33eb 100644 --- a/development-tools/clinic/howto.rst +++ b/development-tools/clinic/howto.rst @@ -1419,24 +1419,32 @@ The generated glue code looks like this: .. code-block:: c static PyObject * - _io_TextIOWrapper__CHUNK_SIZE_get(textio *self, void *Py_UNUSED(context)) + _io_TextIOWrapper__CHUNK_SIZE_get(PyObject *self, void *Py_UNUSED(context)) { PyObject *return_value = NULL; Py_BEGIN_CRITICAL_SECTION(self); - return_value = _io_TextIOWrapper__CHUNK_SIZE_get_impl(self); + return_value = _io_TextIOWrapper__CHUNK_SIZE_get_impl((textio *)self); Py_END_CRITICAL_SECTION(); return return_value; } static int - _io_TextIOWrapper__CHUNK_SIZE_set(textio *self, PyObject *value, void *Py_UNUSED(context)) + _io_TextIOWrapper__CHUNK_SIZE_set(PyObject *self, PyObject *value, void *Py_UNUSED(context)) { int return_value; + + if (value == NULL) { + PyErr_Format(PyExc_AttributeError, + "attribute '_CHUNK_SIZE' of '%.100s' objects cannot be deleted", + Py_TYPE(self)->tp_name); + return -1; + } Py_BEGIN_CRITICAL_SECTION(self); - return_value = _io_TextIOWrapper__CHUNK_SIZE_set_impl(self, value); + return_value = _io_TextIOWrapper__CHUNK_SIZE_set_impl((textio *)self, value); Py_END_CRITICAL_SECTION(); + return return_value; } @@ -1446,6 +1454,45 @@ The generated glue code looks like this: The *value* parameter for a "setter" is added implicitly by Argument Clinic. It is possible to create a docstring for the property by adding it to the ``@getter``. + The accessors of the same attribute must share the C basename; + declaring the same accessor twice is an error. + +The setter slot of :c:type:`PyGetSetDef` is used both for setting and for +deleting the attribute: the setter is called with ``NULL`` as the value to +delete it. +As shown above, the generated setter rejects the deletion with an +:exc:`AttributeError` before calling the "impl" function. + +If the attribute can be deleted, add the ``@deleter`` directive after +``@setter``. +The "impl" function is then called with ``NULL`` and is responsible for +handling this case, as in this example taken from +:cpy-file:`Objects/funcobject.c`:: + + /*[clinic input] + @critical_section + @setter + @deleter + function.__annotations__ + [clinic start generated code]*/ + +.. code-block:: c + + static int + function___annotations___set_impl(PyFunctionObject *self, PyObject *value) + { + if (value == Py_None) + value = NULL; + /* Legal to del f.func_annotations. + * Can only set func_annotations to NULL (through C api) + * or a dict. */ + if (value != NULL && !PyDict_Check(value)) { + PyErr_SetString(PyExc_TypeError, + "__annotations__ must be set to a dict object"); + return -1; + } + ... + } And then the implementation will work the same as a Python method which is decorated by :py:class:`property`: @@ -1570,3 +1617,94 @@ and update your unit tests to reflect the new behaviour. If you forget to update your input block during the alpha and beta phases, the compiler warning will turn into a compiler error when the release candidate phase begins. + + +.. _clinic-howto-remove-parameter: + +How to remove a parameter +------------------------- + +A parameter cannot be removed right away: +as mandated by Python's backwards-compatibility policy (see :pep:`387`), +passing it must first emit a :exc:`DeprecationWarning` for two releases. +The ``[until ...]`` prefix marks a parameter which is going away and names +the release in which it will be removed:: + + /*[clinic input] + module foo + myfunc + a: object + [until 3.18] b: object = None + * [from 3.18] + c: object = None + [clinic start generated code]*/ + +Passing an argument for *b* now emits: + +.. code-block:: none + + DeprecationWarning: Passing the argument 'b' to myfunc() is deprecated. It will be removed in Python 3.18. + +A deprecated parameter must have a default value, because calls which do not +pass it must already be valid. + +Removing a parameter shifts the position of every parameter which follows it, +so they should become keyword-only in the same release, +using the ``* [from ...]`` syntax described above. +This is why *c* is deprecated as a positional parameter in the example above. +Argument Clinic enforces this for positional-only parameters: +only the last of them can be deprecated, because there is no way to pass +a positional-only parameter which follows a removed one. + +As with the ``[from ...]`` syntax described above, C preprocessor directives +are generated for emitting compiler warnings if the ``[until ...]`` prefix has +not been removed from the Argument Clinic input when the deprecation period is +over. +Then remove the parameter and the corresponding argument of the "impl" +function. + +.. versionadded:: 3.16 + + +.. _clinic-howto-rename-parameter: + +How to rename a parameter +------------------------- + +Renaming a positional-only parameter is backward compatible: +its name cannot be used in a call, so it is enough to change it. + +For a positional-or-keyword or a keyword-only parameter the name is a part of +the API, so the old name can only be removed after a deprecation period. +Change the name of the parameter, and add an optional keyword-only parameter +with the old name, the C name of the renamed parameter and the ``[until ...]`` +prefix:: + + /*[clinic input] + module foo + myfunc + source: object = None + flag: bool = False + * + [until 3.18] input as source: object = None + [clinic start generated code]*/ + +A parameter which shares the C variable of a preceding parameter is an +alternative name (an *alias*) of it: +both names fill the same argument of the "impl" function, and only one of them +can be used in a call, so ``myfunc(1, input=2)`` and +``myfunc(source=1, input=2)`` raise :exc:`TypeError`. +An alias is declared after all other parameters, but it fills the slot of +the parameter which it renames, so ``myfunc(input=1, flag=True)`` works. +It is not shown in the signature, which for the function above is +``($module, /, source=None, flag=False)``. + +Passing an argument for the old name now emits: + +.. code-block:: none + + DeprecationWarning: Passing the argument 'input' to myfunc() is deprecated. Use 'source' instead. It will be removed in Python 3.18. + +When the deprecation period is over, remove the alias. + +.. versionadded:: 3.16 diff --git a/development-tools/clinic/index.rst b/development-tools/clinic/index.rst index a6ddd5c721..20a834e2d8 100644 --- a/development-tools/clinic/index.rst +++ b/development-tools/clinic/index.rst @@ -148,7 +148,7 @@ Terminology Command-line interface ---------------------- -The Argument Clinic :abbr:`CLI (Command-Line Interface)` is typically used to +The Argument Clinic CLI (Command-Line Interface) is typically used to process a single source file, like this: .. code-block:: shell-session diff --git a/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/help-documenting.rst b/documentation/help-documenting.rst index 23520375cb..d9894573cb 100644 --- a/documentation/help-documenting.rst +++ b/documentation/help-documenting.rst @@ -92,8 +92,8 @@ section containing multiple problems; instead, file several issues so that it is easier to break the work up for multiple people and more efficient review. For help with the finer points of English technical writing, mention the -`@python/proofreaders `__ -team in your issue or pull request in any `@python `__ +:gh-python-team:`proofreaders` +team in your issue or pull request in any :github:`python` repo. If you'd like to join the team, `open a core-workflow issue `__ similar to diff --git a/documentation/markup.rst b/documentation/markup.rst index 5ba8e4c7af..8341278914 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 @@ -699,18 +699,23 @@ As :ref:`previously mentioned `, Sphinx uses interpreted text roles of the form ``:rolename:`content``` to insert semantic markup in documents. -In the CPython documentation, there are a couple common cases +In the CPython documentation, there are a few common cases where simpler markup should be used: * ``*arg*`` (rendered as *arg*) for function and method arguments. + * ````True````/````False````/````None```` for ``True``/``False``/``None``. +* ``Full Spelling (abbreviation)`` for abbreviations and acronyms. + + The ``:abbr:`` role generates HTML which is not accessible to some forms of + assistive technology and mobile users. + In addition, the CPython documentation defines a few custom roles: -* ``:cve:`YYYY-NNNNN```: link to a Common Vulnerabilities and Exposures entry. -* ``:cwe:`NNN```: link to a Common Weakness Enumeration entry. * ``:gh:`ID```: link to a GitHub issue. * ``:issue:`ID```: link to a bugs.python.com issue. +* ``:oss-fuzz:`ID```: link to an OSS-Fuzz issue. * ``:pypi:`NAME```: link to a project on PyPI. * ``:source:`PATH```: link to a source file on GitHub. @@ -970,6 +975,16 @@ in a different style: The following roles generate external links: +.. describe:: cve + + Link to a `Common Vulnerabilities and Exposures `__ + entry. You can link to a specific section by using ``:cve:`number#anchor```. + +.. describe:: cwe + + Link to a `Common Weakness Enumeration `__ entry. + You can link to a specific section by using ``:cwe:`number#anchor```. + .. describe:: pep A reference to a Python Enhancement Proposal. This generates appropriate diff --git a/documentation/style-guide.rst b/documentation/style-guide.rst index 28e4f21682..9747651b60 100644 --- a/documentation/style-guide.rst +++ b/documentation/style-guide.rst @@ -58,6 +58,41 @@ of these entities are not assigned any special markup, but the preferred spellings are given in :ref:`specific words` to aid authors in maintaining the consistency of presentation in the Python documentation. + +Use simple language +=================== + +Avoid esoteric phrasing where possible. Our audience is world-wide and may not +be native English speakers. + +Don't use Latin abbreviations like "e.g." or "i.e." where English words will do, +such as "for example" or "that is." + +In general, the first time an acronym or abbreviation is used on a page, spell +it out. +Prefer to write out the full term and follow it with the acronym in parentheses. +For example, write "Basic Multilingual Plane (BMP)". +Commonly understood acronyms, such as "HTML" and "UTF-8", should not be expanded. + + +Charged terminology to avoid +============================ + +Avoid terminology that may be considered insensitive or exclusionary. + +.. list-table:: + :header-rows: 1 + + * - Avoid + - Instead + * - whitelist + - allowlist + * - blacklist + - blocklist, denylist + * - master/slave + - main, parent/child, server/client, primary/secondary + + .. _specific words: Specific words @@ -84,6 +119,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 hyphen: "open source is a collaboration model." + POSIX The name assigned to a particular group of standards. This is always uppercase. @@ -92,7 +132,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'. @@ -111,33 +151,30 @@ Unix 1970s. -Use simple language -=================== +Type names +========== -Avoid esoteric phrasing where possible. Our audience is world-wide and may not -be native English speakers. +When writing the names of types in prose, indicate that the name is a type by +writing the name of the type exactly as it appears in source, styled as a class +reference or an unlinked class. For example, refer to dict as ``:class:`dict`‌`` +or ``:class:`!dict`‌``. -Don't use Latin abbreviations like "e.g." or "i.e." where English words will do, -such as "for example" or "that is." +Links should be used according to the :ref:`guidance on links `. +Some type names are commonly understood ideas or nouns outside of Python. +For example, "tuples" are a general programming concept, as distinct from the +``tuple`` type. When referring to general ideas, do not style the relevant word +as a type. -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 +Many types have descriptive names which may or may not exactly match their type +name. For example, "context variables" describes ``contextvars.ContextVar``, +and both "dict" and "dictionary" are used to describe ``dict``. Once it is clear +that the text refers to a specific type, use the naming which suits the context: +in the case of ``dict``, any of "dict", "dictionary", or "``:class:`dict```" may +be best. +Descriptive names should be written as common nouns, meaning they are lowercase +when not at the start of a sentence or phrase. .. index:: diataxis .. _diataxis: @@ -185,6 +222,8 @@ Please consult the `Diátaxis `__ guide for more detail. +.. _style-guide-links: + Links ===== @@ -198,7 +237,7 @@ the second mention is more appropriate for a link. Some units are long enough to have a few repeated links. Use judgement to decide when a link will help the reader. -We use the :pypi:`linklint Sphinx extension ` to suppress two kinds +We use the :pypi:`linklint Sphinx extension ` to suppress two kinds of excessive links: references in a section to itself and duplicate references in a paragraph. Previously, editors had to carefully use an exclamation mark in a Sphinx reference (``:func:`!map```) to prevent such links. @@ -235,7 +274,7 @@ Bad example (creating worry in the mind of a reader): Good example (establishing confident knowledge in the effective use of the language): - A best practice for using files is use a try/finally pair to explicitly + A best practice for using files is to use a try/finally pair to explicitly close a file after it is used. Alternatively, using a with-statement can achieve the same effect. This assures that files are flushed and file descriptor resources are released in a timely manner. @@ -339,7 +378,7 @@ model to alternative implementations and because the operation of the "grouper" is more easily shown in code than in English prose. An example of when not to use a code equivalent is for the :func:`oct` function. -The exact steps in converting a number to octal doesn't add value for a user +The exact steps in converting a number to octal don't add value for a user trying to learn what the function does. @@ -354,7 +393,7 @@ your best to connect-the-dots, but don't talk down to them or waste their time. The tutorial is meant for newcomers, many of whom will be using the tutorial to evaluate the language as a whole. The experience needs to be positive and not leave the reader with worries that something bad will happen if they make a -misstep. The tutorial serves as guide for intelligent and curious readers, +misstep. The tutorial serves as a guide for intelligent and curious readers, saving details for the how-to guides and other sources. Be careful accepting requests for documentation changes from the rare but vocal diff --git a/documentation/translations/coordinating.rst b/documentation/translations/coordinating.rst index 82cfce74fa..1936dbb7bb 100644 --- a/documentation/translations/coordinating.rst +++ b/documentation/translations/coordinating.rst @@ -15,7 +15,7 @@ Discussions about translations occur on the Python Docs Discord `#translations channel `__ and the `translations category `_ of the Python Discourse. -For administrative issues, ping ``@python/editorial-board``. +For administrative issues, ping :gh-python-team:`editorial-board`. Starting a new translation diff --git a/documentation/translations/overview-dark.svg b/documentation/translations/overview-dark.svg new file mode 100644 index 0000000000..ff8ce2ca8b --- /dev/null +++ b/documentation/translations/overview-dark.svg @@ -0,0 +1,4 @@ + + +DocumentationPublishDocsbuild-scriptsTranslationrepositoryUploadTranslationPO filesTranslateExtract stringsDocumentationsourceBuild translation diff --git a/documentation/translations/overview-light.svg b/documentation/translations/overview-light.svg new file mode 100644 index 0000000000..39b71714c4 --- /dev/null +++ b/documentation/translations/overview-light.svg @@ -0,0 +1,4 @@ + + +DocumentationPublishDocsbuild-scriptsTranslationrepositoryUploadTranslationPO filesTranslateExtract stringsDocumentationsourceBuild translation diff --git a/documentation/translations/python-logo-languages.svg b/documentation/translations/python-logo-languages.svg new file mode 100644 index 0000000000..0286904455 --- /dev/null +++ b/documentation/translations/python-logo-languages.svg @@ -0,0 +1,233 @@ + + + + diff --git a/documentation/translations/translating.rst b/documentation/translations/translating.rst index e8e3dc32f4..8f7ebe92d2 100644 --- a/documentation/translations/translating.rst +++ b/documentation/translations/translating.rst @@ -6,8 +6,8 @@ Translating .. highlight:: rest -There are several documentation translations already -in production and can be found in the language switcher; others are works in +Several documentation translations are already in production and can be found +in the language switcher; others are works in progress. To get started read your repository's contributing guide, which is generally the ``README`` file, and this page. If your language isn’t listed below, feel free to start the translation! @@ -34,6 +34,9 @@ For more details about translations and their progress, see - Julien Palard (:github-user:`JulienPalard`) - `AFPy/python-docs-fr `__, :github:`mirror ` + * - German (de) + - Swen Bachmann (:github-user:`sba72`) + - :github:`GitHub ` * - `Greek (el) `__ - | Lysandros Nikolaou (:github-user:`lysnikolaou`), | Fanis Petkos (:github-user:`thepetk`), @@ -61,15 +64,18 @@ For more details about translations and their progress, see * - `Korean (ko) `__ - 오동권 (:github-user:`flowdas`) - :github:`GitHub ` - * - Marathi (mr) - - Sanket Garade (:github-user:`sanketgarade`, `email `__) - - :github:`GitHub ` * - Lithuanian (lt) - Albertas Gimbutas (:github-user:`albertas`, `email `__) - `original announcement `__ + * - Marathi (mr) + - Satvik Mudgal (:github-user:`satvikmudgal`, `email `__) + - :github:`GitHub `, + `coordinator transfer `__ * - Persian (fa) - - Alireza Shabani (:github-user:`revisto`) - - :github:`GitHub ` + - | Alireza Shabani (:github-user:`revisto`), + | Sepehr Rasouli (:github-user:`sepehr-rs`) + - :github:`GitHub `, + `Telegram `__ * - `Polish (pl) `__ - | Maciej Olko (:github-user:`m-aciek`), | Stan Ulbrych (:github-user:`StanFromIreland`) @@ -83,12 +89,19 @@ For more details about translations and their progress, see `guide `__, `Telegram `__, `article `__ - * - `Romanian (ro) `__ + * - Punjabi (pa) + - | Bhuvansh Kataria (:github-user:`BHUVANSH855`), + | Mohit Yadav (:github-user:`mohityadav8`), + | Yashraj Jangra (:github-user:`Yashraj-Jangra`) + - :github:`GitHub `, + `Transifex `_ + * - `Romanian (ro) `__ - Octavian Mustafa (:github-user:`octaG-M`, `email `__) - :github:`GitHub ` - * - Russian (ru) - - Daniil Kolesnikov (:github-user:`MLGRussianXP`, `email `__) - - :github:`GitHub `, + * - `Russian (ru) `__ + - Daniil Kolesnikov (:github-user:`dkqzz`, `email `__) + - :github:`GitHub `, + `Telegram `__, `original announcement `__ * - `Simplified Chinese (zh-cn) `__ - | Shengjing Zhu (:github-user:`zhsj`), @@ -98,14 +111,14 @@ For more details about translations and their progress, see * - `Spanish (es) `__ - Raúl Cumplido (:github-user:`raulcd`) - :github:`GitHub ` - * - Swedish (sv) + * - `Swedish (sv) `__ - Daniel Nylander (:github-user:`yeager`) - :github:`GitHub ` * - Tamil (ta) - | Murugan Santhosh (:github-user:`terminaljoint`), | Hari (:github-user:`nammahari`) - :github:`GitHub `, - `Discord `__ + `Discord `__ * - `Traditional Chinese (zh-tw) `__ - | 王威翔 Matt Wang (:github-user:`mattwang44`), | Josix Wang (:github-user:`josix`) @@ -118,6 +131,77 @@ For more details about translations and their progress, see - Dmytro Kazanzhy (:github-user:`kazanzhy`, `email `__) - :github:`GitHub `, `Transifex `_ + * - Vietnamese (vi) + - Duc-Tam Nguyen (:github-user:`tamnd`) + - :github:`GitHub `, + `Transifex `_ + + +Overview +======== + +.. figure:: overview-light.svg + :class: only-light + :align: center + :alt: Strings are extracted from the source documentation into PO files, + translated, uploaded to the translation repository, built by + docsbuild-scripts, and published. + +.. figure:: overview-dark.svg + :class: only-dark + :align: center + :alt: Strings are extracted from the source documentation into PO files, + translated, uploaded to the translation repository, built by + docsbuild-scripts, and published. + +.. Drawn with Excalidraw: https://excalidraw.com/#json=eh8rCFZJwziIPgj9BjK-r,VEOHnb-9FdAHZNaG4zfH6g + +Roughly, translation works as follows: + +- Translators work on gettext PO file catalogs generated from the Python docs + `by Sphinx `__, + rather than editing the documentation directly. +- Teams work in different ways. For example, some have translators work + locally, while others use tools like :ref:`Transifex `. + Messages without a translation fall back to English, so a translation can be + published before it is complete. +- Translations are committed to the :ref:`translation repository `. +- Completed translations are automatically pulled in from the repository by + :github:`docsbuild-scripts ` and published to + docs.python.org. + + +Motivation +========== + +The Python documentation is written in English, but Python is taught, learned, +and used around the world, in many languages. English is the native language +of only about 5% of the world's population, and fewer than a fifth more speak +it as an additional language [#f1]_. For many people, learning Python also +means overcoming a language barrier. They must learn not only Python, but also +enough English to be able to use the language's documentation. + +The United Nations Open Source Principles call on projects both to provide +documentation and to foster inclusive participation [#f2]_. Providing +documentation only in English limits who can benefit from it and who can +participate in the wider Python community. + +.. figure:: python-logo-languages.svg + :align: center + :alt: The word "Python" written in dozens of languages. + +.. Image drawn manually in Inkscape. The text in python-logo-languages.svg was + converted to paths before exporting for consistent rendering, contact + StanFromIreland for the original. + +Translations make Python's documentation accessible to a much wider audience. +They allow people to learn and use Python in a language they are confident in, +reducing the additional burden of learning through English. + +Translation also improves the English documentation. Translators review the +source text closely and often find bugs. As a result, translation therefore +benefits not only readers of other languages, but everyone who uses and +contributes to Python's documentation. How to get help @@ -363,7 +447,7 @@ The coordination team for my language is inactive, what do I do? If you would like to coordinate, open a pull request in the `devguide `__ adding yourself to the table -at the top of this page, and ping ``@python/editorial-board``. +at the top of this page, and ping :gh-python-team:`editorial-board`. How do I merge translations back in after docs are moved? @@ -411,6 +495,12 @@ with the commit hash from before the files were moved): After running ``pomerge``, review the changes and commit the updated files. You may also need to rewrap the lines (see :pypi:`powrap`). +.. rubric:: Footnotes + +.. [#f1] Ethnologue, `What is the most spoken language? + `__ +.. [#f2] `United Nations Open Source Principles + `__ .. _discourse: https://discuss.python.org/c/documentation/translations/ .. _tx: https://explore.transifex.com/python-doc/python-newest/ diff --git a/getting-started/ai-tools.rst b/getting-started/ai-tools.rst new file mode 100644 index 0000000000..cd69987ca2 --- /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, +without explanation, regardless of whether AI tools were used or not. + +If a contributor repeatedly opens unproductive issues or PRs, they may be +blocked from contributing to the project because it is disruptive and +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..33717b14d9 100644 --- a/getting-started/git-boot-camp.rst +++ b/getting-started/git-boot-camp.rst @@ -265,7 +265,7 @@ To re-apply the last stashed change:: Comparing changes ----------------- -View all non-commited changes:: +View all non-committed changes:: $ git diff @@ -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:: @@ -550,60 +557,97 @@ dismissing your previous review that requested changes. Note that pushing new changes after the auto-merge flow was enabled does **NOT** stop it. + +.. _branch-merge: + Backporting merged changes -------------------------- -A pull request may need to be backported into one of the maintenance branches -after it has been accepted and merged into ``main``. It is usually indicated -by the label ``needs backport to X.Y`` on the pull request itself. +After a pull request has been merged into ``main``, it may need to be backported +to one or more :ref:`maintenance ` or :ref:`security ` +branches. This is indicated by the :samp:`needs backport to {X.Y}` labels on +the pull request. -Use the utility script -`cherry_picker.py `__ -to backport the commit. +``miss-islington`` will automatically attempt to create backport PRs for the +versions indicated by these labels. If ``miss-islington`` cannot create a +backport PR due to conflicts, you can use the :pypi:`cherry-picker` tool to +create the backport and resolve the conflicts manually. -The commit hash for backporting is the squashed commit that was merged to -the ``main`` branch. On the merged pull request, scroll to the bottom of the -page. Find the event that says something like: +You need the commit hash of the squashed commit that was merged into +the ``main`` branch. ``miss-islington`` should post a comment when it is unable +to create the backport automatically, including the full command and commit hash. +If that comment is not posted, look for an event on the merged +pull request similar to: .. code-block:: text merged commit into python:main ago. -By following the link to ````, you will get the full commit hash. +By following the link to ````, you can get the full commit hash. -Alternatively, the commit hash can also be obtained by the following Git +Alternatively, the commit hash can also be obtained with the following Git commands:: $ git fetch upstream - $ git rev-parse ":/gh-12345" + $ git rev-parse ":/gh-" + +These commands print the hash of the commit whose message contains ``gh-``. + +You can then use the commit hash and the :pypi:`cherry-picker` tool to create +the backport. In the following command, ```` is the target maintenance +branch (for example, ``3.12``): + +.. code-block:: text -The above commands will print out the hash of the commit containing -``"gh-12345"`` as part of the commit message. + $ cherry_picker -When formatting the commit message for a backport commit: leave the original -one as is and delete the number of the backport pull request. +Then, follow the instructions provided. You will have to identify the files +with conflicts, fix them, and build and run applicable tests if necessary. +When you are finished, ``git add`` all modified files and run +``cherry_picker --continue`` to push the backport. -✅ Example of good backport commit message: +The tool usually generates the commit message automatically. If it does not, use +the following format: Keep the original commit message unchanged, except for +removing the backport pull request number (``(#XXXXX)``). At the end of the +message, append a ``(cherry picked from commit )`` line. + +The format of a correct backport commit message is: .. code-block:: text :class: good - gh-12345: Improve the spam module (GH-777) + [] gh-XXXXX: (GH-XXXXX) + + - * Add method A to the spam module - * Update the documentation of the spam module + (cherry picked from commit ) - (cherry picked from commit 62adc55) +Here ``gh-XXXXX`` is the GitHub *issue* number, and ``(GH-XXXXX)`` is the +original *pull request* number. -❌ Example of bad backport commit message: +An example of a bad backport commit message: .. code-block:: text :class: bad - gh-12345: Improve the spam module (GH-777) (#888) + gh-XXXXX: Custom title (GH-XXXXX) (#XXXXX) + + * Custom message + +.. _backport-pr: + +When opening the backport PR, its title PR must follow the same format as the +commit title, beginning with the ``[]`` prefix and referencing the +original PR with a ``(GH-XXXXX)`` suffix. For example: + +.. code-block:: text + :class: good + + [3.15] gh-12345: Fix the spam module (GH-24680) + +After the backport PR is opened, ``miss-islington`` will link it to the original +PR and remove the corresponding backport label. - * Add method A to the spam module - * Update the documentation of the spam module Editing a pull request prior to merging --------------------------------------- diff --git a/getting-started/index.rst b/getting-started/index.rst index 05ee67a3bc..c83de10a0e 100644 --- a/getting-started/index.rst +++ b/getting-started/index.rst @@ -7,9 +7,10 @@ Getting started .. toctree:: :maxdepth: 5 + quick-reference setup-building fixing-issues git-boot-camp pull-request-lifecycle getting-help - generative-ai + ai-tools diff --git a/getting-started/pull-request-lifecycle.rst b/getting-started/pull-request-lifecycle.rst index 78c8cfff06..5cba5f233e 100644 --- a/getting-started/pull-request-lifecycle.rst +++ b/getting-started/pull-request-lifecycle.rst @@ -16,58 +16,8 @@ that you create a branch in Git, make your changes, push those changes to your fork on GitHub (``origin``), and then create a pull request against the official CPython repository (``upstream``). - -.. _pullrequest-quickguide: - -Quick guide -=========== - -`Clear communication`_ is key to contributing to any project, especially an -`Open Source`_ project like CPython. - -Here is a quick overview of how you can contribute to CPython: - -#. `Create an issue`_ that describes your change. If it is trivial - (like :ref:`typo fixes `), or an issue already exists, - you can skip this step. - -#. :ref:`Create a new branch in Git ` from the - ``main`` branch - -#. Work on changes: fix a bug or add a new feature - -#. :ref:`Run tests ` and ``make patchcheck`` - -#. :ref:`Commit ` and :ref:`push ` - changes to your GitHub fork - -#. `Create Pull Request`_ on GitHub to merge a branch from your fork - -#. Make sure the :ref:`continuous integration checks on your Pull Request - are green ` (successful) - -#. Review and address `comments on your Pull Request`_ - -#. When your changes are merged, you can :ref:`delete the PR branch - ` - -#. Celebrate contributing to CPython! :) - -Don't force-push ----------------- - -In order to keep the commit history intact, please avoid squashing or amending -history and then force-pushing to the PR. Reviewers often want to look at -individual commits. -When the PR is merged, everything will be squashed into a single commit. - -.. _Clear communication: https://opensource.guide/how-to-contribute/#how-to-submit-a-contribution -.. _Open Source: https://opensource.guide/ -.. _create an issue: https://github.com/python/cpython/issues -.. _CPython: https://github.com/python/cpython -.. _use HTTPS: https://help.github.com/articles/which-remote-url-should-i-use/ -.. _Create Pull Request: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request -.. _comments on your Pull Request: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/commenting-on-a-pull-request +For a cheat-sheet reference, see the +:ref:`quick reference on creating pull requests `. .. _pullrequest-steps: @@ -185,6 +135,15 @@ message. It is usually okay to leave that as-is and close the editor. See `the merge command's documentation `__ for a detailed technical explanation. +Don't force-push +---------------- + +In order to keep the commit history intact, avoid squashing or amending +history and then force-pushing to the PR. +Reviewers often want to look at individual commits. + +CPython uses squash merges, so PRs will end up as single commits when merged. + .. _good-prs: @@ -290,6 +249,8 @@ in the "What's New in Python" entry. A change that needs an entry in "What's New in Python" is very likely not suitable for inclusion in a maintenance release. +.. _news-entry-howto: + How to add a NEWS entry ----------------------- @@ -297,6 +258,11 @@ How to add a NEWS entry ``NEWS`` entry can be created by using `blurb-it `_, or the :pypi:`blurb` tool and its ``blurb add`` command. +.. tip:: + + You can read more about ``blurb`` in its + :github:`repository `. + If you are unable to use the tool, then you can create the ``NEWS`` entry file manually. The ``Misc/NEWS.d`` directory contains a sub-directory named ``next``, which contains various sub-directories representing classifications @@ -701,10 +667,16 @@ list of executed checks. Clicking :guilabel:`Update branch` next to this message will merge in the latest changes from the base branch into the PR. If this still doesn't help with the failure on the PR, you can try -to re-run that particular failed check. Go to the red GitHub Action job, -click on the :guilabel:`Re-run jobs` button on the top right, and select -:guilabel:`Re-run failed jobs`. The button will only be present when all other -jobs finished running. +to re-run that particular failed check. Note that the :guilabel:`Re-run jobs` +button is only visible to members of the core and triage team. If you have those +permissions, go to the failed GitHub Action job, click :guilabel:`Re-run jobs` on +the top right, and select :guilabel:`Re-run failed jobs`. The button is only +present once all other jobs have finished. + +If don't have access to the button, ask a member of the teams to +re-run the jobs for you. Alternatively, you can re-trigger CI yourself by +pushing an empty commit, or by updating your branch with the +:guilabel:`Update branch` button. Re-running failed jobs shouldn't be your first instinct but it is occasionally helpful because distributed systems can have intermittent failures, and @@ -738,11 +710,10 @@ do not take it personally! Your work is still appreciated regardless of whether your pull request is merged. Balancing what *does* and *does not* go into Python is tricky and we simply cannot accept everyone's contributions. -But if your pull request is merged it will then go into Python's -:abbr:`VCS (version control system)` to be released -with the next feature release of Python. It may also be backported to older -versions of Python as a bugfix if the core team member doing the merge believes -it is warranted. +But if your pull request is merged it will then go into Python's VCS (version +control system) to be released with the next feature release of Python. +It may also be backported to older versions of Python as a bugfix if the core +team member doing the merge believes it is warranted. Crediting diff --git a/getting-started/quick-reference.rst b/getting-started/quick-reference.rst new file mode 100644 index 0000000000..909e2f41a8 --- /dev/null +++ b/getting-started/quick-reference.rst @@ -0,0 +1,171 @@ +.. _quick-reference: + +=============== +Quick reference +=============== + +.. include:: /include/activate-tab.rst + +Here are the basic steps needed to get set up and open a pull request. + +This is meant as a checklist and cheat-sheet, not a comprehensive guide. +For complete instructions see the :ref:`setup guide ` and the +:ref:`pull request guide `. + + +Set up Git +========== + +Install and set up ``Git``. + +For detailed setup information, see :ref:`"Install Git" `. +There is also a more detailed :ref:`Git guide and cheat sheet `. + +Fork and clone the repo +----------------------- + +Fork `the CPython repository `__ +to your GitHub account and clone the repo using:: + + git clone https://github.com//cpython + cd cpython + +For detailed information, see :ref:`"Get the source code" `. + + +Build Python +============ + +.. tab:: Unix + + .. code-block:: shell + + ./configure --config-cache --with-pydebug && make -j $(nproc) + +.. tab:: macOS + + .. code-block:: shell + + ./configure --config-cache --with-pydebug && make -j$(sysctl -n hw.logicalcpu) + +.. tab:: Windows + + .. code-block:: dosbatch + + PCbuild\build.bat -e -d + +See also :ref:`more detailed instructions `, +:ref:`how to install and build dependencies `, +and the platform-specific pages for :ref:`Unix `, +:ref:`macOS `, and :ref:`Windows `. + + +Run the tests +============= + +.. tab:: Unix + + .. code-block:: shell + + ./python -m test -j0 + +.. tab:: macOS + + .. code-block:: shell + + ./python.exe -m test -j0 + + .. note:: + :ref:`Most ` macOS systems use + :file:`./python.exe` in order to avoid filename conflicts with + the ``Python`` directory. + +.. tab:: Windows + + .. code-block:: dosbatch + + .\python.bat -m test -j0 + + +See also :ref:`how to write and run tests `. + + +.. _pullrequest-quickguide: + +Create issues and pull requests +=============================== + +Create issues for nontrivial changes +------------------------------------ + +For most changes, `create an issue `__ +before submitting a pull request. +Trivial changes like typo fixes do not need issues. + +Create work branches +-------------------- + +Work on a feature or fix in a new branch in Git from the ``main`` branch:: + + git checkout -b fix-issue-12345 main + +Make changes, then :ref:`commit ` and +:ref:`push to your fork `. + +Document your changes +--------------------- + +Many changes deserve a NEWS entry which documents what changed. +For more information on how and when to write news entries, +see :ref:`"Updating NEWS and What's New in Python" `. + +A news entry can be created locally with the :pypi:`blurb` tool +and its ``blurb add`` command or online after a pull request has +been opened with `blurb-it `__. + +For more information about how to create news entries, see +:ref:`"How to add a NEWS entry" `. + +Create pull requests +-------------------- + +Create pull requests on GitHub from your branches, on your fork, and make sure +to put the relevant issue number in ``gh-NNNNNN`` format in the pull request title. +For example: + +.. code-block:: text + + gh-12345: Fix some bug in spam module + +See also, GitHub's documentation on `creating pull requests`_. + +For more detailed guidance, follow the :ref:`step-by-step pull request guide `. + +.. note:: + + First time contributors will need to sign the Contributor Licensing + Agreement (CLA) as described in the :ref:`Licensing ` section of + this guide. + +.. _creating pull requests: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request + +Work on your pull request +------------------------- + +Make sure the :ref:`continuous integration checks on your pull +request are green ` (successful). + +Read and respond to reviewer comments on your pull request. + +See also, GitHub's documentation on `commenting on pull requests`_. + +.. _commenting on pull requests: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/commenting-on-a-pull-request + +Don't force-push +---------------- + +In order to keep the commit history intact, avoid squashing or amending +history and then force-pushing to the PR. +Reviewers often want to look at individual commits. + +CPython uses squash merges, so PRs will end up as single commits when merged. diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index 6acc7ee578..c29f86c87b 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 ------- @@ -718,7 +742,7 @@ Platforms/Apple --help`` for more details. You can also run the test suite in Xcode itself. This is required if you want to run on a physical device. See the `iOS README -`__ +`__ for details. .. c_compile_and_build_end @@ -740,68 +764,88 @@ some of CPython's modules (for example, ``zlib``). For Unix-based systems, we try to use system libraries whenever available. This means optional components will only build if the relevant system headers - are available. The best way to obtain the appropriate headers will vary by - distribution, but the appropriate commands for some popular distributions - are below. + are available. The best way to obtain these headers varies by distribution, + but commands for some popular distributions are given below. + + .. tab:: Fedora / RHEL / CentOS + + On **Fedora**, **RHEL**, **CentOS** and other ``dnf``-based systems:: + + $ sudo dnf install git pkg-config + $ sudo dnf install dnf-plugins-core # install this to use 'dnf builddep' + $ sudo dnf builddep python3 + + Some optional development dependencies are not included in the above. + To install some additional dependencies for optional build and test components:: + + $ sudo dnf install \ + gcc gcc-c++ gdb lzma glibc-devel libstdc++-devel openssl-devel \ + readline-devel zlib-devel libzstd-devel libffi-devel bzip2-devel \ + xz-devel sqlite sqlite-devel sqlite-libs libuuid-devel gdbm-libs \ + perf expat expat-devel mpdecimal python3-pip + + .. tab:: Debian / Ubuntu + + On **Debian**, **Ubuntu**, and other ``apt``-based systems, try to get the + dependencies for the Python you're working on by using the ``apt`` command. + + First, make sure you have enabled the source packages in the sources list. + Where those live depends on your release. - On **Fedora**, **RHEL**, **CentOS** and other ``dnf``-based systems:: + On **Ubuntu 24.04 and later**, and on other releases using the deb822 + format, the sources are in ``/etc/apt/sources.list.d/ubuntu.sources``. + Add ``deb-src`` to the ``Types`` field of the entries you want sources + for:: - $ sudo dnf install git pkg-config - $ sudo dnf install dnf-plugins-core # install this to use 'dnf builddep' - $ sudo dnf builddep python3 + $ sudo nano /etc/apt/sources.list.d/ubuntu.sources - Some optional development dependencies are not included in the above. - To install some additional dependencies for optional build and test components:: + changing:: - $ sudo dnf install \ - gcc gcc-c++ gdb lzma glibc-devel libstdc++-devel openssl-devel \ - readline-devel zlib-devel libzstd-devel libffi-devel bzip2-devel \ - xz-devel sqlite sqlite-devel sqlite-libs libuuid-devel gdbm-libs \ - perf expat expat-devel mpdecimal python3-pip + Types: deb + to:: - On **Debian**, **Ubuntu**, and other ``apt``-based systems, try to get the - dependencies for the Python you're working on by using the ``apt`` command. + Types: deb deb-src - First, make sure you have enabled the source packages in the sources list. - You can do this by adding the location of the source packages, including - URL, distribution name and component name, to ``/etc/apt/sources.list``. - Take Ubuntu 22.04 LTS (Jammy Jellyfish) for example:: + On **Ubuntu 22.04 and other releases using the one-line format**, add the + location of the source packages, including URL, distribution name and + component name, to ``/etc/apt/sources.list``. Taking Ubuntu 22.04 LTS + (Jammy Jellyfish) as the example:: - $ deb-src http://archive.ubuntu.com/ubuntu/ jammy main + $ deb-src http://archive.ubuntu.com/ubuntu/ jammy main - Alternatively, uncomment lines with ``deb-src`` using an editor, for - example:: + Alternatively, uncomment the lines with ``deb-src`` using an editor, for + example:: - $ sudo nano /etc/apt/sources.list + $ sudo nano /etc/apt/sources.list - For other distributions, like Debian, change the URL and names to correspond - with the specific distribution. + For other distributions, like Debian, change the URL and names to correspond + with the specific distribution. - Then you should update the packages index:: + Then you should update the packages index:: - $ sudo apt-get update + $ sudo apt-get update - Now you can install the build dependencies via ``apt``:: + Now you can install the build dependencies via ``apt``:: - $ sudo apt-get build-dep python3 - $ sudo apt-get install pkg-config + $ sudo apt-get build-dep python3 + $ sudo apt-get install pkg-config - If you want to build all optional modules, install the following packages and - their dependencies:: + If you want to build all optional modules, install the following packages and + their dependencies:: - $ sudo apt-get install build-essential gdb lcov pkg-config \ - libbz2-dev libffi-dev libgdbm-dev libgdbm-compat-dev liblzma-dev \ - libncurses5-dev libreadline6-dev libsqlite3-dev libssl-dev \ - lzma lzma-dev tk-dev uuid-dev zlib1g-dev libmpdec-dev libzstd-dev \ - inetutils-inetd + $ sudo apt-get install build-essential gdb lcov pkg-config \ + libbz2-dev libffi-dev libgdbm-dev libgdbm-compat-dev liblzma-dev \ + libncurses5-dev libreadline6-dev libsqlite3-dev libssl-dev \ + lzma lzma-dev tk-dev uuid-dev zlib1g-dev libmpdec-dev libzstd-dev \ + inetutils-inetd - Note that Debian 12 and Ubuntu 24.04 do not have the ``libmpdec-dev`` - package. You can safely remove it from the install list above and the - Python build will use a bundled version. But we recommend using the system - `libmpdec `__ library. - Either build it from sources or install this package from - https://deb.sury.org. + Note that Debian 12 and Ubuntu 24.04 do not have the ``libmpdec-dev`` + package. You can safely remove it from the install list above and the + Python build will use a bundled version. But we recommend using the system + `libmpdec `__ library. + Either build it from sources or install this package from + https://deb.sury.org. .. tab:: macOS @@ -833,7 +877,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 +885,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 +895,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 +918,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 +928,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``:: @@ -1077,8 +1125,7 @@ every rule. See also :ref:`building-doc`. ``Grammar`` - Contains the :abbr:`PEG (Parser Expression Grammar)` grammar file for - Python. + Contains the PEG (Parser Expression Grammar) grammar file for Python. ``Include`` Contains all interpreter-wide header files. @@ -1308,4 +1355,4 @@ also apply here. .. _cpython-devcontainers repo: https://github.com/python/cpython-devcontainers -.. include:: ../links.rst +.. include:: /include/links.rst diff --git a/links.rst b/include/links.rst similarity index 100% rename from links.rst rename to include/links.rst diff --git a/index.rst b/index.rst index 18aca244e1..84936f3ecf 100644 --- a/index.rst +++ b/index.rst @@ -1,4 +1,5 @@ .. _devguide-main: +.. _contributing: ======================== Python Developer's Guide @@ -8,24 +9,16 @@ Python Developer's Guide .. highlight:: bash -This guide is a comprehensive resource for :ref:`contributing ` +This guide is a comprehensive resource for contributing to Python_ -- for both new and experienced contributors. It is :ref:`maintained ` by the same community that maintains Python. We welcome your contributions! - -.. _contributing: - -Contributing ------------- - -We encourage everyone to contribute to Python. To help you, we have put up this -developer's guide. If you still have questions after reviewing the material in +Start with the area that best matches what you want to do. +If you still have questions after reviewing the material in this guide, then the `Core Python Mentorship`_ group is available to help guide new contributors through the process. -Guide for contributing to Python: - .. list-table:: :widths: 10 10 10 :header-rows: 1 @@ -40,6 +33,7 @@ Guide for contributing to Python: * :ref:`rst-primer` * :ref:`translating` * :ref:`devguide` + * :ref:`ai-tools` - * :ref:`setup` * :ref:`help` @@ -49,124 +43,45 @@ Guide for contributing to Python: * :ref:`communication` * :ref:`gitbootcamp` * :ref:`devcycle` + * :ref:`ai-tools` - * :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. +around within the guide, be aware that some sections build on each other, +so you may need to backtrack for missing concepts or terminology. -A number of individuals from the Python community have contributed to a series +For broader open-source contribution advice, a number of individuals from the +Python community have contributed to a series of excellent guides at `Open Source Guides `__. For example, `How to Contribute to Open Source `__. +.. admonition:: You don't have to be a compiler engineer to work on Python -- Savannah Ostrowski -.. _quick-reference: - -Quick reference ---------------- - -Here are the basic steps needed to get set up and open a pull request. -This is meant as a checklist, once you know the basics. For complete -instructions please see the :ref:`setup guide `. - -1. Install and set up :ref:`Git ` and other dependencies - (see the :ref:`Git Setup ` page for detailed information). - -2. Fork `the CPython repository `__ - to your GitHub account and :ref:`get the source code ` using:: - - git clone https://github.com//cpython - cd cpython - -3. Build Python: - - .. tab:: Unix - - .. code-block:: shell - - ./configure --with-pydebug && make -j $(nproc) - - .. tab:: macOS - - .. code-block:: shell - - ./configure --with-pydebug && make -j8 - - .. tab:: Windows + .. container:: compact-video - .. code-block:: dosbatch + .. youtube:: WGXXxGLBVF4 + :privacy_mode: + :width: 100% - PCbuild\build.bat -e -d - See also :ref:`more detailed instructions `, - :ref:`how to install and build dependencies `, - and the platform-specific pages for :ref:`Unix `, - :ref:`macOS `, and :ref:`Windows `. - -4. :ref:`Run the tests `: - - .. tab:: Unix - - .. code-block:: shell - - ./python -m test -j3 - - .. tab:: macOS - - .. code-block:: shell - - ./python.exe -m test -j8 - - .. note:: - :ref:`Most ` macOS systems use - :file:`./python.exe` in order to avoid filename conflicts with - the ``Python`` directory. - - .. tab:: Windows - - .. code-block:: dosbatch - - .\python.bat -m test -j3 - -5. Create a new branch where your work for the issue will go, for example:: - - git checkout -b fix-issue-12345 main - - If an issue does not already exist, please `create it - `__. Trivial issues (for example, typos) do - not require an issue. - -6. Push the branch on your fork on GitHub and :ref:`create a pull request - `. Include the issue number using ``gh-NNNNNN`` in the - pull request title. For example: - - .. code-block:: text - - gh-12345: Fix some bug in spam module - -7. Add a News entry into the ``Misc/NEWS.d/`` directory as individual file. The - news entry can be created by using `blurb-it `__, - or the :pypi:`blurb` tool and its ``blurb add`` - command. Please read more about ``blurb`` in its - `repository `__. +Quick reference +--------------- .. note:: - First time contributors will need to sign the Contributor Licensing - Agreement (CLA) as described in the :ref:`Licensing ` section of - this guide. + The quick reference documentation has been moved to serve as a cheat-sheet and overview + in :ref:`Getting started `. +Go to :ref:`the new quick reference `. Proposing changes to Python itself ---------------------------------- @@ -288,6 +203,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..a63e5aa8ae 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,11 +1,13 @@ -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 +sphinx_linklint +sphinxcontrib-youtube>=1.5.0 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..dd084b9eb0 --- /dev/null +++ b/security/index.rst @@ -0,0 +1,12 @@ +.. _security: + +======== +Security +======== + +.. toctree:: + :maxdepth: 5 + + policy + psrt + sbom diff --git a/security/policy.rst b/security/policy.rst new file mode 100644 index 0000000000..33228e8e80 --- /dev/null +++ b/security/policy.rst @@ -0,0 +1,204 @@ +=============== +Security policy +=============== + +.. important:: + + :ref:`Python Security Response Team ` (PSRT) members balance this work + against many other responsibilities. Please be thoughtful about the time and + attention your report requires. Repeated failure to respect the security policy + will result in future reports being rejected, or the reporter being banned + from the ``python`` GitHub organization, regardless of technical merit. + +What types of bugs are vulnerabilities? +--------------------------------------- + +**Not all bugs are vulnerabilities.** + +To avoid causing duplicate work for PSRT members, **all potential** reports +must be evaluated against the relevant threat models +prior to being submitted to the PSRT. +Where possible, cite the relevant threat model to show that +the latter has been considered while determining whether +to report a bug as a vulnerability. + +Vulnerabilities must be exploitable from code, configurations, +pre-conditions, or deployments that may exist in the real world. +A vulnerability that only affects code unlikely to be used +in a production program will not be accepted. + +Documented functionality is not considered a vulnerability. +For example, :mod:`pickle`, :mod:`marshal`, :mod:`shelve`, :func:`eval`, +and :func:`exec` are documented to execute arbitrary Python code that is +supplied as data. The :mod:`ctypes` module is documented to enable modifying +arbitrary locations in memory. + +CPython does not support sandboxing untrusted Python code as a security +boundary, so escapes from such a sandbox are not vulnerabilities in Python +and should be reported to the sandbox's developers instead. + +Vulnerabilities must not depend on malicious control of Python's launch +conditions, including (but not limited to) command line arguments, environment variables, or +modifications to files on the target system. We assume that, at the time Python +is executed, the environment is as intended by the legitimate user, and any +malicious variation from this cannot be mitigated by Python itself. + +Vulnerabilities that affect availability (such as DoS, ReDoS, crashes, +dead-locks, and resource exhaustion) must be +triggerable with data inputs that are reasonably sized for the use case. +Availability vulnerabilities must also demonstrate an "upward" change in posture +for the attacker, rather than a "lateral" one. +This is to avoid handling performance improvements as security vulnerabilities. + +Exceptions are an expected part of control flow when processing inputs. +Unhandled exceptions are not considered crashes and are not, by themselves, +security vulnerabilities. + +Vulnerabilities in dependencies of Python (such as zlib, Tcl/Tk, or OpenSSL) +are not vulnerabilities in Python unless Python's use of the dependency +interferes with secure use of the dependency. +For example, a vulnerability in the bundled copy of zlib in Python is a +vulnerability in zlib, not Python. + +What versions of Python accept reports? +--------------------------------------- + +Python accepts vulnerability reports and will +assign CVE IDs for :ref:`supported Python versions ` that have a +status of :ref:`"bugfix" or "security" `. Versions that are +not yet stable (status of :ref:`"feature" or "prerelease" `) +are not eligible for CVE IDs. If the vulnerability only exists in prerelease +versions (alphas, betas, release candidates), then the issue should be reported +as a regular bug. +Prior to submitting a report, check whether the issue has already been +resolved on the ``main`` branch and only requires backporting. + +Sometimes features may be marked as +"experimental" in Python, even in a stable Python version. +These features are not eligible for security vulnerabilities. +Instead, open a public GitHub issue. + +If a vulnerability is platform-dependent, check if the platform is +supported per :pep:`11`. +Vulnerabilities that exclusively affect unsupported platforms +are not treated as vulnerabilities in Python. + +As per the :pep:`Unsupported Platforms section of PEP 11 <11#unsupported-platforms>`, +porting Python to an unsupported platform is treated as a third-party project. +For these reports, the PSRT treats them as vulnerability reports for a third-party +port, not as Python vulnerabilities. +If you choose to report such an issue to Python, follow the requirements +of this guide and include the relevant platform and maintainer context. +The PSRT forwards these reports to platform maintainers (or other interested +parties) and they are usually handled under the relevant maintainers' security +policies. These reports will be closed if the maintainers are unknown or unresponsive. + +What to include and how to structure a vulnerability report? +------------------------------------------------------------ + +For your vulnerability report to be handled efficiently by +the PSRT, the report must include certain information and +be formatted correctly: + +* For the initial report and follow-up communications, avoid + overly long, verbose, or excessive structure (such as headers or tables). + Reports should be a few sentences describing the vulnerability. Ideally include + a proof-of-concept script that reproduces the issue and provides a clear + indication of whether the vulnerability is still present (such as exiting with + ``1`` if vulnerable and ``0`` if not vulnerable). +* When reporting large numbers or "batches" of vulnerabilities or + searching for potential vulnerabilities using an LLM, you as a reporter must + verify the factual validity (such as whether APIs have been hallucinated) + of the content in all reports prior to submission to the PSRT. +* Do not include severity or CVSS information in your initial report, + this information will be determined by the PSRT. +* Ideally, include a minimal patch with the mitigation for the report. +* Always include the versions of Python that were tested, + and indicate which were found to be vulnerable. +* Submit reports as plain-text only, including attachments. + No PDFs, binaries, notebooks, or other files that cannot be safely reviewed. + If your proof-of-concept depends on a specially constructed binary file, + please include a script to construct it rather than the file itself. +* Proof-of-concept scripts longer than a few lines should be wrapped with a + `collapsed section`_ using ``
`` for better readability. +* Reports that do not contain a potential security vulnerability (such as spam + or requesting compliance or due-diligence work) + will be discarded without a reply. + +.. _collapsed section: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-collapsed-sections + +How to submit a vulnerability report? +------------------------------------- + +Submit all potential security vulnerability reports for CPython +by `opening a new ticket `_. +Do not open a public GitHub issue to report a security vulnerability. +For all other projects (such as pip, python.org and tools) or if you're +not sure where to send your report, send an email to +`security@python.org `__. + +Here's what to expect for how a vulnerability report will be handled: + +* Reporter reports the vulnerability privately to the PSRT. +* If the PSRT determines the report isn't a vulnerability, the reporter + may open a public issue. +* If the PSRT determines the report is a vulnerability, the PSRT will + accept the report and a CVE ID will be assigned by the PSF CNA. + Do not publicly reference the assigned CVE ID before its record is published, + as the report and ID remain provisional and may still be changed. +* Once a public pull request containing a fix is merged to CPython, + the advisory and CVE record will be published with attribution. + +For more information about how the PSRT handles vulnerabilities, +see :ref:`psrt-vulnerability-process`. + +When are security fixes released or backported? +----------------------------------------------- + +Advisories and CVE records are published after a security fix is first merged. +The CVE record contains information about the patch and will be kept up-to-date +as the patch is backported and released to Python versions. + +According to :pep:`602`, Python versions receive five years of security updates +after the new Python version is released. However, these security updates +are not published according to a fixed schedule or as a result of any security +fix being available. The schedule for security updates is determined by +the Release Manager. Users are encouraged to apply patches themselves ahead +of patches being merged and released if necessary. + +Security fixes that only affect binary installers (such as macOS and Windows) +will not be published to Python release streams that are +:ref:`source-only `. + +Some security fixes may require introducing backwards-incompatible behavior +changes. In these circumstances, the Python Steering Council +will decide with the relevant Release Managers whether to introduce +a backwards incompatible change to fix a security vulnerability +in a stable version. This may affect whether a security fix is backported +to all Python versions or enabled by default. See the CVE record for +more information. + +Code of conduct +--------------- + +Well-being and safety of the Python Security Response Team members is +prioritized over the technical merit of vulnerability reports. +Despite communications being private, vulnerability reporting is subject +to the `PSF Code of Conduct`_. Violations will be reported to the Code of +Conduct team with undisclosed vulnerability information removed, if applicable. + +.. _GHSA: https://github.com/python/cpython/security/advisories/new +.. _PSF Code of Conduct: https://policies.python.org/python.org/code-of-conduct/ + +CVE Numbering Authority (CNA) +----------------------------- + +The Python and pip projects are scoped under the +`Python Software Foundation CVE Numbering Authority `__ +(CNA). This means you must submit all security +vulnerability reports to the PSRT for a CVE ID +to be issued for Python or pip. To reach the PSF +CNA contact directly, send an email to +`cna@python.org `__. + +.. _CNA: https://www.python.org/cve-numbering-authority/ diff --git a/developer-workflow/psrt-emeritus.csv b/security/psrt-emeritus.csv similarity index 89% rename from developer-workflow/psrt-emeritus.csv rename to security/psrt-emeritus.csv index f9d26bfba4..6f5cb17665 100644 --- a/developer-workflow/psrt-emeritus.csv +++ b/security/psrt-emeritus.csv @@ -3,7 +3,6 @@ Christian Heimes,tiran, Georg Brandl,birkenfeld, Huzaifa Sidhpurwala,, Jesse Noller,, -Kushal Das,kushaldas, Mark Hammond,mhammond, Nam Nguyen,, Neal Norwitz,, diff --git a/developer-workflow/psrt.csv b/security/psrt.csv similarity index 79% rename from developer-workflow/psrt.csv rename to security/psrt.csv index da67432d9b..f6dff2073b 100644 --- a/developer-workflow/psrt.csv +++ b/security/psrt.csv @@ -2,14 +2,18 @@ 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 +Ee Durbin,ewdurbin, Emma Smith,emmatyping, Glyph Lefkowitz,glyph, Gregory P. Smith,gpshead, Hugo van Kemenade,hugovk,Release Manager -Jacob Coffee,JacobCoffee, +Jacob Coffee,JacobCoffee,Admin +Jelle Zijlstra,JelleZijlstra, +Kushal Das,kushaldas, +Kirill Podoprigora,eclips4, Larry Hastings,larryhastings, Łukasz Langa,ambv,Release Manager Ned Deily,ned-deily,"Admin, Release Manager" @@ -20,7 +24,7 @@ Pradyun Gedam,pradyunsg, Savannah Ostrowski,savannahostrowski,Release Manager Serhiy Storchaka,serhiy-storchaka, Seth Larson,sethmlarson,Admin -Stan Ulbrych,StanFromIreland, +Stan Ulbrych,StanFromIreland,Admin Steve Dower,zooba,Release Manager Thomas Wouters,Yhg1s,Release Manager Tim Peters,tim-one, diff --git a/developer-workflow/psrt.rst b/security/psrt.rst similarity index 79% rename from developer-workflow/psrt.rst rename to security/psrt.rst index c2501e44b7..c2a98eff2e 100644 --- a/developer-workflow/psrt.rst +++ b/security/psrt.rst @@ -1,9 +1,13 @@ +.. _psrt: + 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 ------- @@ -82,6 +86,8 @@ following additional responsibilities: * Running nomination elections, including counting final votes and giving the Steering Council an opportunity to veto nominations via email. +.. _psrt-vulnerability-process: + Triaging a vulnerability report ------------------------------- @@ -106,9 +112,11 @@ New report in GitHub Security Advisories (GHSA) Once a report is in GHSA, a "Coordinator" must be assigned to be responsible for moving the report through the process. The "Coordinator" role is assigned using a "Credit" in a GHSA ticket -(Select 'Edit' > 'Credit' > Add GitHub username and the role 'Coordinator'). +(Select :guilabel:`Edit` > :guilabel:`Credit` > Add a GitHub username and the +'Coordinator' role). + +.. important:: -.. warning:: Assigning the "Coordinator" role to each GHSA ticket is important, as this metadata records whether a PSRT member is `"active" according to PEP 811`_ to avoid being removed due to inactivity. @@ -116,9 +124,9 @@ The "Coordinator" role is assigned using a "Credit" in a GHSA ticket .. _"active" according to PEP 811: https://peps.python.org/pep-0811/#psrt-membership-policy If a GHSA ticket is idle for three days without a coordinator -assigned a PSRT member who is not a Release Manager +assigned, a PSRT member who is not a Release Manager or Steering Council member will be automatically assigned -as coordinator by the PSRT bot. +as coordinator by the :ref:`PSRT bot `. If a coordinator can't complete the process they must find a replacement coordinator in the PSRT and re-assign the GHSA ticket. @@ -135,20 +143,28 @@ vulnerability, or as a security vulnerability. If the Coordinator needs help from core team experts in making the determination, the experts may be added as 'Collaborators' to the GHSA ticket. Accepted security vulnerabilities will be moved to the 'Draft' state in GHSA. +Only repository admins can accept advisories; however, PSRT members may accept +reports through the PSRT bot by prepending ``[ACCEPTED]`` to the GHSA's +title. If the report isn't a vulnerability, coordinators close the GHSA ticket after optionally opening a public GitHub issue. Note that reporters often will not open a GitHub issue on their own, as there is no longer an incentive -for them to do so without a CVE being assigned. +for them to do so without a CVE being assigned. Similarly to accepting, +only repository admins can close advisories; however, PSRT members may close +reports through the PSRT bot by prepending ``[CLOSED]`` (for regular bugs), +``[INVALID]`` (for spam), ``[DUPLICATE]`` (for duplicates), or ``[COMPLETED]`` +(for completed tickets where an advisory has been issued) to the GHSA's title. Remediating a vulnerability report ---------------------------------- Once a report has been accepted as a vulnerability, the remediation development process begins. Coordinators move the GHSA ticket to a 'Draft' -state using the green 'Accept as Draft' button. Once in this state, +state using the green :guilabel:`Accept as Draft` button (repository admins) +or the PSRT bot's ``[ACCEPTED]`` title tag. Once in this state, the PSRT bot will automatically assign a CVE ID from the Python Software -Foundation CVE Numbering Authority. +Foundation CVE Numbering Authority and create a temporary private fork. Once a vulnerability has been accepted there are three things the Coordinator must prepare before sending an advisory and @@ -178,9 +194,11 @@ for help in calculating a severity from other PSRT members. Developing a patch privately ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Patch development can initially be done privately by selecting the -'Start a temporary private fork' button within the GHSA ticket. Note that -due to the size of Git repositories, this fork repository may +Patch development can begin once a report has been accepted, as the PSRT bot +will automatically create a temporary private fork for the advisory. +The fork can also be created earlier by repository admins or reporters by selecting +the :guilabel:`Start a temporary private fork` button within the GHSA ticket. +Note that due to the size of Git repositories, this fork repository may take several minutes to create. Once the fork has been created any PSRT member or GHSA collaborator can clone the fork and develop a fix and push a branch: @@ -230,15 +248,18 @@ This patch can then be applied and pushed to the public GitHub repository: git apply ./ghsa-abcd-efgh-ijkl.patch git push origin branch-name -.. warning:: **IMPORTANT:** CPython's backport infrastructure - is used for tracking backported patches. Use **one GitHub issue - per CVE** to accurately track backports of vulnerability fixes. - For new CVEs, even when related to a previous issue, **open a +.. important:: + + CPython's backport infrastructure is used for tracking backported patches. + Use **one GitHub issue per CVE** to accurately track backports of vulnerability + fixes. For new CVEs, even when related to a previous issue, **open a new GitHub issue** to accurately track fixed versions. -.. warning:: **IMPORTANT:** Don't select the green 'Merge pull request' - or 'Publish advisory' buttons within GHSA. Advisories are published - to the mailing list, and the 'Merge pull request' button within +.. important:: + + Repository admins should not select the green :guilabel:`Publish advisory` + or :guilabel:`Merge pull request` buttons within GHSA. Advisories are published + to the mailing list, and the :guilabel:`Merge pull request` button within GHSA bypasses all continuous integration and branch protection steps. Use a public pull request instead. @@ -257,14 +278,40 @@ if applying the patch isn't the only way to mitigate the vulnerability. * The advisory email will be received by PSF CVE Numbering Authority operators and used to publish a CVE record. * Begin the backporting process for all Python branches still receiving - security updates. Add the :gh-label:`type-security` and :gh-label:`release-blocker` labels - to each backport pull request so that release managers can find them prior + security updates. Add the :gh-label:`type-security` and :gh-label:`release-blocker` + labels to each backport pull request so that release managers can find them prior to releasing. After an advisory email is sent, the GHSA ticket can be closed. +As only repository admins can close advisories directly, PSRT members +can prepend ``[COMPLETED]`` to the GHSA's title and the PSRT bot +will close the ticket. .. _advisory template: #advisory-email +.. _psrt-bot: + +The PSRT bot +------------ + +The :github:`PSRT bot ` is a GitHub App +that automates parts of the GHSA workflow described above. GitHub only +allows repository admins to modify security advisories, so the bot enables +any PSRT member to move a report through the process using title tags. + +The bot runs hourly (or by manual dispatch) and for each open GHSA ticket: + +* Adds the PSRT GitHub team as collaborators, giving members access to new reports. +* Moves tickets from the 'Triage' to the 'Draft' state when the title contains + the ``[ACCEPTED]`` tag. +* Closes tickets when the title contains one of the closing tags + (``[CLOSED]``, ``[INVALID]``, ``[DUPLICATE]``, or ``[COMPLETED]``). +* For accepted ('Draft') tickets, creates the temporary private fork if one + doesn't already exist, and reserves a CVE ID. + +Tags are case-insensitive and can appear anywhere in the title, though for visibility +they are prepended. + Handling code signing certificate reports ----------------------------------------- @@ -317,7 +364,11 @@ Submit using GitHub Security Advisories Thanks for submitting this report. We use GitHub Security Advisories for triaging vulnerability reports, - please submit your report here: + please review our security policy before submitting: + + https://devguide.python.org/security/policy/ + + Then submit your report here: https://github.com/python/cpython/security/advisories/new @@ -331,6 +382,15 @@ Rejecting a vulnerability report If you are interested in working on this further, you can optionally open a public issue on GitHub. +Rejecting a duplicate report +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + Thanks for your report. We've determined that this submission is a duplicate + of an issue that is already being tracked internally. Please refrain from + public disclosure until the issue has been resolved. + Advisory email ~~~~~~~~~~~~~~ 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/coverage.rst b/testing/coverage.rst index 48c2efc985..54782caf11 100644 --- a/testing/coverage.rst +++ b/testing/coverage.rst @@ -7,7 +7,7 @@ Increase test coverage .. include:: /include/activate-tab.rst Python development follows a practice that all semantic changes and additions -to the language and :abbr:`stdlib (standard library)` are accompanied by +to the language and stdlib (standard library) are accompanied by appropriate unit tests. Unfortunately Python was in existence for a long time before the practice came into effect. This has left chunks of the stdlib untested which is not a desirable situation to be in. 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/new-buildbot-worker.rst b/testing/new-buildbot-worker.rst index aea43a782a..97127b1412 100644 --- a/testing/new-buildbot-worker.rst +++ b/testing/new-buildbot-worker.rst @@ -48,8 +48,10 @@ compiled Python. In order to set up the buildbot software, you will need to obtain an identifier and password for your worker so it can join the fleet. Open an issue in the `configuration repository `__ -to discuss adding your worker and to obtain the -needed workername and password. You can do some of the steps that follow +to discuss adding your worker and to obtain the needed workername and password. +(The steps the administrators follow are documented under `"Add a worker" +`__ in the README.) +You can do some of the steps that follow before having the credentials, but it is easiest to have them before the "buildbot worker" step below. diff --git a/testing/oss-fuzz.rst b/testing/oss-fuzz.rst new file mode 100644 index 0000000000..4bf4a5b419 --- /dev/null +++ b/testing/oss-fuzz.rst @@ -0,0 +1,54 @@ +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 :gh-python-team:`fuzzers` team on GitHub. + +OSS-Fuzz bug reports are private when filed, so access to crash details and +reproducer test cases is limited to those listed in the ``auto_ccs`` fields of +the OSS-Fuzz project configuration files. Those listed can log into +https://oss-fuzz.com/ with their Google account to view crash details, +reproducer test cases, and project statistics. +If you need access, contact the :gh-python-team:`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/github-bpo-faq.rst b/triage/github-bpo-faq.rst index f4f8b16dd4..383bd7d53e 100644 --- a/triage/github-bpo-faq.rst +++ b/triage/github-bpo-faq.rst @@ -1,3 +1,5 @@ +:orphan: + .. _github-bpo-faq: .. _gh-faq: @@ -5,97 +7,8 @@ GitHub issues for BPO users =========================== -Here are some frequently asked questions about how to do things in -GitHub issues that you used to be able to do on `bpo`_. - -Before you ask your own question, make sure you read :ref:`tracker` -and :ref:`triaging` (specifically including :ref:`gh-labels`) as those -pages include a lot of introductory material. - -How to format my comments nicely? -================================= - -There is a wonderful `beginner guide to writing and formatting on GitHub -`__. -Highly recommended. - -One pro-tip we can sell you right here is that if you want to paste -some longer log as a comment, attach a file instead (see how below). -If you still insist on pasting it in your comment, do it like this:: - -
- This is the summary text, click me to expand - - Here goes the long, long text. - It will be collapsed by default! -
- -How to attach files to an issue? -================================ - -Drag them into the comment field, wait until the file uploads, and GitHub -will automatically put a link to your file in your comment text. - -How to link to file paths in the repository when writing comments? -================================================================== - -Use Markdown links. If you link to the default GitHub path, the file -will link to the latest current version on the given branch. - -You can get a permanent link to a given revision of a given file by -`pressing "y" `__. - -How to do advanced searches? -============================ - -Use the `GitHub search syntax`_ or the interactive `advanced search`_ form -that generates search queries for you. - -Where is the "nosy list"? -========================= - -Subscribe another person to the issue by tagging them in the comment with -``@username``. - -If you want to subscribe yourself to an issue, click the -:guilabel:`🔔 Subscribe` button in the sidebar. - -Similarly, if you were tagged by somebody else but -decided this issue is not for you, you might click the -:guilabel:`🔕 Unsubscribe` button in the sidebar. - -There is no exact equivalent of the "nosy list" feature, so to preserve -this information during the transfer, we list the previous members of -this list in the first message on the migrated issue. - -How to add issue dependencies? -============================== - -Add a checkbox list like this in the issue description:: - - - [x] #739 - - [ ] https://github.com/octo-org/octo-repo/issues/740 - - [ ] Add delight to the experience when all tasks are complete :tada: - -then those will become sub-tasks on the given issue. Moreover, GitHub will -automatically mark a task as complete if the other referenced issue is -closed. More details in the `official GitHub documentation -`__. - -What on earth is a "mannequin"? -=============================== - -For issues migrated to GitHub from `bpo`_ where the authors or commenters -are not core developers, we opted not to link to their GitHub accounts -directly. Users not in the `python organization on GitHub -`__ might not like comments to -appear under their name from an automated import. Others never linked GitHub on -`bpo`_ in the first place so linking their account, if any, would be impossible. - -In those cases a "mannequin" account is present to help follow the conversation -that happened in the issue. In case the user did share their GitHub account -name in their `bpo`_ profile, we use that. Otherwise, their classic `bpo`_ -username is used instead. +Here are some frequently asked questions about things you used to be able +to do on `bpo`_ that work differently in GitHub issues. Where did the "resolution" field go? ==================================== @@ -120,5 +33,3 @@ particularly useful outside of the change log. .. _bpo: https://bugs.python.org/ -.. _GitHub search syntax: https://docs.github.com/en/search-github/getting-started-with-searching-on-github/understanding-the-search-syntax -.. _advanced search: https://github.com/search/advanced diff --git a/triage/index.rst b/triage/index.rst index a054ad62f2..495d93917f 100644 --- a/triage/index.rst +++ b/triage/index.rst @@ -8,5 +8,4 @@ Issues and triaging issue-tracker triaging labels - github-bpo-faq triage-team diff --git a/triage/issue-tracker.rst b/triage/issue-tracker.rst index 4dd0815e4c..e55cda18c5 100644 --- a/triage/issue-tracker.rst +++ b/triage/issue-tracker.rst @@ -1,33 +1,33 @@ .. _issue-tracker: .. _tracker: -============= -Issue tracker -============= - - +======================= Using the issue tracker ======================= +The `issue tracker`_ is hosted on GitHub, alongside the codebase and pull requests. + +.. note:: + + Prior to moving the issue tracker to GitHub, + Python used to use a dedicated `Roundup`_ instance as its issue tracker. + That `old bug tracker`_ was hosted under the domain ``bugs.python.org`` + (sometimes called :dfn:`bpo` or :dfn:`BPO` for short). A read-only version is + available on that domain for historical purposes. All ``bpo`` data has been + migrated to the current issue tracker on GitHub. + Old issues are still referenced in the :samp:`bpo-{NNN}` format, + where ``bpo-12345`` refers to ``https://bugs.python.org/issue12345``. + + +Reporting an issue +================== + If you think you have found a bug in Python, you can report it to the -`issue tracker`_. The `issue tracker`_ is now hosted on GitHub, alongside -the codebase and pull requests. Documentation bugs can also be reported there. +`issue tracker`_. Documentation bugs can also be reported there. -If you would like to file an issue about this devguide, please do so at the -`devguide repo`_. +If you would like to file an issue about this devguide, please do so in the +:github:`devguide repository ` instead. -.. note:: - Prior to moving the issue tracker to GitHub, - Python used to use a dedicated `Roundup`_ instance as its issue tracker. - That `old bug tracker`_ was hosted under the domain ``bugs.python.org`` - (sometimes called ``bpo`` for short). A read-only version is - available on that domain for historical purposes. All ``bpo`` data has been - migrated to the current `issue tracker`_ on GitHub. - - If you're familiar with ``bpo`` and would like to learn more about GitHub - issues, please read this page, and the :ref:`triaging` page as they - provide good introductory material. There is also a :ref:`gh-faq` - document to answer some of the more popular questions. Checking if a bug already exists -------------------------------- @@ -43,11 +43,12 @@ already been reported. Checking if the problem is an existing issue will: is needed To see if an issue already exists, search the bug database using the search box -above the list of bugs on the issues page. A form-based `advanced search`_ query -builder is also available on GitHub to help creating the text query you need. +above the list of bugs on the issues page. See :ref:`searching-gh-issues` +for more information. -Reporting an issue ------------------- + +Creating a new issue +-------------------- If the problem you're reporting is not already in the `issue tracker`_, you can report it using the green :guilabel:`New issue` button on the right of the search @@ -63,14 +64,15 @@ available choices include, for example: * **Report a security vulnerability**: privately report a security vulnerability. Depending on your choice, a dedicated form template will appear. -In particular, you'll notice that the last button actually takes you to +In particular, you'll notice that one of the buttons actually takes you to the `Python Discourse`_ (``discuss.python.org``), where many Python-related discussions take place. The submission form has only two fields that you need to fill: * in the **Title** field, enter a *very* short description of the problem; - less than ten words is good; + less than ten words is good; don't include "labels" like ``[feature]`` + as we use GitHub labels; * in the **Write** field, describe the problem in detail using hints from the template that was put in that field for you. Be sure to include what you expected to happen, what did happen, and how to replicate the @@ -85,12 +87,67 @@ Use the :ref:`experts` to know who wants to be tagged or assigned for specific areas. There are a number of additional fields like **Assignees**, **Labels**, -and **Projects**. Those are filled by triagers and core -developers and are covered in the :ref:`triaging` page. You don't need +and **Projects**. Those are filled by triagers and core team members +and are covered in the :ref:`triaging` page. You don't need to worry about those when reporting issues as a Python user. -Adding special links --------------------- + +Working with issues +=================== + +This section covers common tasks on the issue tracker, such as +searching, commenting on, and following issues. + +.. _searching-gh-issues: +.. _how-to-search-issues: + +Searching issues +---------------- + +Use the `GitHub search syntax`_ or the interactive `advanced search`_ form +that generates search queries for you. + +You can also narrow down the results by filtering by label, either with +the :guilabel:`Labels` dropdown above the list of issues or with the +:samp:`label:{name}` search qualifier. See :ref:`gh-labels` for an +overview of the labels used in the CPython repository. + + +Formatting issues and comments +------------------------------ + +There is a wonderful `beginner guide to writing and formatting on GitHub +`__. +Highly recommended. + +One pro-tip we can sell you right here is that if you want to paste +some longer log as a comment, :ref:`attach a file instead `. +If you still insist on pasting it in your comment, wrap it with a +`collapsed section`_ using ``
`` for better readability:: + +
+ This is the summary text, click me to expand + + Here goes the long, long text. + It will be collapsed by default! +
+ + +.. _attaching-to-gh-issues: +.. _how-to-attach-files-to-an-issue: + +Attaching files +--------------- + +Drag them into the comment field, wait until the file uploads, and GitHub +will automatically put a link to your file in your comment text. + + +.. _adding-special-links: +.. _how-to-link-to-file-paths-in-the-repository-when-writing-comments: + +Adding links +------------ The following abbreviations can be used in a comment to generate a link: @@ -100,31 +157,60 @@ The following abbreviations can be used in a comment to generate a link: See also the `list of autolinks supported by GitHub `_. +To link to a file in the repository, you can get a permanent link to a +given revision of the file by `pressing "y" +`__. + + Following issues ---------------- If you want to subscribe yourself to an issue, click the :guilabel:`🔔 Subscribe` -button in the sidebar. Similarly, if you were tagged by somebody else but -decided this issue is not for you, click the :guilabel:`🔕 Unsubscribe` +button in the sidebar. Subscribe another person to the issue by tagging them +in a comment with ``@username``. If you were tagged by somebody else +but decided this issue is not for you, click the :guilabel:`🔕 Unsubscribe` button in the sidebar. Note that you are automatically subscribed to -issues you created. +issues you create or comment on. + Tracking dependencies and duplicates ------------------------------------ -It is possible to use `checklists`_ to track dependencies or, -in case of meta-issues, to link to the other related issues. +It is possible to `create relationships between issues `_ to track +dependencies and in case of meta-issues, to `add sub-issues `_ +to link to the other related issues. By writing :samp:`Duplicate of #{NNN}` in a comment, you can `mark issues and PRs as duplicates `_. -Disagreement with a resolution on the issue tracker -=================================================== +.. _what-on-earth-is-a-mannequin: + +Mannequin accounts +------------------ + +For old issues migrated to GitHub from bugs.python.org (BPO) where the authors or commenters +were not core team members, we opted not to link to their GitHub accounts +directly. Users not in the `python organization on GitHub +`__ might not like comments to +appear under their name from an automated import. Others never linked GitHub on +BPO in the first place so linking their account, if any, would be impossible. + +In those cases a "mannequin" account is present to help follow the conversation +that happened in the issue. In case the user did share their GitHub account +name in their BPO profile, we use that. Otherwise, their classic BPO +username is used instead. + + +.. _disagreement-with-a-resolution-on-the-issue-tracker: + +Disagreement with a resolution +============================== As humans, we will have differences of opinions from time to time. First and foremost, please be respectful that care, thought, and volunteer time went into -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 @@ -140,19 +226,16 @@ As a reminder, issues closed by a core developer have already been carefully considered. Please do not reopen a closed issue. An issue can be closed with reason either as ``complete`` or ``not planned``. -.. seealso:: - - `The Python issue tracker `_ - Where to report issues about Python. - .. _issue tracker: https://github.com/python/cpython/issues .. _advanced search: https://github.com/search/advanced -.. _devguide repo: https://github.com/python/devguide/issues +.. _GitHub search syntax: https://docs.github.com/en/search-github/getting-started-with-searching-on-github/understanding-the-search-syntax .. _Roundup: https://www.roundup-tracker.org/ .. _Python Discourse: https://discuss.python.org/ .. _autolinks: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/autolinked-references-and-urls -.. _checklists: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/about-task-lists +.. _collapsed section: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-collapsed-sections .. _duplicates: https://docs.github.com/en/issues/tracking-your-work-with-issues/administering-issues/marking-issues-or-pull-requests-as-a-duplicate +.. _issue-rel: https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/creating-issue-dependencies +.. _sub-issues: https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/adding-sub-issues .. _Core Development Discourse category: https://discuss.python.org/c/core-dev/23 .. _old bug tracker: https://bugs.python.org/ diff --git a/triage/labels.rst b/triage/labels.rst index 96e0d8f58e..3251a384cf 100644 --- a/triage/labels.rst +++ b/triage/labels.rst @@ -121,6 +121,7 @@ Other labels * :gh-label:`easy`: for issues that are considered easy. * :gh-label:`infra`: for issues related to the infrastructure of the project (for example, GitHub Actions, dependabot, the buildbots). +* :gh-label:`invalid`: for marking spam issues/PRs. * :gh-label:`pending`: for issues/PRs that will be closed unless further feedback is provided. * :gh-label:`release-blocker`/:gh-label:`deferred-blocker`: for issues/PRs diff --git a/triage/triaging.rst b/triage/triaging.rst index 207c59082f..22c1c5b745 100644 --- a/triage/triaging.rst +++ b/triage/triaging.rst @@ -4,25 +4,48 @@ Triaging an issue ================= -This section of the devguide documents the :ref:`issue tracker ` for -users and developers. +Every issue on the :ref:`issue tracker ` needs to be triaged to make +sure everything runs smoothly. This section covers what that involves. Checklist for triaging ====================== * Read the initial message and the comments. +* :ref:`Search the tracker ` to check that the issue + isn't a duplicate. If it is, use GitHub's :guilabel:`Close as duplicate` + option and select the issue it duplicates. * Check that the title is reasonably concise, while including enough specifics so that those scanning the list of issues can quickly identify its topic. * For pull requests, ensure that the corresponding issue is added before the title (:samp:`gh-NNNNN: {Title}`). -* Set all the relevant :ref:`labels `. -* Where appropriate, set the :guilabel:`Assignees`, :guilabel:`Reviewers`, - :guilabel:`Project` fields, and possibly @mention relevant people. +* Set all the relevant :ref:`labels `. +* Where appropriate, set the :guilabel:`Assignees`, :guilabel:`Reviewers`, and + :guilabel:`Project` :ref:`fields `, and possibly @mention + relevant people. * You might also leave a brief comment about the proposed next action needed. If there is a long message list, a summary can be very helpful. -* If the issue is clearly invalid (unrelated to CPython, duplicate, spam, etc), - you can use GitHub's "Close as not planned" option. +* If the issue is clearly invalid (unrelated to CPython, spam, and + so on), you can use GitHub's :guilabel:`Close as not planned` option + and apply the :gh-label:`invalid` label. + + +.. _triage-fields: + +Issue fields +============ + +These fields can be set in the sidebar of issues and pull requests. + + +.. _triage-labels: + +Labels +------ + +Labels are the main way of categorizing issues and automating certain actions on +pull requests. Set all that apply. See :ref:`gh-labels` for more information. + Assignees --------- @@ -35,11 +58,33 @@ forward without their help; for example, they need to make a technical decision how to proceed. Also consult the :ref:`experts` as certain stdlib modules should always be assigned to a specific person. -Note that in order to assign an issue to someone, that person **must** be -a team member, likely a triager or a core developer. +Note that in order to assign an issue to someone, that person **must** +have at least triage permissions in the repository. + + +Reviewers +--------- + +This field is used to request a review from specific people. + +In most cases there is nothing to do, as the maintainers listed in the +:cpy-file:`.github/CODEOWNERS` file are automatically requested to review +pull requests touching the files they maintain. Otherwise, consult the +:ref:`experts` to find someone with a working knowledge of the affected area +or platform. + +If the person you have in mind doesn't show up in the :guilabel:`Reviewers` +dropdown (usually because they don't have the required permissions in the +repository), @mention them in a comment instead. -.. The Assignees subsection was copied from the labels.rst page in #930. - For consistency, the other fields mentioned above should be documented too. + +Project +------- + +`GitHub projects `__ are used to track +work on a specific module, platform, or interest area across issues and pull +requests. Add all the relevant ones. Note that several are added automatically +when the corresponding :ref:`label ` is added. .. _helptriage: @@ -52,9 +97,6 @@ structured and you are comfortable with the workflow, a great way to contribute is to help triage issues. Do realize, though, that experience working on Python is needed in order to effectively help triage. -Around the clock, new issues are being opened on the :ref:`issue tracker -` and existing issues are being updated. Every issue needs to be -triaged to make sure everything runs smoothly. Classifying reports ------------------- @@ -63,14 +105,14 @@ For bugs, an issue needs to: * clearly explain the bug so it can be reproduced * include all relevant platform details -* state what version(s) of Python are affected by the bug. +* state what versions of Python are affected by the bug. These are things you can help with once you have experience developing for Python: * Try reproducing the bug: if it is not explained clearly - enough for you to reproduce it, then there is a good chance a core developer - won't be able to either. + enough for you to reproduce it, then there is a good chance a core team + member won't be able to either. * See if the issue happens on a different Python version: it is always helpful to know if a bug not only affects the in-development version of Python, but whether it also affects other versions in maintenance mode. @@ -78,8 +120,9 @@ Python: Python's test suite, having that written can be very helpful. This is all helpful as it allows members of the :ref:`triage team ` -to properly classify an issue so it can be handled by the right core developers -in a timely fashion. +to properly classify an issue so it can be handled by the right core team +members in a timely fashion. + Reviewing pull requests ----------------------- @@ -88,25 +131,23 @@ If an issue has a linked pull request that has not been reviewed, you can help by making sure the pull request: * is a good solution to the problem it is trying to solve -* follows the style guides (:pep:`7`, :pep:`8`, :ref:`style-guide`, etc.) +* follows the style guides (for example, :pep:`7`, :pep:`8`, and :ref:`style-guide`) * includes proper tests * includes proper documentation changes * includes a :ref:`NEWS entry ` (if needed) * doesn't have conflicts with the ``main`` branch * :ref:`doesn't have failing CI checks ` -Doing all of this allows core developers and :ref:`triagers ` +Doing all of this allows core team members and :ref:`triagers ` to more quickly look for subtle issues that only people with extensive -experience working on Python's code base will notice. +experience working on Python's codebase will notice. See also :ref:`committing`. + Finding an issue you can help with ---------------------------------- If you want to help with triaging, you might also want to search for issues -in modules for which you have a working knowledge. Search for the name of a -module in the issue tracker, filter by label, or use the `advanced search`_ -to find these issues. - -.. _advanced search: https://github.com/search/advanced +in modules for which you have a working knowledge. See :ref:`searching-gh-issues` +for more information. diff --git a/versions.rst b/versions.rst index 58d56b3e0a..228b445d97 100644 --- a/versions.rst +++ b/versions.rst @@ -45,6 +45,7 @@ Full chart .. raw:: html :file: _static/release-cycle-all.svg +.. _version-status-key: Status key ==========