Merge branch 'main' into clarify-environment-marker-comparisons

Author: ncoghlan

source/discussions/deploying-python-applications.rst

@@ -97,7 +97,7 @@ services, and DLL/EXE COM servers might work but it is not actively supported.
 The distutils extension is released under the MIT-licence and Mozilla
 Public License 2.0.
 
-.. __: https://devguide.python.org/#status-of-python-branches
+.. __: https://devguide.python.org/versions/
 
 macOS
 -----

source/discussions/versioning.rst

@@ -27,7 +27,7 @@ examples of version numbers [#version-examples]_:
 - A post-release of an alpha release (possible, but discouraged): ``1.2.0a1.post1``
 - A simple version with only two components: ``23.12``
 - A simple version with just one component: ``42``
-- A version with an epoch: ``1!1.0``
+- A version with an epoch (discouraged): ``1!1.0``
 
 Projects can use a cycle of pre-releases to support testing by their users
 before a final release. In order, the steps are: alpha releases, beta releases,
@@ -46,13 +46,14 @@ notes. They should not be used for bug fixes; these should be done with a new
 final release (e.g., incrementing the third component when using semantic
 versioning).
 
-Finally, epochs, a rarely used feature, serve to fix the sorting order when
-changing the versioning scheme. For example, if a project is using calendar
-versioning, with versions like 23.12, and switches to semantic versioning, with
-versions like 1.0, the comparison between 1.0 and 23.12 will go the wrong way.
-To correct this, the new version numbers should have an explicit epoch, as in
-"1!1.0", in order to be treated as more recent than the old version numbers.
-
+Finally, epochs were intended to fix the sorting order when changing the
+versioning scheme. For example, if a project was using calendar versioning, with
+versions like ``23.12``, and switched to semantic versioning, with versions like
+``1.0``, the comparison between ``1.0`` and ``23.12`` would go the wrong way. To
+correct this, the new version numbers would have an explicit epoch, as in
+``1!1.0``, in order to be treated as more recent than the old version numbers.
+However, this is discouraged, and it is preferable to use a higher version
+number that is unlikely to cause user confusion, such as ``100.0``.
 
 
 Semantic versioning vs. calendar versioning

source/glossary.rst

@@ -14,7 +14,7 @@ Glossary
 
     Build Backend
 
-        A library that takes a source tree
+        A library that takes a :term:`source tree <Project Source Tree>`
         and builds a :term:`source distribution <Source Distribution (or "sdist")>` or
         :term:`built distribution <Built Distribution>` from it.
         The build is delegated to the backend by a

source/guides/analyzing-pypi-package-downloads.rst

@@ -333,6 +333,14 @@ Usage:
 The `pandas-gbq`_ project allows for accessing query results via `Pandas`_.
 
 
+``ClickPy``
+-----------
+
+The `ClickPy`_ project provides a public application to visualize download
+statistics, with free direct SQL access to the underlying open-source
+`ClickHouse`_ database, updated daily.
+
+
 References
 ==========
 
@@ -346,3 +354,5 @@ References
 .. _google-cloud-bigquery: https://cloud.google.com/bigquery/docs/reference/libraries
 .. _pandas-gbq: https://pandas-gbq.readthedocs.io/en/latest/
 .. _Pandas: https://pandas.pydata.org/
+.. _ClickHouse: https://github.com/ClickHouse/ClickHouse
+.. _Clickpy: https://clickpy.clickhouse.com/

source/guides/writing-pyproject-toml.rst

@@ -413,6 +413,7 @@ A list of PyPI classifiers that apply to your project. Check the
 
 .. code-block:: toml
 
+    [project]
     classifiers = [
       # How mature is this project? Common values are
       #   3 - Alpha

source/shared/build-backend-tabs.rst

@@ -38,5 +38,5 @@
     .. code-block:: toml
 
         [build-system]
-        requires = ["uv_build >= 0.10.0, <0.11.0"]
+        requires = ["uv_build >= 0.10.10, <0.11.0"]
         build-backend = "uv_build"

source/specifications/pypirc.rst

@@ -10,6 +10,11 @@ indexes <Package Index>` (referred to here as "repositories"), so that you don't
 have to enter the URL, username, or password whenever you upload a package with
 :ref:`twine` or :ref:`flit`.
 
+The :file:`.pypirc` file **SHOULD** be UTF-8 encoded.
+
+Tools that read or write :file:`.pypirc` files may not function correctly
+if another character encoding is used.
+
 The format (originally defined by the :ref:`distutils` package) is:
 
 .. code-block:: ini

source/specifications/pyproject-toml.rst

@@ -14,8 +14,6 @@
 The ``pyproject.toml`` file acts as a configuration file for packaging-related
 tools (as well as other tools).
 
-.. note:: This specification was originally defined in :pep:`518` and :pep:`621`.
-
 The ``pyproject.toml`` file is written in `TOML <https://toml.io>`_. Three
 tables are currently specified, namely
 :ref:`[build-system] <pyproject-build-system-table>`,

source/specifications/version-specifiers.rst

@@ -394,6 +394,21 @@ from an earlier epoch::
     1!1.1
     1!2.0
 
+.. note::
+
+   Use of nonzero epochs is discouraged. They are often not supported or
+   discouraged by downstream packaging where Python packages may need to be
+   consumed, and due to their scarce use they may also not be well supported by
+   Python packaging tools.
+
+   When version scheme needs to be changed, it is preferable to continue with
+   monotonically increasing numbers in epoch zero. For example, the version
+   2026.x could be unambiguously followed by 3000.x.
+
+   See `Discouraging use of epoch segments in versions
+   <https://discuss.python.org/t/discouraging-use-of-epoch-segments-in-versions/105811>`__
+   for the relevant discussion.
+
 
 .. _version-specifiers-normalization:
 
@@ -590,8 +605,8 @@ and post-releases for minor corrections::
     1.0.dev2
     1.0.dev3
     1.0.dev4
-    1.0c1
-    1.0c2
+    1.0rc1
+    1.0rc2
     1.0
     1.0.post1
     1.1.dev1
@@ -1273,3 +1288,4 @@ History
 - May 2025: Clarify that development releases are a form of pre-release when
   they are handled.
 - Nov 2025: Make arbitrary equality case insensitivity explicit.
+- Jan 2026: The use of epochs was discouraged.