Update Porting page, move platform experts list there (GH-1839)

Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Co-authored-by: Miro Hrončok <miro@hroncok.cz>

Author: 3 people

conf.py

@@ -276,6 +276,7 @@
     "gh-label": (f"{_repo}/labels/%s", "%s"),
     "github": ("https://github.com/%s", "%s"),
     "github-user": ("https://github.com/%s", "@%s"),
+    "gh-python-team": ("https://github.com/orgs/python/teams/%s", "@python/%s"),
     "pypi": ("https://pypi.org/project/%s/", "%s"),
     "pypi-org": ("https://pypi.org/org/%s/", "%s"),
 }

core-team/experts.rst

@@ -179,23 +179,9 @@ PEG Generator       gvanrossum, pablogsal, lysnikolaou
 Platforms
 =========
 
-For official contacts for supported platforms, see :pep:`11`.
+The **Platforms experts list** has moved to :ref:`ports`.
 
-Platforms listed here are not necessarily supported by CPython.
-Some of the experts listed here maintain and distribute Python
-for “their” platform as a third-party project.
-
-===================   ===========
-Platform              Maintainers
-===================   ===========
-AIX                   ayappanec
-Android               mhsmith
-Emscripten            hoodmane, pmp-p, rdb, rth, ryanking13
-iOS                   freakboy3742, ned-deily
-macOS                 ronaldoussoren, ned-deily, freakboy3742
-Solaris/OpenIndiana   jcea, kulikjak
-Windows               tjguk, zooba, pfmoore
-===================   ===========
+For official contacts for supported platforms, see :pep:`11`.
 
 
 Miscellaneous

developer-workflow/porting.rst

@@ -1,9 +1,131 @@
 .. _porting:
 
-=========================
+============================
+Porting and platform support
+============================
+
+The Python interpreter runs on an underlying *platform* -- the operating system
+(for example, Linux, Windows or macOS), processor (like Intel/AMD, ARM),
+C compiler and library, and other "lower level" details.
+
+CPython is *officially supported* on several platforms, on which the core team
+has adequate knowledge and resources to test releases and fix bugs.
+See :pep:`11` for details.
+
+Other platforms are unsupported *by the core team*, but might be supported
+by others -- as a volunteer project, by a company that wants Python on "their"
+system, or just as a one-off experiment.
+See :pep:`PEP 11 <11#unsupported-platforms>` for the policy on merging code for
+unsupported platforms into the main CPython repository.
+
+
+.. _ports:
+
+Ports and contacts
+==================
+
+The table below lists relevant third-party projects,
+their maintainers, and links to information that's relevant when triaging
+platform-specific issues.
+Officially supported platforms are also included when there is relevant
+information for them (beyond :pep:`11`), or to group similar platforms.
+
+It is OK to @mention the listed GitHub usernames to draw maintainers' attention
+or request their opinion on platform-specific issues.
+Maintainers must only be listed with their permission, and they may remove
+themselves at any time.
+
+Third-party projects should only be listed if they benefit substantially
+more people than the maintainers.
+
+Links should be for the port specifically (not the platform itself),
+and relevant for porting work and fixing platform-specific issues
+(no homepage/marketing links).
+
+.. list-table::
+   :header-rows: 1
+
+   * - Platform
+     - Maintainers
+     - Information
+   * - **AIX**
+     - :github-user:`ayappanec`
+     -
+   * - **Android** [t3]_
+     - :github-user:`mhsmith`
+     - `Usage <https://docs.python.org/3/using/android.html>`__,
+       `Limitations <https://docs.python.org/3/library/intro.html#mobile-platforms>`__,
+       :cpy-file:`Platforms/Android`
+   * - **iOS** [t3]_
+     - :github-user:`freakboy3742`, :github-user:`ned-deily`
+     - `Usage <https://docs.python.org/3/using/ios.html>`__,
+       `Limitations <https://docs.python.org/3/library/intro.html#mobile-platforms>`__,
+       :cpy-file:`Platforms/Apple`
+   * - **Linux** [t1]_
+     -
+     -
+   * - \- Fedora
+     - :github-user:`hroncok`, :github-user:`befeleme`
+     - `Config & patches <https://src.fedoraproject.org/rpms/python3.15/tree/rawhide>`_,
+       `Bugs <https://bugzilla.redhat.com/buglist.cgi?bug_status=__open__&classification=Fedora&columnlist=product%2Ccomponent%2Cassigned_to%2Cbug_status%2Cshort_desc%2Cchangeddate%2Cbug_severity&f1=component&o1=regexp&order=status%2C%20assigned_to%2C%20id%2C%20&product=Fedora&product=Fedora%20EPEL&query_format=advanced&v1=python3\.\d%2B%24>`__,
+       `Maintenance guide <https://hackmd.io/9f64YNIZTCy0ZzKb5wKtqQ?view>`__
+   * - \- Debian
+     - :github-user:`stefanor`
+     - `Config & patches <https://salsa.debian.org/cpython-team/python3/-/tree/master/debian>`_,
+       `Bugs <https://bugs.debian.org/cgi-bin/pkgreport.cgi?src=python3.15>`__,
+       `Wiki <https://wiki.debian.org/Python>`__
+   * - \- Ubuntu
+     - :github-user:`stefanor`
+     - `Config & patches <https://git.launchpad.net/ubuntu/+source/python3.15/tree/debian>`_ (by version),
+       `Bugs <https://launchpad.net/ubuntu/+source/python3-defaults/+bugs>`__
+   * - \- Alpine
+     -
+     - `Config & patches <https://github.com/alpinelinux/aports/tree/master/main/python3>`_
+   * - **macOS** [t1]_
+     - :gh-python-team:`macos-team`, :github-user:`freakboy3742`
+     - `Usage <https://docs.python.org/3/using/mac.html>`__,
+       :cpy-file:`Platforms/Apple`
+   * - **Solaris**/OpenIndiana
+     - :github-user:`jcea`, :github-user:`kulikjak`
+     -
+   * - **WebAssembly**
+     -
+     - `Limitations <https://docs.python.org/3/library/intro.html#webassembly-platforms>`__
+   * - \- WASI [t2]_
+     -
+     - :cpy-file:`WASI <Platforms/WASI>`
+   * - \- Emscripten [t3]_
+     - :github-user:`pmp-p`, :github-user:`rdb`, :github-user:`hoodmane`
+     - :cpy-file:`emscripten <Platforms/emscripten>`
+   * - \- Pyodide
+     - :github-user:`ryanking13`, :github-user:`agriyakhetarpal`
+     -
+   * - **Windows** [t1]_
+     - :gh-python-team:`windows-team`, :github-user:`pfmoore`
+     - `Usage <https://docs.python.org/3/using/windows.html>`__,
+       :cpy-file:`PC`,
+       :cpy-file:`PCbuild`
+   * - **Cross-Platform**
+     -
+     -
+   * - \- conda-forge
+     -
+     - `Recipe <https://github.com/conda-forge/python-feedstock/tree/main/recipe>`_
+
+.. [t1] Specific variants have official :pep:`Tier 1 support <11#tier-1>`
+.. [t2] Specific variants have official :pep:`Tier 2 support <11#tier-2>`
+.. [t3] Specific variants have official :pep:`Tier 3 support <11#tier-3>`
+
+
 Porting to a new platform
 =========================
 
+Porting CPython to an entirely new platform is an adventure.
+If you try it, consider keeping notes -- and updating this guide, if you
+find something that might be relevant to others.
+Since each platform is different, this guide can only give you a
+few rough tips.
+
 The first step is to familiarize yourself with the development toolchain on
 the platform in question, notably the C compiler. Make sure you can compile and
 run a hello-world program using the target compiler.
@@ -12,23 +134,39 @@ Next, learn how to compile and run the Python interpreter on a platform to
 which it has already been ported; preferably Unix, but Windows will
 do, too. The build process for Python, in particular the ``Makefile`` in the
 source distribution, will give you a hint on which files to compile
-for Python.  Not all source files are relevant: some are platform-specific,
-and others are only used in emergencies (for example, ``getopt.c``).
+for Python. Not all source files are relevant: some are platform-specific,
+and others are only used in emergencies (for example,
+:cpy-file:`Python/getopt.c`).
 
 It is not recommended to start porting Python without at least a medium-level
 understanding of your target platform; how it is generally used, how to
 write platform-specific apps, and so on. Also, some Python knowledge is required, or
 you will be unable to verify that your port is working correctly.
 
-You will need a ``pyconfig.h`` file tailored for your platform.  You can
-start with ``pyconfig.h.in``, read the comments, and turn on definitions that
-apply to your platform.  Also, you will need a ``config.c`` file, which lists
-the built-in modules you support.  Again, starting with
-``Modules/config.c.in`` is recommended.
+On systems with a UNIX shell, run the included :cpy-file:`configure` script.
+This should generate all required files, including a :file:`Makefile`.
+If it does not, you will need to debug it (or reimplement it).
+Note that the script is generated from :cpy-file:`configure.ac` using GNU
+Autotools.
+(CPython pins a specific version for reproducibility, but other versions may
+work fine.)
+
+The main files that ``configure`` generates -- and which you might want to
+check -- are:
 
-Finally, you will run into some things that are not supported on your
-target platform.  Forget about the ``posix`` module in the beginning. You can
-simply comment it out of the ``config.c`` file.
+* A :file:`pyconfig.h` file tailored for your platform.
+  If you need to create this manually, start with :cpy-file:`pyconfig.h.in`,
+  read the comments, and turn on definitions that apply to your platform.
+* A :file:`config.c` file, which lists the built-in modules you support.
+  Until you get dynamic extension loading to work, all compiled modules
+  you need to import will need to be listed here.
+  The file is generated from :cpy-file:`Modules/config.c.in`.
+* A :file:`Makefile` with instructions to put everything together.
+  If one isn't generated, try compiling all the ``*.c`` files, and fix the
+  errors -- or omit files that don't look important.
+  For example, forget about the ``posix`` module
+  (:cpy-file:`Modules/posixmodule.c`) in the beginning: don't compile it,
+  and comment it out of the :file:`config.c` file.
 
 Keep working on it until you get a ``>>>`` prompt.  You may have to disable the
 importing of ``site.py`` by passing the ``-S`` option. When you have a prompt,
@@ -38,6 +176,9 @@ At some point you will want to use the ``os`` module; this is the time to start
 thinking about what to do with the ``posix`` module.  It is okay to simply
 comment out functions in the ``posix`` module that cause problems; the
 remaining ones will be quite useful.
+You can use the same approach for other modules too, of course.
 
 Before you are done, it is highly recommended to run the Python regression test
 suite, as described in :ref:`runtests`.
+You will probably need to skip tests that do not make sense; for inspiration
+look at how that's done for the WASI platform.