diff --git a/.github/workflows/documentation-links.yml b/.github/workflows/documentation-links.yml new file mode 100644 index 0000000000..d95cbd3ab7 --- /dev/null +++ b/.github/workflows/documentation-links.yml @@ -0,0 +1,17 @@ +name: Read the Docs PR preview +on: + pull_request_target: + types: + - opened + +permissions: + pull-requests: write + +jobs: + documentation-links: + runs-on: ubuntu-latest + steps: + - uses: readthedocs/actions/preview@v1 + with: + project-slug: "cpython-devguide" + single-version: "true" diff --git a/.github/workflows/release-cycle.yml b/.github/workflows/release-cycle.yml deleted file mode 100644 index 8b676d78a4..0000000000 --- a/.github/workflows/release-cycle.yml +++ /dev/null @@ -1,31 +0,0 @@ -name: Test release cycle - -on: [pull_request, push, workflow_dispatch] - -env: - FORCE_COLOR: 1 - -jobs: - test: - runs-on: ${{ matrix.os }} - strategy: - fail-fast: false - matrix: - os: [windows-latest, ubuntu-latest] - - steps: - - uses: actions/checkout@v3 - - - uses: actions/setup-python@v4 - with: - python-version: "3" - - - name: Generate release cycle output - run: python -I -bb -X dev -X warn_default_encoding -W error _tools/generate_release_cycle.py - - - name: Check for differences - run: | - git add . - git status - git diff --staged - test $(git status --porcelain | wc -l) = 0 diff --git a/.gitignore b/.gitignore index c74e78d0fa..df4dc9415a 100644 --- a/.gitignore +++ b/.gitignore @@ -9,6 +9,7 @@ __pycache__/ # Distribution / packaging .Python env/ +ENV/ venv/ build/ develop-eggs/ @@ -80,13 +81,13 @@ celerybeat-schedule # dotenv .env -# virtualenv -venv/ -ENV/ -venv/ - # Spyder project settings .spyderproject # Rope project settings .ropeproject + +# Generated CSV and SVG files +include/branches.csv +include/end-of-life.csv +include/release-cycle.svg diff --git a/Makefile b/Makefile index d1416e031b..17141ac2d8 100644 --- a/Makefile +++ b/Makefile @@ -74,7 +74,7 @@ html: ensure-venv versions @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." .PHONY: dirhtml -dirhtml: ensure-venv +dirhtml: ensure-venv versions $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." @@ -195,14 +195,14 @@ serve: "(see https://github.com/python/cpython/issues/80510)" include/branches.csv: include/release-cycle.json - $(PYTHON) _tools/generate_release_cycle.py + $(VENVDIR)/bin/python3 _tools/generate_release_cycle.py include/end-of-life.csv: include/release-cycle.json - $(PYTHON) _tools/generate_release_cycle.py + $(VENVDIR)/bin/python3 _tools/generate_release_cycle.py -include/release-cycle.mmd: include/release-cycle.json - $(PYTHON) _tools/generate_release_cycle.py +include/release-cycle.svg: include/release-cycle.json + $(VENVDIR)/bin/python3 _tools/generate_release_cycle.py .PHONY: versions -versions: include/branches.csv include/end-of-life.csv include/release-cycle.mmd +versions: venv include/branches.csv include/end-of-life.csv include/release-cycle.svg @echo Release cycle data generated. diff --git a/README.rst b/README.rst index f083d9d0fb..f8f7ff2519 100644 --- a/README.rst +++ b/README.rst @@ -21,11 +21,9 @@ nickname of "the devguide" by the Python core developers. The official home of this guide is https://devguide.python.org. -Compilation +Render HTML ----------- -For the compilation of the devguide, you need to use a version of Python which -supports the ``venv`` module, because the ``make html`` command will create a -virtual environment and will install the ``Sphinx`` package:: +To render the devguide to HTML under ``_build/html``, run:: make html diff --git a/_static/devguide_overrides.css b/_static/devguide_overrides.css index c34f471332..a8e96a43cf 100644 --- a/_static/devguide_overrides.css +++ b/_static/devguide_overrides.css @@ -7,66 +7,74 @@ } /* Release cycle chart */ -#python-release-cycle .mermaid .active0, -#python-release-cycle .mermaid .active1, -#python-release-cycle .mermaid .active2, -#python-release-cycle .mermaid .active3 { - fill: #00dd00; - stroke: darkgreen; + +.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%; } -#python-release-cycle .mermaid .done0, -#python-release-cycle .mermaid .done1, -#python-release-cycle .mermaid .done2, -#python-release-cycle .mermaid .done3 { - fill: orange; - stroke: darkorange; +.release-cycle-chart .release-cycle-version-label { + fill: var(--color-foreground-primary); } -#python-release-cycle .mermaid .task0, -#python-release-cycle .mermaid .task1, -#python-release-cycle .mermaid .task2, -#python-release-cycle .mermaid .task3 { - fill: #007acc; - stroke: #004455; +.release-cycle-chart .release-cycle-blob { + stroke-width: 1.6px; + /* default colours, overriden below for individual statuses */ + fill: var(--color-background-primary); + stroke: var(--color-foreground-primary); } -#python-release-cycle .mermaid .section0, -#python-release-cycle .mermaid .section2 { - fill: darkgrey; +.release-cycle-chart .release-cycle-blob-label { + /* white looks good on both light & dark */ + fill: white; } -/* Set master colours */ -:root { - --mermaid-section1-3: white; - --mermaid-text-color: black; +.release-cycle-chart .release-cycle-blob-label.release-cycle-blob-security, +.release-cycle-chart .release-cycle-blob-label.release-cycle-blob-bugfix { + /* but use black to improve contrast for lighter backgrounds */ + fill: black; } -@media (prefers-color-scheme: dark) { - body[data-theme=auto] { - --mermaid-section1-3: black; - --mermaid-text-color: #ffffffcc; - } +.release-cycle-chart .release-cycle-blob.release-cycle-blob-end-of-life { + fill: #DD2200; + stroke: #FF8888; } -body[data-theme=dark] { - --mermaid-section1-3: black; - --mermaid-text-color: #ffffffcc; + +.release-cycle-chart .release-cycle-blob.release-cycle-blob-security { + fill: #FFDD44; + stroke: #FF8800; } -#python-release-cycle .mermaid .section1, -#python-release-cycle .mermaid .section3 { - fill: var(--mermaid-section1-3); +.release-cycle-chart .release-cycle-blob.release-cycle-blob-bugfix { + fill: #00DD22; + stroke: #008844; +} + +.release-cycle-chart .release-cycle-blob.release-cycle-blob-prerelease { + fill: teal; + stroke: darkgreen; } -#python-release-cycle .mermaid .grid .tick text, -#python-release-cycle .mermaid .sectionTitle0, -#python-release-cycle .mermaid .sectionTitle1, -#python-release-cycle .mermaid .sectionTitle2, -#python-release-cycle .mermaid .sectionTitle3, -#python-release-cycle .mermaid .taskTextOutside0, -#python-release-cycle .mermaid .taskTextOutside1, -#python-release-cycle .mermaid .taskTextOutside2, -#python-release-cycle .mermaid .taskTextOutside3, -#python-release-cycle .mermaid .titleText { - fill: var(--mermaid-text-color); +.release-cycle-chart .release-cycle-blob.release-cycle-blob-feature { + fill: #2222EE; + stroke: #008888; } diff --git a/_tools/generate_release_cycle.py b/_tools/generate_release_cycle.py index 7e9e69ad83..27b5cc3ec0 100644 --- a/_tools/generate_release_cycle.py +++ b/_tools/generate_release_cycle.py @@ -1,28 +1,13 @@ -"""Read in a JSON and generate two CSVs and a Mermaid file.""" +"""Read in a JSON and generate two CSVs and an SVG file.""" from __future__ import annotations +import argparse import csv import datetime as dt import json +import sys -MERMAID_HEADER = """ -gantt - dateFormat YYYY-MM-DD - title Python release cycle - axisFormat %Y -""".lstrip() - -MERMAID_SECTION = """ - section Python {version} - {release_status} :{mermaid_status} python{version}, {first_release},{eol} -""" # noqa: E501 - -MERMAID_STATUS_MAPPING = { - "feature": "", - "bugfix": "active,", - "security": "done,", - "end-of-life": "crit,", -} +import jinja2 def csv_date(date_str: str, now_str: str) -> str: @@ -33,33 +18,41 @@ def csv_date(date_str: str, now_str: str) -> str: return date_str -def mermaid_date(date_str: str) -> str: - """Format a date for Mermaid.""" +def parse_date(date_str: str) -> dt.date: if len(date_str) == len("yyyy-mm"): - # Mermaid needs a full yyyy-mm-dd, so let's approximate - date_str = f"{date_str}-01" - return date_str + # We need a full yyyy-mm-dd, so let's approximate + return dt.date.fromisoformat(date_str + "-01") + return dt.date.fromisoformat(date_str) class Versions: - """For converting JSON to CSV and Mermaid.""" + """For converting JSON to CSV and SVG.""" def __init__(self) -> None: with open("include/release-cycle.json", encoding="UTF-8") as in_file: self.versions = json.load(in_file) + + # Generate a few additional fields + for key, version in self.versions.items(): + version["key"] = key + version["first_release_date"] = parse_date(version["first_release"]) + version["end_of_life_date"] = parse_date(version["end_of_life"]) self.sorted_versions = sorted( - self.versions.items(), - key=lambda k: [int(i) for i in k[0].split(".")], + self.versions.values(), + key=lambda v: [int(i) for i in v["key"].split(".")], reverse=True, ) def write_csv(self) -> None: """Output CSV files.""" - now_str = str(dt.datetime.utcnow()) + if sys.version_info >= (3, 11): + now_str = str(dt.datetime.now(dt.UTC)) + else: + now_str = str(dt.datetime.utcnow()) versions_by_category = {"branches": {}, "end-of-life": {}} headers = None - for version, details in self.sorted_versions: + for details in self.sorted_versions: row = { "Branch": details["branch"], "Schedule": f":pep:`{details['pep']}`", @@ -70,7 +63,7 @@ def write_csv(self) -> None: } headers = row.keys() cat = "end-of-life" if details["status"] == "end-of-life" else "branches" - versions_by_category[cat][version] = row + versions_by_category[cat][details["key"]] = row for cat, versions in versions_by_category.items(): with open(f"include/{cat}.csv", "w", encoding="UTF-8", newline="") as file: @@ -78,30 +71,85 @@ def write_csv(self) -> None: csv_file.writeheader() csv_file.writerows(versions.values()) - def write_mermaid(self) -> None: - """Output Mermaid file.""" - out = [MERMAID_HEADER] - - for version, details in reversed(self.versions.items()): - v = MERMAID_SECTION.format( - version=version, - first_release=details["first_release"], - eol=mermaid_date(details["end_of_life"]), - release_status=details["status"], - mermaid_status=MERMAID_STATUS_MAPPING[details["status"]], - ) - out.append(v) + def write_svg(self, today: str) -> None: + """Output SVG file.""" + env = jinja2.Environment( + loader=jinja2.FileSystemLoader("_tools/"), + autoescape=True, + lstrip_blocks=True, + trim_blocks=True, + undefined=jinja2.StrictUndefined, + ) + template = env.get_template("release_cycle_template.svg.jinja") + + # Scale. Should be roughly the pixel size of the font. + # All later sizes are multiplied by this, so you can think of all other + # numbers being multiples of the font size, like using `em` units in + # CSS. + # (Ideally we'd actually use `em` units, but SVG viewBox doesn't take + # those.) + SCALE = 18 + + # Width of the drawing and main parts + DIAGRAM_WIDTH = 46 + LEGEND_WIDTH = 7 + RIGHT_MARGIN = 0.5 + + # Height of one line. If you change this you'll need to tweak + # some positioning numbers in the template as well. + LINE_HEIGHT = 1.5 + + first_date = min(ver["first_release_date"] for ver in self.sorted_versions) + last_date = max(ver["end_of_life_date"] for ver in self.sorted_versions) + + def date_to_x(date: dt.date) -> float: + """Convert datetime.date to an SVG X coordinate""" + num_days = (date - first_date).days + total_days = (last_date - first_date).days + ratio = num_days / total_days + x = ratio * (DIAGRAM_WIDTH - LEGEND_WIDTH - RIGHT_MARGIN) + return x + LEGEND_WIDTH + + def year_to_x(year: int) -> float: + """Convert year number to an SVG X coordinate of 1st January""" + return date_to_x(dt.date(year, 1, 1)) + + def format_year(year: int) -> str: + """Format year number for display""" + return f"'{year % 100:02}" with open( - "include/release-cycle.mmd", "w", encoding="UTF-8", newline="\n" + "include/release-cycle.svg", "w", encoding="UTF-8", newline="\n" ) as f: - f.writelines(out) + template.stream( + SCALE=SCALE, + diagram_width=DIAGRAM_WIDTH, + diagram_height=(len(self.sorted_versions) + 2) * LINE_HEIGHT, + years=range(first_date.year, last_date.year + 1), + LINE_HEIGHT=LINE_HEIGHT, + versions=list(reversed(self.sorted_versions)), + today=dt.datetime.strptime(today, "%Y-%m-%d").date(), + year_to_x=year_to_x, + date_to_x=date_to_x, + format_year=format_year, + ).dump(f) def main() -> None: + parser = argparse.ArgumentParser( + description=__doc__, formatter_class=argparse.ArgumentDefaultsHelpFormatter + ) + parser.add_argument( + "--today", + default=str(dt.date.today()), + metavar=" YYYY-MM-DD", + help="Override today for testing", + ) + args = parser.parse_args() + versions = Versions() versions.write_csv() - versions.write_mermaid() + versions.write_svg(args.today) if __name__ == "__main__": diff --git a/_tools/release_cycle_template.svg.jinja b/_tools/release_cycle_template.svg.jinja new file mode 100644 index 0000000000..5d39d307a5 --- /dev/null +++ b/_tools/release_cycle_template.svg.jinja @@ -0,0 +1,91 @@ + + + + {% for version in versions %} + {% set y = loop.index * LINE_HEIGHT %} + + {% if loop.index % 2 %} + + + {% endif %} + {% endfor %} + + {% for year in years %} + + {{ format_year(year) }} + + {% if not loop.last %} + + {% endif %} + {% endfor %} + + {% for version in versions %} + {% set y = loop.index * LINE_HEIGHT %} + + + + Python {{ version.key }} + + + + {% set start_x = date_to_x(version.first_release_date) %} + {% set end_x = date_to_x(version.end_of_life_date) %} + {% set mid_x = (start_x + end_x) / 2 %} + + + {{ version.status }} + + {% endfor %} + + + + diff --git a/advanced-tools/gdb.rst b/advanced-tools/gdb.rst index cf84085d2d..81bdb52015 100644 --- a/advanced-tools/gdb.rst +++ b/advanced-tools/gdb.rst @@ -21,7 +21,7 @@ GDB 7 and later =============== In gdb 7, support for `extending gdb with Python -`_ was +`_ was added. When CPython is built you will notice a ``python-gdb.py`` file in the root directory of your checkout. Read the module docstring for details on how to use the file to enhance gdb for easier debugging of a CPython process. diff --git a/conf.py b/conf.py index 3d30921023..8a05c1d2d7 100644 --- a/conf.py +++ b/conf.py @@ -1,16 +1,18 @@ +import hashlib import os import sys import time +from pathlib import Path # Location of custom extensions. sys.path.insert(0, os.path.abspath(".") + "/_extensions") extensions = [ 'custom_roles', + 'notfound.extension', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx_copybutton', - 'sphinxcontrib.mermaid', 'sphinxext.opengraph', 'sphinxext.rediraffe', ] @@ -32,6 +34,14 @@ '.github', ] +def _asset_hash(path: os.PathLike[str]) -> str: + """Append a `?digest=` to an url based on the file content.""" + full_path = (Path(html_static_path[0]) / path).resolve() + digest = hashlib.sha1(full_path.read_bytes()).hexdigest() + + return f"{path}?digest={digest}" + + html_theme = 'furo' html_theme_options = { "source_repository": "https://github.com/python/devguide", @@ -39,7 +49,7 @@ } html_static_path = ['_static'] html_css_files = [ - 'devguide_overrides.css', + _asset_hash('devguide_overrides.css'), ] html_logo = "_static/python-logo.svg" html_favicon = "_static/favicon.png" @@ -81,7 +91,7 @@ linkcheck_ignore = [ # The voters repo is private and appears as a 404 - 'https://github.com/python/voters/', + 'https://github.com/python/voters', # The python-core team link is private, redirects to login 'https://github.com/orgs/python/teams/python-core', # The Discourse groups are private unless you are logged in @@ -141,6 +151,9 @@ todo_include_todos = True +# sphinx-notfound-page +notfound_urls_prefix = "/" + # sphinxext-opengraph config ogp_site_url = "https://devguide.python.org/" ogp_site_name = "Python Developer's Guide" @@ -153,6 +166,6 @@ # Strip the dollar prompt when copying code # https://sphinx-copybutton.readthedocs.io/en/latest/use.html#strip-and-configure-input-prompts-for-code-cells -copybutton_prompt_text = "$" +copybutton_prompt_text = "$ " # https://sphinx-copybutton.readthedocs.io/en/latest/use.html#honor-line-continuation-characters-when-copying-multline-snippets copybutton_line_continuation_character = "\\" diff --git a/core-developers/committing.rst b/core-developers/committing.rst index be223ba83d..256fda9d1c 100644 --- a/core-developers/committing.rst +++ b/core-developers/committing.rst @@ -74,8 +74,8 @@ to enter the public source tree. Ask yourself the following questions: 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 -------------------------------------- @@ -120,8 +120,8 @@ for what was affected (e.g. ``Misc/NEWS.d/next/Library`` for changes relating to the standard library). The file name itself should be in the format ``.gh-issue-..rst``: -* ```` is today's date joined with a hyphen (``-``) to the current - time, in the ``YYYY-MM-DD-hh-mm-ss`` format (e.g. ``2017-05-27-16-46-23``). +* ```` is today's date joined with a hyphen (``-``) to your current + local time, in the ``YYYY-MM-DD-hh-mm-ss`` format (e.g. ``2017-05-27-16-46-23``). * ```` is the issue number the change is for (e.g. ``12345`` for ``gh-issue-12345``). * ```` is a unique string to guarantee that the file name is @@ -191,7 +191,8 @@ Seeing active branches If you use ``git branch``, then you will see a :ref:`list of branches `. The only branch that receives new features is ``main``, the in-development branch. The other branches receive only -bug fixes or security fixes. +bug fixes or security fixes. In almost all cases the fixes should first +originate on ``main`` and then be ported back to older branches. .. _branch-merge: diff --git a/core-developers/developers.csv b/core-developers/developers.csv index 53edf62b32..2939f8e5d2 100644 --- a/core-developers/developers.csv +++ b/core-developers/developers.csv @@ -1,3 +1,6 @@ +C.A.M. Gerlach,CAM-Gerlach,2023-04-19,, +Barney Gale,barneygale,2023-03-21,, +Carl Meyer,carljm,2023-02-28,, Pradyun Gedam,pradyunsg,2023-01-30,, Shantanu Jain,hauntsaninja,2022-12-19,, Kumar Aditya,kumaraditya303,2022-11-21,, diff --git a/core-developers/experts.rst b/core-developers/experts.rst index f48eaf7ea7..b8b962f974 100644 --- a/core-developers/experts.rst +++ b/core-developers/experts.rst @@ -61,15 +61,12 @@ aifc bitdancer argparse array ast benjaminp, pablogsal, isidentical -asynchat josiahcarlson, giampaolo*, stutzbach^ -asyncio 1st1, asvetlov, gvanrossum, graingert, kumaraditya303 -asyncore josiahcarlson, giampaolo*, stutzbach^ +asyncio 1st1, asvetlov, gvanrossum, graingert, kumaraditya303, willingc atexit audioop serhiy-storchaka base64 bdb binascii -binhex bisect rhettinger* builtins bz2 @@ -85,7 +82,7 @@ codeop collections rhettinger* collections.abc rhettinger*, stutzbach^ colorsys -compileall +compileall carljm concurrent.futures pitrou, brianquinlan, gpshead* configparser ambv* contextlib ncoghlan, 1st1 @@ -97,7 +94,7 @@ crypt jafo^* csv smontanaro (inactive) ctypes theller (inactive), abalkin, amauryfa, meadori curses Yhg1s -dataclasses ericvsmith* +dataclasses ericvsmith*, carljm datetime abalkin, pganssle dbm decimal facundobatista, rhettinger, mdickinson @@ -115,7 +112,6 @@ fcntl Yhg1s filecmp fileinput fnmatch -formatter fractions mdickinson ftplib giampaolo* functools rhettinger* @@ -135,7 +131,6 @@ idlelib kbkaiser (inactive), terryjreedy*, serwy (inactive), taleinat imaplib imghdr -imp importlib brettcannon inspect 1st1 io benjaminp, stutzbach^ @@ -168,7 +163,7 @@ optparse mitsuhiko os os.path serhiy-storchaka ossaudiodev -parser benjaminp, pablogsal +parser pablogsal pathlib barneygale* pdb pickle avassalotti @@ -184,7 +179,7 @@ profile pstats pty Yhg1s* pwd -py_compile +py_compile carljm pyclbr isidentical pydoc queue rhettinger* @@ -205,7 +200,6 @@ shlex shutil tarekziade, giampaolo signal gpshead site -smtpd giampaolo smtplib sndhdr socket gpshead @@ -220,7 +214,6 @@ stringprep struct mdickinson, meadori subprocess astrand^ (inactive), giampaolo, gpshead* sunau -symbol symtable benjaminp sys sysconfig FFY00 @@ -245,7 +238,7 @@ tracemalloc vstinner tty Yhg1s* turtle gregorlingl^, willingc types 1st1 -typing gvanrossum, Fidget-Spinner, JelleZijlstra*, AlexWaygood* +typing gvanrossum, Fidget-Spinner, JelleZijlstra*, AlexWaygood*, carljm unicodedata malemburg, ezio-melotti unittest voidspace*, ezio-melotti, rbtcollins, gpshead unittest.mock voidspace* @@ -297,6 +290,7 @@ Platforms Platform Maintainers =================== =========== AIX David.Edelsohn^ +Android Cygwin jlt63^, stutzbach^ FreeBSD HP-UX @@ -318,12 +312,12 @@ Interest Area Maintainers ================== ========================================================== algorithms rhettinger* argument clinic larryhastings -ast/compiler benjaminp, 1st1, pablogsal, markshannon, isidentical, brandtbucher +ast/compiler benjaminp, 1st1, pablogsal, markshannon, isidentical, brandtbucher, carljm autoconf/makefiles Yhg1s* bsd issue tracker ezio-melotti buildbots zware, pablogsal -bytecode benjaminp, 1st1, markshannon, brandtbucher +bytecode benjaminp, 1st1, markshannon, brandtbucher, carljm context managers ncoghlan core workflow Mariatta, ezio-melotti, hugovk coverity scan tiran, Yhg1s @@ -350,12 +344,13 @@ object model benjaminp, Yhg1s packaging tarekziade, malemburg, alexis^, merwok, dstufft, pfmoore pattern matching brandtbucher* peg parser gvanrossum, pablogsal, lysnikolaou -performance vstinner, serhiy-storchaka, 1st1, rhettinger, markshannon, brandtbucher +performance vstinner, serhiy-storchaka, 1st1, rhettinger, markshannon, brandtbucher, carljm pip ncoghlan, dstufft, pfmoore, Marcus.Smith^, pradyunsg py3 transition benjaminp release management tarekziade, malemburg, benjaminp, warsaw, gvanrossum, anthonybaxter^, merwok, ned-deily, birkenfeld, JulienPalard +runtime lifecycle ericsnowcurrently, kumaraditya303, zooba str.format ericvsmith* subinterpreters ericsnowcurrently, kumaraditya303 testing voidspace, ezio-melotti diff --git a/core-developers/motivations.rst b/core-developers/motivations.rst index 1c813730db..625c763d97 100644 --- a/core-developers/motivations.rst +++ b/core-developers/motivations.rst @@ -259,15 +259,15 @@ participating in the CPython core development process: .. topic:: Carol Willing (United States) - * Noteable: ``__ (Technical Evangelist) + * Noteable: ``__ (VP Engineering) * Personal site: `Willing Consulting `_ * `Extended bio `__ - * Project Jupyter (Steering Council, Core Team for JupyterHub/Binder) + * Project Jupyter (Software Council, Core Team for JupyterHub/Binder) * Python Software Foundation (Fellow) Carol is focused on Python's usage in education and scientific research. - She is interested in organizational development, operational workflows, - and sustainability of open source projects. + She is interested in distributed computing, organizational development, + operational workflows, and sustainability of open source projects. .. _goals-of-the-motivations-page: diff --git a/developer-workflow/c-api.rst b/developer-workflow/c-api.rst index 3e6199f8eb..103abe7b0a 100644 --- a/developer-workflow/c-api.rst +++ b/developer-workflow/c-api.rst @@ -4,18 +4,20 @@ Changing Python's C API ======================= -The C API is divided into three sections: +The C API is divided into these tiers: 1. The internal, private API, available with ``Py_BUILD_CORE`` defined. Ideally declared in ``Include/internal/``. Any API named with a leading underscore is also considered private. -2. The public C API, available when ``Python.h`` is included normally. +2. The Unstable C API, identified by the ``PyUnstable_`` name prefix. + Ideally declared in :cpy-file:`Include/cpython/` along with the general public API. +3. The “general” public C API, available when :cpy-file:`Include/Python.h` is included normally. Ideally declared in ``Include/cpython/``. -3. The Limited API, available with ``Py_LIMITED_API`` defined. +4. The Limited C API, available with :c:macro:`Py_LIMITED_API` defined. Ideally declared directly under ``Include/``. -Each section has higher stability & maintenance requirements, and you will -need to think about more issues when you add or change definitions in it. +Each tier has different stability and maintenance requirements to consider +when you add or change definitions in it. The compatibility guarantees for public C API are explained in the user documentation, ``Doc/c-api/stable.rst`` (:ref:`python:stable`). @@ -29,6 +31,11 @@ for building CPython itself, as indicated by a macro like ``Py_BUILD_CORE``. 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 `_ +or an issue so we can try to find a supported way to serve them. + With PyAPI_FUNC or PyAPI_DATA ----------------------------- @@ -36,6 +43,7 @@ With PyAPI_FUNC or PyAPI_DATA Functions or structures in ``Include/internal/`` defined with ``PyAPI_FUNC`` or ``PyAPI_DATA`` are internal functions which are exposed only for specific use cases like debuggers and profilers. +Ideally, these should be migrated to the :ref:`unstable-capi`. With the extern keyword @@ -53,14 +61,18 @@ Private names -------------- Any API named with a leading underscore is also considered internal. -There are two main use cases for using such names rather than putting the -definition in ``Include/internal/`` (or directly in a ``.c`` file): +There is currently only one main use case for using such names rather than +putting the definition in :cpy-file:`Include/internal/` (or directly in a ``.c`` file): + +* Internal helpers for other public APIs, which users should not call directly. + +Note that historically, underscores were used for APIs that are better served by +the :ref:`unstable-capi`: + +* “provisional” APIs, included in a Python release to test real-world + usage of new APIs; +* APIs for very specialized uses like JIT compilers. -* Internal helpers for other public API; users should not use these directly; -* “Provisional” API, included in a Python release to test real-world usage - of new API. Such names should be renamed when stabilized; preferably with - a macro aliasing the old name to the new one. - See :pep:`"Finalizing the API" in PEP 590 <590#finalizing-the-api>` for an example. Internal API Tests ------------------ @@ -81,7 +93,10 @@ CPython's public C API is available when ``Python.h`` is included normally It should be defined in ``Include/cpython/`` (unless part of the Limited API, see below). -Guidelines for expanding/changing the public API: +.. _public-api-guidelines: + +Guidelines for expanding/changing the public API +------------------------------------------------ - Make sure the new API follows reference counting conventions. (Following them makes the API easier to reason about, and easier use @@ -94,6 +109,24 @@ Guidelines for expanding/changing the public API: - Make sure the ownership rules and lifetimes of all applicable struct fields, arguments and return values are well defined. +- Functions returning ``PyObject *`` must return a valid pointer on success, + and ``NULL`` with an exception raised on error. + Most other API must return ``-1`` with an exception raised on error, + and ``0`` on success. + +- APIs with lesser and greater results must return ``0`` for the lesser result, + and ``1`` for the greater result. + Consider a lookup function with a three-way return: + + - ``return -1``: internal error or API misuse; exception raised + - ``return 0``: lookup succeeded; no item was found + - ``return 1``: lookup succeeded; item was found + +Please start a public discussion if these guidelines won't work for your API. + +.. note:: + + By *return value*, we mean the value returned by the *C return statement*. C API Tests ----------- @@ -134,6 +167,103 @@ When moving existing tests, feel free to replace ``TestError`` with ``PyExc_AssertionError`` unless actually testing custom exceptions. +.. _unstable-capi: + +Unstable C API +============== + +The unstable C API tier is meant for extensions that need tight integration +with the interpreter, like debuggers and JIT compilers. +Users of this tier may need to change their code with every minor release. + +In many ways, this tier is like the general C API: + +- it's available when ``Python.h`` is included normally, +- it should be defined in :cpy-file:`Include/cpython/`, +- it requires tests, so we don't break it unintentionally +- it requires docs, so both we and the users, + can agree on the expected behavior, +- it is tested and documented in the same way. + +The differences are: + +- Names of functions structs, macros, etc. start with the ``PyUnstable_`` + prefix. This defines what's in the unstable tier. +- The unstable API can change in minor versions, without any deprecation + period. +- A stability note appears in the docs. + This happens automatically, based on the name + (via :cpy-file:`Doc/tools/extensions/c_annotations.py`). + +Despite being “unstable”, there are rules to make sure third-party code can +use this API reliably: + +* Changes and removals can be done in minor releases + (: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 `_ + 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 + renamed. +* When moving an API into or out of the Unstable tier, the old name + should continue to be available (but deprecated) until an incompatible + change is made. In other words, while we're allowed to break calling code, + we shouldn't break it *unnecessarily*. + + +Moving an API from the public tier to Unstable +---------------------------------------------- + +* Expose the API under its new name, with the ``PyUnstable_`` prefix. +* Make the old name an alias (e.g. a ``static inline`` function calling the + new function). +* Deprecate the old name, typically using :c:macro:`Py_DEPRECATED`. +* Announce the change in the "What's New". + +The old name should continue to be available until an incompatible change is +made. Per Python’s backwards compatibility policy (:pep:`387`), +this deprecation needs to last at least two releases +(modulo Steering Council exceptions). + +The rules are relaxed for APIs that were introduced in Python versions +before 3.12, when the official Unstable tier was added. +You can make an incompatible change (and remove the old name) +as if the function was already part of the Unstable tier +for APIs introduced before Python 3.12 that are either: + +* Documented to be less stable than default. +* Named with a leading underscore. + +Moving an API from the private tier to unstable +----------------------------------------------- + +* Expose the API under its new name, with the ``PyUnstable_`` prefix. +* If the old name is documented, or widely used externally, + make it an alias and deprecate it (typically with :c:macro:`Py_DEPRECATED`). + It should continue to be available until an incompatible change is made, + as if it was previously public. + + This applies even to underscored names. Python wasn't always strict with + the leading underscore. +* Announce the change in What's New. + +Moving an API from unstable to public +------------------------------------- + +* Expose the API under its new name, without the ``PyUnstable_`` prefix. +* Make the old ``PyUnstable_*`` name be an alias (e.g. a ``static inline`` + function calling the new function). +* Announce the change in What's New. + +The old name should remain available until the +new public name is deprecated or removed. +There's no need to deprecate the old name (it was unstable to begin with), +but there's also no need to break working code just because some function +is now ready for a wider audience. + + Limited API =========== @@ -183,10 +313,13 @@ It is possible to remove items marked as part of the Stable ABI, but only if there was no way to use them in any past version of the Limited API. +.. _limited-api-guidelines: + Guidelines for adding to the Limited API ---------------------------------------- - Guidelines for the general :ref:`public-capi` apply. + See :ref:`public-api-guidelines`. - New Limited API should only be defined if ``Py_LIMITED_API`` is set to the version the API was added in or higher. @@ -266,14 +399,14 @@ Adding a new definition to the Limited API .. code-block:: shell - ./python ./Tools/scripts/stable_abi.py --generate-all ./Misc/stable_abi.toml + ./python ./Tools/build/stable_abi.py --generate-all ./Misc/stable_abi.toml - Build Python and check the using ``make check-limited-abi``. On platforms without ``make``, run this command directly: .. code-block:: shell - ./python ./Tools/scripts/stable_abi.py --all ./Misc/stable_abi.toml + ./python ./Tools/build/stable_abi.py --all ./Misc/stable_abi.toml - Add tests -- see below. diff --git a/developer-workflow/communication-channels.rst b/developer-workflow/communication-channels.rst index 239855bb16..9935474263 100644 --- a/developer-workflow/communication-channels.rst +++ b/developer-workflow/communication-channels.rst @@ -250,13 +250,27 @@ order to make open source pleasant for everyone involved. Additional Repositories ======================= -`Python Core Workflow`_ hosts the codebase for tools such as `cherry_picker`_ -and `blurb`_. +`Python Core Workflow`_ hosts the codebase for tools such as `blurb`_. + +Other core workflow tools are: + +* `cherry_picker`_ (`PyPI`_) +* `bedevere`_ +* `blurb_it`_ +* `miss-islington`_ +* `cla-bot`_ +* `cpython-emailer-webhook`_ Python `Performance Benchmark`_ project is intended to be an authoritative source of benchmarks for all Python implementations. .. _Python Core Workflow: https://github.com/python/core-workflow -.. _cherry_picker: https://pypi.org/project/cherry_picker/ .. _blurb: https://pypi.org/project/blurb +.. _cherry_picker: https://github.com/python/cherry-picker +.. _PyPI: https://pypi.org/project/cherry_picker/ +.. _bedevere: https://github.com/python/bedevere +.. _blurb_it: https://github.com/python/blurb_it +.. _miss-islington: https://github.com/python/miss-islington +.. _cla-bot: https://github.com/ambv/cla-bot +.. _cpython-emailer-webhook: https://github.com/berkerpeksag/cpython-emailer-webhook .. _Performance Benchmark: https://github.com/python/pyperformance diff --git a/documentation/help-documenting.rst b/documentation/help-documenting.rst index 0da669b35c..86652ffd3b 100644 --- a/documentation/help-documenting.rst +++ b/documentation/help-documenting.rst @@ -36,9 +36,9 @@ and :ref:`maintenance ` branches at https://docs.python.org/dev/. 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 `docs@python.org `_ -mailing list and the `Documentation category on the Python Discourse -`_, +to the `Documentation category on the Python Discourse +`_ and the +`docs@python.org `_ mailing list where user issues are raised and documentation toolchain, projects, and standards are discussed. diff --git a/documentation/markup.rst b/documentation/markup.rst index 45724a0fb2..8859ab8d00 100644 --- a/documentation/markup.rst +++ b/documentation/markup.rst @@ -30,6 +30,8 @@ external links ```Link text `_`` :ref:`hyperl roles w/ custom text ``:role:`custom text ``` :ref:`roles` roles w/ only last part ``:role:`~hidden.hidden.visible``` :ref:`roles` roles w/o link ``:role:`!target``` :ref:`roles` +issues ``:gh:`ID```, ``:issue:`ID``` :ref:`roles` +CPython source ``:source:`PATH``` :ref:`roles` comments ``.. a comment`` :ref:`comments` ======================= =========================================== ==================== @@ -81,7 +83,7 @@ Be aware of some restrictions of this markup: These restrictions may be lifted in future versions of the docutils. -reST also allows for custom "interpreted text roles"', which signify that the +reST also allows for custom "interpreted text roles", which signify that the enclosed text should be interpreted in a specific way. Sphinx uses this to provide semantic markup and cross-referencing of identifiers, as described in the appropriate section. The general syntax is ``:rolename:`content```. @@ -682,6 +684,12 @@ where simpler markup should be used: * ``*arg*`` (rendered as *arg*) for function and method arguments. * ````True````/````False````/````None```` for ``True``/``False``/``None``. +In addition, the CPython documentation defines a few custom roles: + +* ``:gh:`ID```: creates a link to a GitHub issue. +* ``:issue:`ID```: creates a link to a bugs.python.com issue. +* ``:source:`PATH```: creates a link to a source file on GitHub. + There are some additional facilities that make cross-referencing roles more versatile: diff --git a/documentation/start-documenting.rst b/documentation/start-documenting.rst index 175c73c0a5..592059bf7f 100644 --- a/documentation/start-documenting.rst +++ b/documentation/start-documenting.rst @@ -64,79 +64,109 @@ Building the documentation .. highlight:: bash -The toolset used to build the docs is written in Python and is called Sphinx_. -Sphinx is maintained separately and is not included in this tree. Also needed -are blurb_, a tool to create :file:`Misc/NEWS` on demand; and -python-docs-theme_, the Sphinx theme for the Python documentation. +To build the documentation, follow the steps in one of the sections below. +You can view the documentation after building the HTML +by opening the file :file:`Doc/build/html/index.html` in a web browser. -To build the documentation, follow the instructions from one of the sections -below. You can view the documentation after building the HTML by pointing -a browser at the file :file:`Doc/build/html/index.html`. +.. note:: -You are expected to have installed the latest stable version of -Sphinx_ and blurb_ on your system or in a virtualenv_ (which can be -created using ``make venv``), so that the Makefile can find the -``sphinx-build`` command. You can also specify the location of -``sphinx-build`` with the ``SPHINXBUILD`` :command:`make` variable. + The following instructions all assume your current working dir is + the ``Doc`` subdirectory in your :ref:`CPython repository clone `. + Make sure to switch to it with ``cd Doc`` if necessary. -.. _building-using-make: +.. _doc-create-venv: + +Create a virtual environment +---------------------------- -Using make / make.bat ---------------------- +.. _doc-create-venv-unix: -**On Unix**, run the following from the root of your :ref:`repository clone -` to build the output as HTML:: +**On Unix platforms** that support :program:`make` +(including Linux, macOS and BSD), +you can create a new :mod:`venv` with the required dependencies using:: - cd Doc make venv - make html -or alternatively ``make -C Doc/ venv html``. ``htmlview`` can be used -instead of ``html`` to conveniently open the docs in a browser once the -build completes. +Building the docs with :program:`make` will automatically use this environment +without you having to activate it. + +.. _doc-create-venv-windows: + +**On Windows**, or if not using :program:`make`, +`create a new virtual environment `__ manually. +Always be sure to `activate this environment `__ +before building the documentation. + + +.. _building-using-make: +.. _using-make-make-bat: +.. _doc-build-make: + +Build using make / make.bat +--------------------------- -You can also use ``make help`` to see a list of targets supported by -:command:`make`. Note that ``make check`` is automatically run when -you submit a :ref:`pull request `, so you should make -sure that it runs without errors. +A Unix ``Makefile`` is provided, :cpy-file:`Doc/Makefile`, +along with a :cpy-file:`Doc/make.bat` batch file for Windows +that attempts to emulate it as closely as practical. -**On Windows**, the :cpy-file:`Doc/make.bat` batchfile tries to emulate -:command:`make` as closely as possible, but the venv target is not implemented, -so you will probably want to make sure you are working in a virtual environment -before proceeding, otherwise all dependencies will be automatically installed -on your system. +.. important:: -When ready, run the following from the root of your :ref:`repository clone -` to build the output as HTML:: + The Windows ``make.bat`` batch file lacks a ``make venv`` target. + Instead, it automatically installs any missing dependencies + into the currently activated environment (or the base Python, if none). + Make sure the environment you :ref:`created above ` + is `activated `__ before running ``make.bat``. + +To build the docs as HTML, run:: - cd Doc make html -You can also use ``make help`` to see a list of targets supported by -:cpy-file:`Doc/make.bat`. +.. tip:: Substitute ``htmlview`` for ``html`` to open the docs in a web browser + once the build completes. + +To check the docs for common errors with `Sphinx Lint`_ +(which is run on all :ref:`pull requests `), use:: + + make check + +To list other supported :program:`make` targets, run:: + + make help + +See :cpy-file:`Doc/README.rst` for more information. + + +.. _using-sphinx-build: +.. _doc-build-sphinx: + +Build using Sphinx directly +--------------------------- + +Advanced users may want to invoke Sphinx directly, +to pass specialized options or to handle specific use cases. -See also :cpy-file:`Doc/README.rst` for more information. +Make sure the environment you :ref:`created above ` +is `activated `__. +Then, install the documentation requirements, :cpy-file:`Doc/requirements.txt`. +Using pip:: -Using sphinx-build ------------------- + python -m pip install --upgrade -r requirements.txt -Sometimes we directly want to execute the sphinx-build tool instead of through -``make`` (although the latter is still the preferred way). In this case, you can -use the following command line from the ``Doc`` directory (make sure to install -Sphinx_, blurb_ and python-docs-theme_ packages from PyPI):: +Finally, directly invoke Sphinx with:: - sphinx-build -b . build/ + python -m sphinx -b html . build/html -where ```` is one of html, text, latex, or htmlhelp (for explanations -see the make targets above). +To use a different `Sphinx builder`_, +replace ``html`` above with the desired builder ``name``. .. _docutils: https://docutils.sourceforge.io/ -.. _python-docs-theme: https://pypi.org/project/python-docs-theme/ .. _Sphinx: https://www.sphinx-doc.org/ -.. _virtualenv: https://virtualenv.pypa.io/ -.. _blurb: https://pypi.org/project/blurb/ +.. _Sphinx builder: https://www.sphinx-doc.org/en/master/usage/builders/index.html +.. _Sphinx Lint: https://github.com/sphinx-contrib/sphinx-lint +.. _venv-activate: https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/#activating-a-virtual-environment +.. _venv-create: https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment Style Guide diff --git a/documentation/translating.rst b/documentation/translating.rst index 19a8d72ecf..005464d591 100644 --- a/documentation/translating.rst +++ b/documentation/translating.rst @@ -36,7 +36,11 @@ in production; others are works in progress. | Italian (it) | | `mail `_ | +-----------------+-------------------------------+----------------------------+ | Japanese (ja) | `Kinebuchi Tomohiko | `GitHub `_ | -| | (@cocoatomo) `_| `Doc `_ | +| | (@cocoatomo) | `Doc `_ | +| | `_, | | +| | `Atsuo Ishimoto | | +| | (@atsuoishimoto) | | +| | `_ | | +-----------------+-------------------------------+----------------------------+ | Korean (ko) | | `GitHub `_ | | | | `Doc `_ | @@ -74,7 +78,7 @@ in production; others are works in progress. | (zh-tw) | Josix Wang | | +-----------------+-------------------------------+----------------------------+ | Turkish (tr) | `Ege Akman (@egeakman) | `GitHub `_ | -| | `_ | `GH-Pages `_ | +| | `_ | `RTD `_ | | | | `Doc `_ | +-----------------+-------------------------------+----------------------------+ | Ukrainian (uk) | `Dmytro Kazanzhy (@kazanzhy) | `GitHub `_ | @@ -83,6 +87,7 @@ in production; others are works in progress. .. _article_pt_br: https://rgth.co/blog/python-ptbr-cenario-atual/ .. _gh_cocoatomo: https://github.com/cocoatomo +.. _gh_atsuoishimoto: https://github.com/atsuoishimoto .. _gh_gbtami: https://github.com/gbtami .. _gh_kushal: https://github.com/Kushal997-das .. _gh_maciek: https://github.com/m-aciek @@ -102,7 +107,6 @@ in production; others are works in progress. .. _doc_tr: https://docs.python.org/tr/ .. _doc_zh_cn: https://docs.python.org/zh-cn/ .. _doc_zh_tw: https://docs.python.org/zh-tw/ -.. _gh_pages_tr: https://python.github.io/python-docs-tr/ .. _github_ar: https://github.com/Abdur-rahmaanJ/python-docs-ar .. _github_bn_in: https://github.com/python/python-docs-bn-in .. _github_es: https://github.com/python/python-docs-es @@ -125,6 +129,7 @@ in production; others are works in progress. .. _mail_lt: https://mail.python.org/pipermail/doc-sig/2019-July/004138.html .. _mail_pl: https://mail.python.org/pipermail/doc-sig/2019-April/004106.html .. _mail_ru: https://mail.python.org/pipermail/doc-sig/2019-May/004131.html +.. _rtd_tr: https://python-docs-tr.readthedocs.io/ .. _tx_pl: https://explore.transifex.com/python-doc/python-newest/ .. _tx_uk: https://explore.transifex.com/python-doc/python-newest/ .. _tx_zh_cn: https://explore.transifex.com/python-doc/python-newest/ diff --git a/getting-started/git-boot-camp.rst b/getting-started/git-boot-camp.rst index e29dc1e059..082232cee7 100644 --- a/getting-started/git-boot-camp.rst +++ b/getting-started/git-boot-camp.rst @@ -185,7 +185,7 @@ created before the rename, you should visit the GitHub page for your fork to rename the branch there. You only have to do this once. GitHub should provide you with a dialog for this. If it doesn't (or the dialog was already dismissed), you can rename the branch in your fork manually `by following -these GitHub instructions `__ +these GitHub instructions `__. After renaming the branch in your fork, you need to update any local clones as well. This only has to be done once per clone:: @@ -350,7 +350,7 @@ Solution:: git push origin main .. note:: For the above commands to work, please follow the instructions found - in the :ref:`checkout` section + in the :ref:`checkout` section. Another scenario: @@ -461,37 +461,68 @@ Accepting and Merging a Pull Request ------------------------------------ Pull requests can be accepted and merged by a Python Core Developer. +You can read more about what to look for before accepting a change +:ref:`here `. -1. At the bottom of the pull request page, click the ``Squash and merge`` - button. +All pull requests have required checks that need to pass before a change +can be merged. At any point, a core developer can schedule an automatic merge +of the change by +clicking the gray ``Enable auto-merge (squash)`` button. You will find +it at the bottom of the pull request page. The auto-merge will only +happen if all the required checks pass, but the PR does not need to have been +approved for a successful auto-merge to take place. -2. Replace the reference to GitHub pull request ``#NNNN`` with ``GH-NNNN``. - If the title is too long, the pull request number can be added to the - message body. +If all required checks are already finished on a PR you're reviewing, +in place of the gray ``Enable auto-merge`` button you will find a green +``Squash and merge`` button. -3. Adjust and clean up the commit message. +In either case, adjust and clean up the commit message. - Example of good commit message:: +Here's an example of a **good** commit message:: - gh-12345: Improve the spam module (GH-777) + gh-12345: Improve the spam module (GH-777) - * Add method A to the spam module - * Update the documentation of the spam module + * Add method A to the spam module + * Update the documentation of the spam module - Example of bad commit message:: +Here's an example of a **bad** commit message:: - gh-12345: Improve the spam module (#777) + gh-12345: Improve the spam module (#777) - * Improve the spam module - * merge from main - * adjust code based on review comment - * rebased + * Improve the spam module + * merge from main + * adjust code based on review comment + * rebased - .. note:: - `How to Write a Git Commit Message `_ - is a nice article describing how to write a good commit message. +The bad example contains bullet points that are a direct effect of the +PR life cycle, while being irrelevant to the final change. -4. Press the ``Confirm squash and merge`` button. +.. note:: + `How to Write a Git Commit Message `_ + is a nice article describing how to write a good commit message. + +Finally, press the ``Confirm squash and merge`` button. + +Cancelling an Automatic Merge +----------------------------- + +If you notice a problem with a pull request that was accepted and where +auto-merge was enabled, you can still cancel the workflow before GitHub +automatically merges the change. + +Press the gray "Disable auto-merge" button on the bottom of the +pull request page to disable automatic merging entirely. This is the +recommended approach. + +To pause automatic merging, apply the "DO-NOT-MERGE" label to the PR or +submit a review requesting changes. The latter will put an "awaiting +changes" label on the PR, which pauses the auto-merge similarly to +"DO-NOT-MERGE". After the author submits a fix and re-requests review, you can +resume the auto-merge process either by submitting an approving review or by +dismissing your previous review that requested changes. + +Note that pushing new changes after the auto-merge flow was enabled +does **NOT** stop it. Backporting Merged Changes -------------------------- diff --git a/getting-started/pull-request-lifecycle.rst b/getting-started/pull-request-lifecycle.rst index de361d2a2f..5c81d0a99c 100644 --- a/getting-started/pull-request-lifecycle.rst +++ b/getting-started/pull-request-lifecycle.rst @@ -402,6 +402,9 @@ on how to properly add the co-author info. See also :ref:`Applying a Patch to Git `. + +.. _reviewing-prs: + Reviewing ========= @@ -413,7 +416,7 @@ request (we cannot force anyone to review pull requests and no one is employed to look at pull requests). If your pull request has not received any notice from reviewers (i.e., no comment made) after one month, first "ping" the issue on the `issue tracker`_ to remind the -nosy list that the pull request needs a review. +subscribers that the pull request needs a review. If you don't get a response within a week after pinging the issue, you can post on the `Core Development Discourse category`_ to ask for someone to review your pull request. @@ -427,7 +430,6 @@ thus iterate until a satisfactory solution has emerged. .. _how-to-review-a-pull-request: - How to Review a Pull Request ---------------------------- diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index 60d0b93d5b..75db82ba20 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -183,20 +183,17 @@ passed into the ``-j`` flag to match the number of cores you have (or if your version of Make supports it, you can use ``-j`` without a number and Make will not limit the number of steps that can run simultaneously.). -At the end of the build you should see a success message, possibly followed +At the end of the build you should see a success message, followed by a list of extension modules that haven't been built because their dependencies were missing: .. code-block:: none - Python build finished successfully! The necessary bits to build these optional modules were not found: - _bz2 _dbm _gdbm - _lzma _sqlite3 _ssl - _tkinter _uuid readline - zlib - To find the necessary bits, look in setup.py in detect_modules() - for the module's name. + _gdbm + To find the necessary bits, look in configure.ac and config.log. + + Checked 106 modules (31 built-in, 74 shared, 0 n/a on macosx-13.4-arm64, 0 disabled, 1 missing, 0 failed on import) If the build failed and you are using a C89 or C99-compliant compiler, please open a bug report on the `issue tracker`_. @@ -314,7 +311,7 @@ You can run the build of Python you've compiled with: See the `PCBuild readme`_ for more details on what other software is necessary and how to build. -.. _Victor Stinner's guide: https://cpython-core-tutorial.readthedocs.io/en/latest/build_cpython_windows.html +.. _Victor Stinner's guide: https://web.archive.org/web/20220907075854/https://cpython-core-tutorial.readthedocs.io/en/latest/build_cpython_windows.html .. _Visual Studio: https://visualstudio.microsoft.com/ .. _PCBuild readme: https://github.com/python/cpython/blob/main/PCbuild/readme.txt .. _Git for Windows download from the official Git website: https://git-scm.com/download/win @@ -413,52 +410,49 @@ Apple no longer provides header files for the deprecated system version of OpenSSL which means that you will not be able to build the ``_ssl`` extension. One solution is to install these libraries from a third-party package manager, like Homebrew_ or MacPorts_, and then add the appropriate paths -for the header and library files to your ``configure`` command. For example, +for the header and library files to your ``configure`` command. -with **Homebrew**:: +For example, with **Homebrew**, install the dependencies:: - $ brew install pkg-config openssl@1.1 xz gdbm tcl-tk + $ brew install pkg-config openssl@3.0 xz gdbm tcl-tk -For Python 3.10 and newer:: +Then, for Python 3.11 and newer, run ``configure``:: - $ CFLAGS="-I$(brew --prefix gdbm)/include -I$(brew --prefix xz)/include" \ - LDFLAGS="-L$(brew --prefix gdbm)/lib -I$(brew --prefix xz)/lib" \ - PKG_CONFIG_PATH="$(brew --prefix tcl-tk)/lib/pkgconfig" \ + $ GDBM_CFLAGS="-I$(brew --prefix gdbm)/include" \ + GDBM_LIBS="-L$(brew --prefix gdbm)/lib -lgdbm" \ ./configure --with-pydebug \ - --with-openssl=$(brew --prefix openssl) - + --with-openssl="$(brew --prefix openssl@3.0)" -For Python versions 3.9 through 3.7:: +Or, for Python 3.8 through 3.10:: - $ CFLAGS="-I$(brew --prefix gdbm)/include -I$(brew --prefix xz)/include" \ + $ CPPFLAGS="-I$(brew --prefix gdbm)/include -I$(brew --prefix xz)/include" \ LDFLAGS="-L$(brew --prefix gdbm)/lib -L$(brew --prefix xz)/lib" \ - PKG_CONFIG_PATH="$(brew --prefix tcl-tk)/lib/pkgconfig" \ ./configure --with-pydebug \ - --with-openssl=$(brew --prefix openssl@1.1) \ - --with-tcltk-libs="$(pkg-config --libs tcl tk)" \ - --with-tcltk-includes="$(pkg-config --cflags tcl tk)" + --with-openssl="$(brew --prefix openssl@3.0)" \ + --with-tcltk-libs="$(pkg-config --libs tcl tk)" \ + --with-tcltk-includes="$(pkg-config --cflags tcl tk)" -and ``make``:: +And finally, run ``make``:: $ make -s -j2 -or **MacPorts**:: +Alternatively, with **MacPorts**:: - $ sudo port install pkgconfig openssl xz gdbm + $ sudo port install pkgconfig openssl xz gdbm tcl tk +quartz -and ``configure``:: +Then, for Python 3.11 and newer, run ``configure``:: - $ CPPFLAGS="-I/opt/local/include" \ - LDFLAGS="-L/opt/local/lib" \ + $ GDBM_CFLAGS="-I$(dirname $(dirname $(which port)))/include" \ + GDBM_LIBS="-L$(dirname $(dirname $(which port)))/lib -lgdbm" \ ./configure --with-pydebug -and ``make``:: +And finally, run ``make``:: $ make -s -j2 There will sometimes be optional modules added for a new release which won't yet be identified in the OS-level build dependencies. In those cases, -just ask for assistance on the core-mentorship list. +just ask for assistance in the *Core Development* category on :ref:`help-discourse`. Explaining how to build optional dependencies on a Unix-based system without root access is beyond the scope of this guide. @@ -483,31 +477,49 @@ Regenerate ``configure`` 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 -``configure`` script to test for availability of the functionality. +: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 `_. + +After editing :file:`configure.ac`, run ``make regen-configure`` to generate +:file:`configure`, :cpy-file:`pyconfig.h.in`, and :cpy-file:`aclocal.m4`. +When submitting a pull request with changes made to :file:`configure.ac`, +make sure you also commit the changes in the generated files. + +The recommended and by far the easiest way to regenerate :file:`configure` is:: + + $ make regen-configure -Python's ``configure`` script is generated from ``configure.ac`` using Autoconf. -Instead of editing ``configure``, edit ``configure.ac`` and then run -``autoreconf`` to regenerate ``configure`` and a number of other files (such as -``pyconfig.h``). +If you are regenerating :file:`configure` in a clean repo, +run one of the following containers instead:: -When submitting a patch with changes made to ``configure.ac``, you should also -include the generated files. + $ podman run --rm --pull=always -v $(pwd):/src:Z quay.io/tiran/cpython_autoconf:271 -Note that running ``autoreconf`` is not the same as running ``autoconf``. For -example, ``autoconf`` by itself will not regenerate ``pyconfig.h.in``. -``autoreconf`` runs ``autoconf`` and a number of other tools repeatedly as is -appropriate. +:: -Python's ``configure.ac`` script typically requires a specific version of -Autoconf. At the moment, this reads: ``AC_PREREQ(2.69)``. It also requires -to have the ``autoconf-archive`` and ``pkg-config`` utilities installed in -the system and the ``pkg.m4`` macro file located in the appropriate ``alocal`` -location. You can easily check if this is correctly configured by running:: + $ docker run --rm --pull=always -v $(pwd):/src quay.io/tiran/cpython_autoconf:271 + +Notice that the images are tagged with ``271``. +Python's :file:`configure.ac` script requires a specific version of +GNU Autoconf. +For Python 3.12 and newer, GNU Autoconf v2.71 is required. +For Python 3.11 and earlier, GNU Autoconf v2.69 is required. +For GNU Autoconf v2.69, change the ``:271`` tag to ``:269``. + +If you cannot (or don't want to) use the ``cpython_autoconf`` containers, +install the :program:`autoconf-archive` and :program:`pkg-config` utilities, +and make sure the :file:`pkg.m4` macro file located in the appropriate +:program:`aclocal` location:: $ ls $(aclocal --print-ac-dir) | grep pkg.m4 -If the system copy of Autoconf does not match this version, you will need to -install your own copy of Autoconf. +.. note:: + + Running :program:`autoreconf` is not the same as running :program:`autoconf`. + For example, running :program:`autoconf` by itself will not regenerate + :file:`pyconfig.h.in`. + :program:`autoreconf` runs :program:`autoconf` and a number of other tools + repeatedly as appropriate. .. _build_troubleshooting: @@ -531,6 +543,10 @@ validate if the change can be made or not. with native extensions and other tools that interact with the Python interpreter. See the documentation about the :ref:`release candidate ` phase. +When the PR check fails, the associated run will have the updated ABI file +attached as an artifact. After release manager approval, you can download and +add this file into your PR to pass the check. + You can regenerate the ABI file by yourself by invoking the ``regen abidump`` Make target. Note that for doing this you need to regenerate the ABI file in the same environment that the GitHub CI uses to check for it. This is because @@ -577,6 +593,7 @@ support. For editors and tools which the core developers have felt some special comment is needed for coding *in* Python, see :ref:`resources`. +.. _build-directory-structure: Directory structure =================== @@ -627,8 +644,7 @@ every rule. ``Programs`` Source code for C executables, including the main function for the - CPython interpreter (in versions prior to Python 3.5, these files are - in the Modules directory). + CPython interpreter. ``Python`` The code that makes up the core CPython runtime. This includes the diff --git a/include/branches.csv b/include/branches.csv deleted file mode 100644 index bfec9da84b..0000000000 --- a/include/branches.csv +++ /dev/null @@ -1,7 +0,0 @@ -Branch,Schedule,Status,First release,End of life,Release manager -main,:pep:`693`,feature,*2023-10-02*,*2028-10*,Thomas Wouters -3.11,:pep:`664`,bugfix,2022-10-24,*2027-10*,Pablo Galindo Salgado -3.10,:pep:`619`,bugfix,2021-10-04,*2026-10*,Pablo Galindo Salgado -3.9,:pep:`596`,security,2020-10-05,*2025-10*,Łukasz Langa -3.8,:pep:`569`,security,2019-10-14,*2024-10*,Łukasz Langa -3.7,:pep:`537`,security,2018-06-27,*2023-06-27*,Ned Deily diff --git a/include/end-of-life.csv b/include/end-of-life.csv deleted file mode 100644 index be9fe1b728..0000000000 --- a/include/end-of-life.csv +++ /dev/null @@ -1,10 +0,0 @@ -Branch,Schedule,Status,First release,End of life,Release manager -3.6,:pep:`494`,end-of-life,2016-12-23,2021-12-23,Ned Deily -3.5,:pep:`478`,end-of-life,2015-09-13,2020-09-30,Larry Hastings -3.4,:pep:`429`,end-of-life,2014-03-16,2019-03-18,Larry Hastings -3.3,:pep:`398`,end-of-life,2012-09-29,2017-09-29,"Georg Brandl, Ned Deily (3.3.7+)" -3.2,:pep:`392`,end-of-life,2011-02-20,2016-02-20,Georg Brandl -3.1,:pep:`375`,end-of-life,2009-06-27,2012-04-09,Benjamin Peterson -3.0,:pep:`361`,end-of-life,2008-12-03,2009-06-27,Barry Warsaw -2.7,:pep:`373`,end-of-life,2010-07-03,2020-01-01,Benjamin Peterson -2.6,:pep:`361`,end-of-life,2008-10-01,2013-10-29,Barry Warsaw diff --git a/include/release-cycle.json b/include/release-cycle.json index df82e64ed4..38c0fd2bad 100644 --- a/include/release-cycle.json +++ b/include/release-cycle.json @@ -1,8 +1,16 @@ { - "3.12": { + "3.13": { "branch": "main", - "pep": 693, + "pep": 719, "status": "feature", + "first_release": "2024-10-01", + "end_of_life": "2029-10", + "release_manager": "Thomas Wouters" + }, + "3.12": { + "branch": "3.12", + "pep": 693, + "status": "prerelease", "first_release": "2023-10-02", "end_of_life": "2028-10", "release_manager": "Thomas Wouters" @@ -18,7 +26,7 @@ "3.10": { "branch": "3.10", "pep": 619, - "status": "bugfix", + "status": "security", "first_release": "2021-10-04", "end_of_life": "2026-10", "release_manager": "Pablo Galindo Salgado" @@ -42,7 +50,7 @@ "3.7": { "branch": "3.7", "pep": 537, - "status": "security", + "status": "end-of-life", "first_release": "2018-06-27", "end_of_life": "2023-06-27", "release_manager": "Ned Deily" diff --git a/include/release-cycle.mmd b/include/release-cycle.mmd deleted file mode 100644 index fc437ab590..0000000000 --- a/include/release-cycle.mmd +++ /dev/null @@ -1,49 +0,0 @@ -gantt - dateFormat YYYY-MM-DD - title Python release cycle - axisFormat %Y - - section Python 2.6 - end-of-life :crit, python2.6, 2008-10-01,2013-10-29 - - section Python 3.0 - end-of-life :crit, python3.0, 2008-12-03,2009-06-27 - - section Python 3.1 - end-of-life :crit, python3.1, 2009-06-27,2012-04-09 - - section Python 2.7 - end-of-life :crit, python2.7, 2010-07-03,2020-01-01 - - section Python 3.2 - end-of-life :crit, python3.2, 2011-02-20,2016-02-20 - - section Python 3.3 - end-of-life :crit, python3.3, 2012-09-29,2017-09-29 - - section Python 3.4 - end-of-life :crit, python3.4, 2014-03-16,2019-03-18 - - section Python 3.5 - end-of-life :crit, python3.5, 2015-09-13,2020-09-30 - - section Python 3.6 - end-of-life :crit, python3.6, 2016-12-23,2021-12-23 - - section Python 3.7 - security :done, python3.7, 2018-06-27,2023-06-27 - - section Python 3.8 - security :done, python3.8, 2019-10-14,2024-10-01 - - section Python 3.9 - security :done, python3.9, 2020-10-05,2025-10-01 - - section Python 3.10 - bugfix :active, python3.10, 2021-10-04,2026-10-01 - - section Python 3.11 - bugfix :active, python3.11, 2022-10-24,2027-10-01 - - section Python 3.12 - feature : python3.12, 2023-10-02,2028-10-01 diff --git a/index.rst b/index.rst index 063dced4a1..b84a766674 100644 --- a/index.rst +++ b/index.rst @@ -69,7 +69,8 @@ instructions please see the :ref:`setup guide `. 8. Add a News entry into the ``Misc/NEWS.d`` directory as individual file. The news entry can be created by using `blurb-it `_, or the `blurb `_ tool and its ``blurb add`` - command. Please read more about ``blurb`` in :ref:`documentation `. + command. Please read more about ``blurb`` in its + `repository `_. .. note:: diff --git a/internals/interpreter.rst b/internals/interpreter.rst index 5c5cfed03d..68d5017d24 100644 --- a/internals/interpreter.rst +++ b/internals/interpreter.rst @@ -13,6 +13,13 @@ The CPython 3.11 bytecode interpreter (a.k.a. virtual machine) has a number of i We describe the inner workings of the 3.11 interpreter here, with an emphasis on understanding not just the code but its design. While the interpreter is forever evolving, and the 3.12 design will undoubtedly be different again, knowing the 3.11 design will help you understand future improvements to the interpreter. +Other sources +------------- + +* Brandt Bucher's talk about the specializing interpreter at PyCon US 2023. + `Slides `_ + `Video `_ + Introduction ============ diff --git a/requirements.txt b/requirements.txt index 3b08c6b77f..f872cdad08 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,7 +1,8 @@ -Sphinx==6.1.3 +Sphinx==7.0.1 furo>=2022.6.4 +jinja2 sphinx-lint==0.6.7 +sphinx-notfound-page sphinx_copybutton>=0.3.3 -sphinxcontrib-mermaid sphinxext-opengraph>=0.7.1 sphinxext-rediraffe diff --git a/triage/issue-tracker.rst b/triage/issue-tracker.rst index 976cf1891f..889d71e9ab 100644 --- a/triage/issue-tracker.rst +++ b/triage/issue-tracker.rst @@ -84,16 +84,44 @@ The submission form has only two fields that you need to fill: information as appropriate). In particular, *what version of Python* you were using. -Understanding the issue's progress and status ---------------------------------------------- - -There is a number of additional fields like **Assignees**, **Labels**, -**Projects**, and **Milestone**. Those are filled by triagers and core -developers, this is covered in the :ref:`triaging` page. You don't need +You can tag someone, with :samp:`@{username}` in a comment, +if you think the issue should be brought to their attention. +Use the :ref:`experts` to know who wants to be +tagged or assigned for specific areas. + +There are a number of additional fields like **Assignees**, **Labels**, +and **Projects**. Those are filled by triagers and core +developers and are covered in the :ref:`triaging` page. You don't need to worry about those when reporting issues as a Python user. -You will automatically receive an update each time an action is taken on -the bug, unless you changed your GitHub notification settings. +Adding special links +-------------------- + +The following abbreviations can be used in a comment to generate a link: + +* :samp:`GH-{NNN}`: to link to another issue or PR; +* :samp:`PEP-{NNN}`: to link to a specific PEP; +* :samp:`BPO-{NNN}`: to link to a bugs.python.org issue; + +See also the `list of autolinks supported by GitHub `_. + +Following issues +---------------- + +If you want to subscribe yourself to an issue, click the :guilabel:`🔔 Subscribe` +button in the sidebar. Similarly, if you were tagged by somebody else but +decided this issue is not for you, click the :guilabel:`🔕 Unsubscribe` +button in the sidebar. Note that you are automatically subscribed to +issues you created. + +Tracking dependencies and duplicates +------------------------------------ + +It is possible to use `checklists`_ to track dependencies or, +in case of meta-issues, to link to the other related issues. + +By writing :samp:`Duplicate of #{NNN}` in a comment, you can +`mark issues and PRs as duplicates `_. Disagreement With a Resolution on the Issue Tracker @@ -128,4 +156,7 @@ reason either as ``complete`` or ``not planned``. .. _devguide repo: https://github.com/python/devguide/issues .. _Roundup: https://roundup.sourceforge.io/ .. _Python Discourse: https://discuss.python.org/ +.. _autolinks: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/autolinked-references-and-urls +.. _checklists: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/about-task-lists +.. _duplicates: https://docs.github.com/en/issues/tracking-your-work-with-issues/marking-issues-or-pull-requests-as-a-duplicate .. _Core Development Discourse category: https://discuss.python.org/c/core-dev/23 diff --git a/triage/labels.rst b/triage/labels.rst index bcdd6bef57..95e84558b6 100644 --- a/triage/labels.rst +++ b/triage/labels.rst @@ -11,405 +11,144 @@ 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 `_. -General purpose labels -====================== -:gh-label:`type-behavior` - Used for issues/PRs that address unintentional behavior, but do not - pose significant security concerns. Generally, bugfixes will be attached - to a specific issue where the unintended behavior was first reported. +.. _general-purpose-labels: +.. _Type: +.. _labels-type: -:gh-label:`type-documentation` - Used for issues/PRs that exclusively involve changes to - the documentation. Documentation includes ``*.rst`` files, docstrings, - and code comments. +Type labels +=========== -:gh-label:`type-enhancement` - Used for issues/PRs that provide additional functionality - or capabilities beyond the existing specifications. +These labels are used to specify the type of issue: -:gh-label:`type-performance` - Used for issues/PRs that provide performance optimizations. +* :gh-label:`type-bug`: for unexpected behaviors, bugs, or exceptions + (not hard crashes). +* :gh-label:`type-crash`: for hard crashes of the interpreter, possibly with a + core dump. +* :gh-label:`type-feature`: for feature requests or enhancements. + The `Ideas Discourse category`_ can be used to discuss enhancements + before filing an issue. +* :gh-label:`type-security`: for security issues. + See also `Reporting security issues in Python`_. -:gh-label:`type-security` - Used for issues/PRs that involve critical security issues. Less severe - security concerns can instead use the type-bugfix label. -:gh-label:`type-tests` - Used for issues/PRs that exclusively involve changes to the tests. +.. _Component: +.. _labels-component: -:gh-label:`OS-Mac` / :gh-label:`OS-Windows` - Used for issues/PRs involving changes which only have an effect upon - a specific operating system. +Component labels +================ -:gh-label:`spam` - Used for issues/PRs that don't include enough eggs or bacon. +These labels are mostly used to specify which :ref:`part of the codebase +` is affected by the issue/PR: -Labels specific to issues -========================= +* :gh-label:`stdlib`: for standard library modules in the :cpy-file:`Lib` + directory (written in Python). +* :gh-label:`extension-modules`: for standard library modules in the + :cpy-file:`Modules` directory (written in C). +* :gh-label:`interpreter-core`: for changes related to the interpreter core in + the :cpy-file:`Objects`, :cpy-file:`Python`, :cpy-file:`Grammar`, + and :cpy-file:`Parser` dirs (written mostly in C). +* :gh-label:`docs`: for documentation in the :cpy-file:`Doc` directory + (written in :ref:`reStructuredText `), docstrings, and code comments. +* :gh-label:`tests`: for tests in the :cpy-file:`Lib/test` directory + (written in Python) and other changes related to tests, :mod:`unittest`, + or :mod:`doctest`. -Priority --------- +OS labels +========= -:gh-label:`release-blocker` - The highest priority of an issue. If unaddressed, will cause the - release manager to hold releasing a new version of Python. +These labels are used to specify which operating systems are affected. +Since most issues either affect all systems or are specific to Unix, +the only available labels are :gh-label:`OS-windows`, :gh-label:`OS-mac`, +and :gh-label:`OS-freebsd`. -:gh-label:`deferred-blocker` - A release blocker that was pushed one or more releases into the - future. Possibly a temporary workaround was employed, or the version - of Python the issue is affecting is still in alpha or beta stages - of development. -Component ---------- +.. _Expert labels: +.. _Topic labels: -:gh-label:`library` - Used for issues involving Python modules in the ``Lib/`` dir. +Topic labels +============ -:gh-label:`docs` - Used for issues involving documentation in the ``Doc/`` dir. +These labels are used to denote the specific topic area, if any, of +the issue/PR. This includes both specific modules/packages and generic +interest areas. -:gh-label:`interpreter-core` - Used for issues in interpreter core (``Objects/``, ``Python/``, - ``Grammar/``, and ``Parser/`` dirs). +Adding these labels is also a way to notify the relevant experts, since +they are encouraged to subscribe to them. Depending on the label, +this might also automatically add the issue to a GitHub project. -:gh-label:`extension-modules` - Used for issues involving C modules in the ``Modules/`` dir. +You can see the `full list of topic labels on GitHub +`_. -:gh-label:`tests` - Used for issues involving only Python's regression test suite, i.e. - files in the ``Lib/test/`` dir. -Other ------ +Version labels +============== -:gh-label:`new` - Denotes that the issue hasn't been looked at by triagers or core - developers yet. +These labels are used to indicate which versions of Python are affected. +The available version labels (with the form :samp:`3.{N}`) are updated +whenever new major releases are created or retired. -:gh-label:`easy` - Denotes that the issue is a good candidate for a newcomer to address. +See also :ref:`the branch status page ` +for a list of active branches. -Labels specific to PRs -====================== +.. _Keywords: +.. _Other: +.. _Priority: +.. _labels-other: -:gh-label:`DO-NOT-MERGE` - Used on PRs to prevent miss-islington from being able - to automatically merge the pull request. This label is appropriate when a PR - has a non-trivial conflict with the branch it is being merged into. - -:gh-label:`expert-asyncio` - Used for PRs which involve changes to the asyncio module - or other asynchronous frameworks that utilize it. - -:gh-label:`invalid` - Used manually for PRs that do not meet basic requirements and - automatically added by bedevere when PR authors attempt to merge maintenance - branches into the main branch. During events such as the October - Hacktoberfest, this label will prevent the PR from counting toward the - author's contributions. - -needs backport to X.Y - For example, :gh-label:`needs backport to 3.11`. - Used for PRs which are appropriate to backport to - branches prior to main. Generally, backports to the maintenance branches - are primarily bugfixes and documentation clarifications. Backports to the - security branches are strictly reserved for PRs involving security fixes, such as - crashes, privilege escalation, and DoS. The use of this label will cause - miss-islington to attempt to automatically merge the PR into the branches - specified. - -:gh-label:`skip issue` - Used for PRs which involve trivial changes, such as typo fixes, - comment changes, and section rephrases. The majority of PRs require - an issue to be attached to, but if there are no code changes and the - section being modified retains the same meaning, this label might be - appropriate. - -:gh-label:`skip news` - Similar to the skip issue label, this label is used for PRs which - involve trivial changes, backports, or already have a relevant news entry - in another PR. Any potentially impactful changes should have a - corresponding news entry, but for trivial changes it's commonly at the - discretion of the PR author if they wish to opt-out of making one. - -:gh-label:`sprint` - Used for PRs authored during an in-person sprint, such as - at PyCon, EuroPython, or other official Python events. The label is - used to prioritize the review of those PRs during the sprint. - -:gh-label:`stale` - Used for PRs that include changes which are no longer relevant, or when the - author hasn't responded to feedback in a long period of time, or when the - reviewer is unresponsive. This label helps core developers quickly identify - PRs that are candidates for closure or require a ping to the author or - reviewer. - -:gh-label:`awaiting review` - Used for PRs that haven't been reviewed by anyone yet. - -:gh-label:`awaiting core review` - Used when the PR is authored by a core developer or when a non-core - developer has reviewed the PR, even if they requested changes. - Note that reviewers could have been added manually by a triager or core - developer, or included automatically through use of the `CODEOWNERS - `_ - file. - -:gh-label:`awaiting changes` - A reviewer required changes to proceed with the PR. - -:gh-label:`awaiting change review` - The PR author made requested changes, and they are waiting for review. - -:gh-label:`awaiting merge` - The PR has been approved by a core developer and is ready to merge. - -:gh-label:`test-with-buildbots` - Used on PRs to test the latest commit with the buildbot fleet. Generally for - PRs with large code changes requiring more testing before merging. This - may take multiple hours to complete. Triagers can also stop a stuck build - using the web interface. +Other labels +============ +* :gh-label:`triaged`: for issue has been accepted as valid by a triager. +* :gh-label:`easy`: for issues that are considered easy. +* :gh-label:`build`/:gh-label:`performance`: for issues related + to the build process or performance, respectively. +* :gh-label:`release-blocker`/:gh-label:`deferred-blocker`: for issues/PRs + that, unless fixed, will hold the current or next release respectively. + Triagers may set these labels for issues that must be fixed before a release, + and the :ref:`branch's release manager ` + will review them and determine if they indeed qualify, + removing or retaining the label as appropriate. +* :gh-label:`pending`: for issues/PRs that will be closed unless further + feedback is provided. +* :gh-label:`stale`: for issues/PRs that have been inactive for a while. +* :gh-label:`sprint`: for easier filtering of issues/PRs being worked on + during official sprints. + +.. _GitHub Labels for PRs: .. _github-pr-labels: -GitHub Labels for PRs -===================== - -An important component of triaging PRs for the CPython repo involves -appropriately categorizing them through the usage of labels. For this -purpose we're using :ref:`gh-labels`. - -Applying labels for Issues -========================== - -The major elements found in an issue report include: - -* Classification (including *Title*) - Metadata that lets us categorize - the issue. Apart from the *Title* field, we use some *type-*, *component-*, and - *version-* specific labels. -* Process - These fields indicate the state of the issue and its progress - toward resolution. The fields are *Status* (open/closed), *Assignees*, - *Comment*, as well as *priority-* and *keyword-* specific labels. -* Messages -* History - -Title ------ -A brief description of the issue. Review whether the title is too generic or -specifies an incorrect term or library. - -(Optional) Add a prefix at the start of the title to indicate the module, e.g. -IDLE, doc, or asyncio. - -Type ----- -Describes the type of issue. If an issue does not fit within any -specific type, please do not set a type. - -+----------------+----------------------------------------------------------+ -| Type | Description | -+================+==========================================================+ -| behavior | Unexpected behavior, result, or exception. Most bugs | -| | will have this type. This group also includes compile | -| | errors, and crashers. | -+----------------+----------------------------------------------------------+ -| enhancement | Issues that propose the addition of new functionality, | -| | such as new functions, classes, modules, or even new | -| | arguments for existing functions. Also used for | -| | improvements in the documentation, test suite and | -| | other refactorings. A good place to discuss enhancements | -| | prior to filing an issue is the | -| | `Ideas Discourse category`_. | -+----------------+----------------------------------------------------------+ -| performance | Situations where too much time is necessary to complete | -| | the task. For example, a common task now takes | -| | significantly longer to complete. This group also | -| | includes resource usage (e.g. too much memory needed) | -| | issues. | -+----------------+----------------------------------------------------------+ -| security | Issues that might have security implications. Report | -| | security vulnerabilities using the procedure found in | -| | the `Reporting security issues in Python`_ page on the | -| | python.org website. | -+----------------+----------------------------------------------------------+ - -Stage ------ -A needed next action to advance the issue. The *stage* on GitHub issues is -determined by presence of a linked PR and whether the issue is still open -or closed. It is the PR that holds code review-related labels. - -Components ----------- -The area or Python library affected by the issue. A single issue can apply -multiple component labels. - -One or more components may be selected for an issue: - -+-------------------+------------------------------------------------------+ -| Component | Description | -+===================+======================================================+ -| Documentation | The documentation in Doc_ (source used to build HTML | -| | docs for https://docs.python.org/). | -+-------------------+------------------------------------------------------+ -| Extension Modules | C modules in Modules_. | -+-------------------+------------------------------------------------------+ -| Interpreter Core | The interpreter core. | -| | The built-in objects in `Objects`_, the `Python`_, | -| | `Grammar`_ and `Parser`_ dirs. | -+-------------------+------------------------------------------------------+ -| Library (Lib) | Python modules in Lib_. | -+-------------------+------------------------------------------------------+ -| Tests | The unittest framework in `Lib/unittest`_ | -| | The doctest framework `Lib/doctest.py`_. | -| | The CPython tests in `Lib/test`_. | -| | The test runner in `Lib/test/regrtest.py`_. | -| | The test support utilities in `Lib/test/support`_. | -+-------------------+------------------------------------------------------+ - -Versions --------- -The known versions of Python that the issue affects and should be fixed for. - -Thus if an issue for a new feature is assigned for e.g., Python 3.8 but is not -applied before Python 3.8.0 is released, this label should be updated to say -``python-3.9`` as the version and drop ``python-3.8``. - -Priority --------- -What is the severity and urgency? - -+------------------+--------------------------------------------------------+ -| Priority | Description | -+==================+========================================================+ -| normal | The default value for most issues filed. | -+------------------+--------------------------------------------------------+ -| deferred blocker | The issue will not hold up the next release, *n*. It | -| | will be promoted to a *release blocker* for the | -| | following release, *n+1*. | -+------------------+--------------------------------------------------------+ -| release blocker | The issue **must** be fixed before *any* release is | -| | made, e.g., will block the next release even if it is | -| | an alpha release. | -+------------------+--------------------------------------------------------+ - -As a guideline, whether a bug is a *release blocker* for the current -:ref:`release schedule ` is decided by the release manager. -Triagers may recommend this priority and should notify the release manager by -tagging them in a comment using ``@username``. If needed, consult the -:ref:`release schedule ` and the release's associated PEP for the -release manager's name. - -Keywords --------- -Various informational flags about the issue. Multiple values are possible. - -+---------------+------------------------------------------------------------+ -| Keyword | Description | -+===============+============================================================+ -| easy | Fixing the issue should not take longer than a day for | -| | someone new to contributing to Python to solve. | -+---------------+------------------------------------------------------------+ - -Nosy List ---------- -A list of people who may be interested in an issue. - -This used to be a feature of the old issue tracker. On GitHub issues the -same effect is achieved by tagging people in a comment using ``@username``. - -It is acceptable to tag someone to if you think the issue should be brought to -their attention. Use the :ref:`experts` to know who wants to be added to the -nosy list for issues targeting specific areas. - -If you want to subscribe yourself to an issue, click the *🔔 Subscribe* -button in the sidebar. Similarly, if you were tagged by somebody else but -decided this issue is not for you, you might click the *🔕 Unsubscribe* -button in the sidebar. - -Assignees ---------- -Who is expected to take the next step in resolving the issue. - -It is acceptable to assign an issue to someone if the issue cannot move -forward without their help, e.g., they need to make a technical decision to -allow the issue to move forward. Also consult the :ref:`experts` as certain -stdlib modules should always be assigned to a specific person. - -Note that in order to assign an issue to someone, that person **must** be -a team member, likely a Triager or a core developer. - -Dependencies ------------- -The issue requires the listed issue(s) to be resolved first before it can move -forward. This is achieved using checkbox lists in the initial issue description -comment. Long story short, if you add this:: - - - [x] #739 - - [ ] https://github.com/octo-org/octo-repo/issues/740 - - [ ] Add delight to the experience when all tasks are complete :tada: - -then those will become sub-tasks on the given issue. Moreover, GitHub will -automatically mark a task as complete if the other referenced issue is -closed. - -More details in the `official GitHub documentation -`_. - -Superseder ----------- -The issue is a duplicate of the listed issue(s). To make GitHub mark -an issue as duplicate, write "Duplicate of #xxxx" in a comment. - -Status ------- - -+---------------+------------------------------------------------------------+ -| Status | Description | -+===============+============================================================+ -| open | Issue is not resolved. | -+---------------+------------------------------------------------------------+ -| closed | The issue has been resolved (somehow). | -+---------------+------------------------------------------------------------+ - -Linked pull requests --------------------- -A link might be added manually using the cog icon next to this field. -Most commonly though, if the PR includes "Fixes #xxx" in its description, -the link will be added automatically. - -Generating Special Links in a Comment -===================================== -Using the following abbreviations in a comment will automatically generate -a link to relevant web pages. - -+-------------------------------------------------------------+-------------------------------------------------------+ -| Comment abbreviation | Description | -+=============================================================+=======================================================+ -| ``#``, | Links to the tracker issue or PR ```` (they | -| ``GH-`` | share the same sequence of integers on GitHub). | -+-------------------------------------------------------------+-------------------------------------------------------+ -| ``BPO-`` | Links to the old bug tracker at bugs.python.org. | -+-------------------------------------------------------------+-------------------------------------------------------+ -| a 10-, 11-, 12-, or 40-digit hex ```` | Indicates a Git changeset identifier and | -| | generates a link to changeset ```` on GitHub. | -+-------------------------------------------------------------+-------------------------------------------------------+ - -.. _Doc: https://github.com/python/cpython/tree/main/Doc/ -.. _Grammar: https://github.com/python/cpython/tree/main/Grammar/ -.. _Lib: https://github.com/python/cpython/tree/main/Lib/ -.. _Lib/doctest.py: https://github.com/python/cpython/blob/main/Lib/doctest.py -.. _Lib/test: https://github.com/python/cpython/tree/main/Lib/test/ -.. _Lib/test/regrtest.py: https://github.com/python/cpython/blob/main/Lib/test/regrtest.py -.. _Lib/test/support: https://github.com/python/cpython/tree/main/Lib/test/support/ -.. _Lib/unittest: https://github.com/python/cpython/tree/main/Lib/unittest/ -.. _Modules: https://github.com/python/cpython/tree/main/Modules/ -.. _Objects: https://github.com/python/cpython/tree/main/Objects/ -.. _Parser: https://github.com/python/cpython/tree/main/Parser/ -.. _Python: https://github.com/python/cpython/tree/main/Python/ +Labels specific to PRs +====================== + +The following labels only apply to :ref:`Pull Requests `. +They are either set automatically by bots, or added by humans +to trigger specific bot behaviors. + +* :gh-label:`DO-NOT-MERGE`: for PRs that shouldn't be merged in their current + state. It also prevents `miss-islington`_ from being able to automatically + merge the PR. +* :samp:`needs backport to {X.Y}`: used to indicate which branches the PR + should be backported to. Once the PR is merged, ``miss-islington`` will + automatically attempt to create backport PRs for the versions indicated + by these labels. + See also :ref:`the status of the Python branches ` for a list + of branches and the type of PRs that can be backported to them. +* :gh-label:`skip issue`: for trivial changes (such as typo fixes, comment + changes, and section rephrases) that don't require a corresponding issue. +* :gh-label:`skip news`: for PRs that don't need a NEWS entry. + The :ref:`news-entry` section covers in details in which cases the NEWS entry + can be skipped. +* :gh-label:`test-with-buildbots`: used to test the latest commit with + the :ref:`buildbot fleet ` whenever more testing is required + before merging. This may take multiple hours to complete. +* :samp:`awaiting {action}`: these labels are applied and used by `bedevere`_ + to indicate the stage of a PR and should not be applied manually. + + .. _Reporting security issues in Python: https://www.python.org/dev/security/ .. _Ideas Discourse category: https://discuss.python.org/c/ideas/6 +.. _miss-islington: https://github.com/python/miss-islington +.. _bedevere: https://github.com/python/bedevere/#pr-state-machine diff --git a/triage/triage-team.rst b/triage/triage-team.rst index c901d0d528..a3e703595d 100644 --- a/triage/triage-team.rst +++ b/triage/triage-team.rst @@ -16,15 +16,11 @@ needed, to other repos such as devguide and core-workflow. Responsibilities include: -* PR/issue management - - Reviewing PRs - - Assisting contributors - - Notifying appropriate core developers -* Applying appropriate labels to PRs/Issues - - Skip news - - Skip issue - - Good first issue - - Other categorizations +* Classifying issues and PRs +* Applying appropriate :ref:`labels ` to issues/PRs +* Notifying appropriate core developers +* :ref:`Reviewing PRs ` +* Assisting contributors Although triagers have the power to close PRs, they should generally not do so without first consulting a core developer. By having triagers and core developers work together, @@ -43,12 +39,12 @@ following: - PRs proposing changes that have been rejected by Python core developers elsewhere (e.g. in an issue or a PEP rejection notice) -If a triager has any doubt about whether to close a PR, they should consult a core -developer before taking any action. +If a triager has any doubt about whether to close a PR, +they should consult a core developer before taking any action. -Triagers can also make use of the ``invalid`` and ``stale`` labels to suggest that a -PR may be suitable for closure. For more information, see the -:ref:`GitHub PR labels ` section. +Triagers can also make use of the :gh-label:`pending` and :gh-label:`stale` +labels to suggest that a PR may be suitable for closure. +For more information, see the entries in the :ref:`labels-other` section. Note that it is of paramount importance to treat every contributor to the Python project kindly and with respect. Regardless of whether they're entirely new @@ -69,8 +65,8 @@ more repositories than just CPython. When you have consistently shown the ability to properly help triage issues without guidance, you may request that you -be given the "Triager" role on the :ref:`issue tracker `. You can make the request -to any core developer. If they decide you are ready +be given the "Triager" role on the :ref:`issue tracker `. +You can make the request to any core developer. If they decide you are ready to gain the extra privileges on the tracker they will then act as a mentor to you until you are ready to do things entirely on your own. There is no set rule as to how many issues you need to have helped with before or how long you have diff --git a/triage/triaging.rst b/triage/triaging.rst index 0fcb7f5889..9e0a621553 100644 --- a/triage/triaging.rst +++ b/triage/triaging.rst @@ -24,9 +24,22 @@ Checklist for Triaging * If the issue is clearly invalid (unrelated to CPython, duplicate, spam, etc), you can close it as "not planned". -.. Remove note once python/core-workflow#460 is implemented +Assignees +--------- -.. note:: Some of these fields can only be set/edited by core developers. +This field indicates who is expected to take the next step in resolving +the issue. + +It is acceptable to assign an issue to someone if the issue cannot move +forward without their help; e.g., they need to make a technical decision on +how to proceed. Also consult the :ref:`experts` as certain +stdlib modules should always be assigned to a specific person. + +Note that in order to assign an issue to someone, that person **must** be +a team member, likely a triager or a core developer. + +.. The Assignees subsection was copied from the labels.rst page in #930. + For consistency, the other fields mentioned above should be documented too. .. _helptriage: diff --git a/versions.rst b/versions.rst index c36f7e6725..78224b09d8 100644 --- a/versions.rst +++ b/versions.rst @@ -5,7 +5,7 @@ Status of Python Versions ========================= -The main branch is currently the future Python 3.12, and is the only +The ``main`` branch is currently the future Python 3.13, and is the only branch that accepts new features. The latest release for each Python version can be found on the `download page `_. @@ -13,8 +13,8 @@ version can be found on the `download page `_ Python Release Cycle ==================== -.. mermaid:: include/release-cycle.mmd - +.. raw:: html + :file: include/release-cycle.svg Supported Versions ================== @@ -23,7 +23,7 @@ Dates shown in *italic* are scheduled and can be adjusted. .. csv-table:: :header-rows: 1 - :widths: 5, 5, 15, 15, 12, 40 + :width: 100% :file: include/branches.csv .. Remember to update main branch in the paragraph above too @@ -34,7 +34,7 @@ Unsupported Versions .. csv-table:: :header-rows: 1 - :widths: 5, 5, 15, 15, 12, 40 + :width: 100% :file: include/end-of-life.csv @@ -55,16 +55,3 @@ See also the :ref:`devcycle` page for more information about branches. By default, the end-of-life is scheduled 5 years after the first release, but can be adjusted by the release manager of each branch. All Python 2 versions have reached end-of-life. - -.. raw:: html - -