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