Merge branch 'main' into bot/update-uv-build-version

Author: ncoghlan

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/guides/multi-version-installs.rst

@@ -37,7 +37,3 @@ time, but that approach does mean that standard command line invocations of
 the affected tools can't be used - it's necessary to write a custom
 wrapper script or use ``python3 -c '<command>'`` to invoke the application's
 main entry point directly.
-
-Refer to the `pkg_resources documentation
-<https://setuptools.readthedocs.io/en/latest/pkg_resources.html#workingset-objects>`__
-for more details.

source/guides/packaging-namespace-packages.rst

@@ -159,8 +159,7 @@ Legacy namespace packages
 
 These two methods, that were used to create namespace packages prior to :pep:`420`,
 are now considered to be obsolete and should not be used unless you need compatibility
-with packages already using this method. Also, :doc:`pkg_resources <setuptools:pkg_resources>`
-has been deprecated.
+with packages already using one of these methods.
 
 To migrate an existing package, all packages sharing the namespace must be migrated simultaneously.
 
@@ -176,7 +175,7 @@ pkgutil-style namespace packages
 Python 2.3 introduced the :doc:`pkgutil <python:library/pkgutil>` module and the
 :py:func:`python:pkgutil.extend_path` function. This can be used to declare namespace
 packages that need to be compatible with both Python 2.3+ and Python 3. This
-is the recommended approach for the highest level of compatibility.
+was the recommended approach for the highest level of compatibility.
 
 To create a pkgutil-style namespace package, you need to provide an
 :file:`__init__.py` file for the namespace package:
@@ -216,10 +215,18 @@ in the `pkgutil namespace example project`_.
 pkg_resources-style namespace packages
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-:doc:`Setuptools <setuptools:index>` provides the `pkg_resources.declare_namespace`_ function and
+.. warning::
+
+    The information in this section is obsolete and is no longer functional
+    (as of Setuptools 82.0.0). It is only retained for historical reference.
+
+    ``pkg_resources`` has been deprecated and was fully removed in Setuptools 82.0.0.
+
+:doc:`Setuptools <setuptools:index>` previously provided the ``pkg_resources.declare_namespace`` function and
 the ``namespace_packages`` argument to :func:`~setuptools.setup`. Together
-these can be used to declare namespace packages. While this approach is no
-longer recommended, it is widely present in most existing namespace packages.
+these could be used to declare namespace packages. While this approach is no
+longer supported, it may still be encountered in environments using older
+``setuptools`` versions.
 If you are creating a new distribution within an existing namespace package that
 uses this method then it's recommended to continue using this as the different
 methods are not cross-compatible and it's not advisable to try to migrate an
@@ -281,11 +288,3 @@ to :func:`~setuptools.setup` in :file:`setup.py`. For example:
         packages=find_packages()
         namespace_packages=['mynamespace']
     )
-
-A complete working example of two pkg_resources-style namespace packages can be found
-in the `pkg_resources namespace example project`_.
-
-.. _pkg_resources.declare_namespace:
-    https://setuptools.readthedocs.io/en/latest/pkg_resources.html#namespace-package-support
-.. _pkg_resources namespace example project:
-    https://github.com/pypa/sample-namespace-packages/tree/master/pkg_resources

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/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:
 
@@ -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.