Update "Dropping older Python versions" guide

Author: chrysle

source/guides/dropping-older-python-versions.rst

@@ -4,23 +4,17 @@
 Dropping support for older Python versions
 ==========================================
 
-Dropping support for older Python versions is supported by the standard :ref:`core-metadata` 1.2 specification via a "Requires-Python" attribute.
+Dropping support for older Python versions is supported by the standard :ref:`core-metadata` 1.2 specification via a :ref:`"Requires-Python" <core-metadata-requires-python>` attribute.
 
 Metadata 1.2+ clients, such as Pip 9.0+, will adhere to this specification by matching the current Python runtime and comparing it with the required version
 in the package metadata. If they do not match, it will attempt to install the last package distribution that supported that Python runtime.
 
-This mechanism can be used to drop support for older Python versions, by amending the "Requires-Python" attribute in the package metadata.
-
-This guide is specifically for users of :ref:`setuptools`, other packaging tools such as ``flit`` may offer similar functionality but users will need to consult relevant documentation.
+This mechanism can be used to drop support for older Python versions, by amending the ``Requires-Python`` attribute in the package metadata.
 
 Requirements
 ------------
 
-This workflow requires that:
-
-1. The publisher is using the latest version of :ref:`setuptools`,
-2. The latest version of :ref:`twine` is used to upload the package,
-3. The user installing the package has at least Pip 9.0, or a client that supports the Metadata 1.2 specification.
+This workflow requires that the user installing the package has at least Pip 9.0, or a client that supports the Metadata 1.2 specification.
 
 Dealing with the universal wheels
 ---------------------------------
@@ -52,42 +46,50 @@ explicitly set ``universal`` to ``0``:
 Defining the Python version required
 ------------------------------------
 
-1. Download the newest version of Setuptools
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Ensure that before you generate source distributions or binary distributions, you update Setuptools and install twine.
+1. Install twine
+~~~~~~~~~~~~~~~~
 
+Ensure that you have twine available at its latest version.
 Steps:
 
 .. tab:: Unix/macOS
 
     .. code-block:: bash
 
-        python3 -m pip install --upgrade setuptools twine
+        python3 -m pip install --upgrade twine
 
 .. tab:: Windows
 
     .. code-block:: bat
 
-        py -m pip install --upgrade setuptools twine
-
-``setuptools`` version should be above 24.0.0.
+        py -m pip install --upgrade twine
 
 2. Specify the version ranges for supported Python distributions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-You can specify version ranges and exclusion rules, such as at least Python 3. Or, Python 2.7, 3.4 and beyond.
-
-Examples:
+You can specify version ranges and exclusion rules (complying with the :ref:`version-specifiers` specification),
+such as at least Python 3. Or, Python 2.7, 3.4 and beyond:
 
 .. code-block:: text
 
-    Requires-Python: ">=3"
-    Requires-Python: ">2.7,!=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*"
+    Requires-Python: ">= 3"
+    Requires-Python: ">= 2.7, != 3.0.*, != 3.1.*, != 3.2.*, != 3.3.*"
+
+
+The way to set those values is within your :file:`pyproject.toml`. The :ref:`requires-python` field of the
+``[project]`` table corresponds to the ``Requires-Python`` metadata field.
+
+.. code-block:: toml
 
-The way to set those values is within the call to ``setup`` within your
-:file:`setup.py` script. This will insert the ``Requires-Python``
-metadata values based on the argument you provide in ``python_requires``.
+   [build-system]
+   ...
+
+   [project]
+   requires-python = ">= 3.8" # At least Python 3.8
+
+
+For :ref:`setuptools` users, another way to achieve this is using the ``python_requires`` parameter
+in the call to ``setup`` within your :file:`setup.py` script.
 
 .. code-block:: python
 
@@ -96,43 +98,54 @@ metadata values based on the argument you provide in ``python_requires``.
 
     setup(
         # Your setup arguments
-        python_requires='>=2.7',  # Your supported Python ranges
+        python_requires='>= 3.8',
     )
 
+It is warned against adding upper bounds to the version ranges, e. g. ``">= 3.8 < 3.10"``. This can cause different errors
+and version conflicts. See the `discourse discussion`_ for more information.
+
 3. Validating the Metadata before publishing
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Within a Python source package (the zip or the tar-gz file you download) is a text file called PKG-INFO.
 
-This file is generated by :ref:`distutils` or :ref:`setuptools` when it generates the source package.
-The file contains a set of keys and values, the list of keys is part of the PyPa standard metadata format.
+This file is generated by the build backend when it generates the source package.
+The file contains a set of keys and values, the list of keys is part of the PyPA standard metadata format.
 
 You can see the contents of the generated file like this:
 
 .. code-block:: bash
 
-    tar xfO dist/my-package-1.0.0.tar.gz my-package-1.0.0/PKG-INFO
+    tar xf dist/my-package-1.0.0.tar.gz my-package-1.0.0/PKG-INFO -O
 
 Validate that the following is in place, before publishing the package:
 
 - If you have upgraded correctly, the Metadata-Version value should be 1.2 or higher.
-- The Requires-Python field is set and matches your specification in setup.py.
+- The ``Requires-Python`` field is set and matches your specification in the configuration file.
 
-4. Using Twine to publish
+4. Publishing the package
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Twine has a number of advantages, apart from being faster it is now the supported method for publishing packages.
+Proceed as suggested in :ref:`Uploading your Project to PyPI`.
 
-Make sure you are using the newest version of Twine, at least 1.9.
-
-Dropping a Python release
+Dropping a Python version
 -------------------------
 
-Once you have published a package with the Requires-Python metadata, you can then make a further update removing that Python runtime from support.
+In principle, at least metadata support for Python versions should be kept as long as possible, because
+once that has been dropped, people still depending on a version will be forced to downgrade.
+If however supporting a specific version becomes a blocker for a new feature or other issues occur, the metadata
+``Requires-Python`` should be amended. Of course this also depends on whether the project needs to be stable and
+well-covered for a wider range of users.
+
+Each version compatibility change should have an own release.
+
+For example, you published version 1.0.0 of your package with ``Requires-Python: ">= 2.7"`` metadata.
+
+If you then update the version string to ``">= 3.5"``, and publish a new version 2.0.0 of your package, any users running Pip 9.0+ from version 2.7 will have version 1.0.0 of the package installed, and any ``>= 3.5`` users will receive version 2.0.0.
 
-It must be done in this order for the automated fallback to work.
+It may be a good idea to create a minor release, stating that it is the last one compatible with the Python version to be removed, just before dropping that version.
 
-For example, you published the Requires-Python: ">=2.7" as version 1.0.0 of your package.
+When dropping a Python version, it might also be rewarding to upgrade the project's code syntax generally, apart from updating the versions used in visible places (like the testing environment). Tools like pyupgrade_ can simplify this task.
 
-If you were then to update the version string to ">=3.5", and publish a new version 2.0.0 of your package, any users running Pip 9.0+ from version 2.7 will
-have version 1.0.0 of the package installed, and any >=3.5 users will receive version 2.0.0.
+.. _discourse discussion: https://discuss.python.org/t/requires-python-upper-limits/12663
+.. _pyupgrade: https://pypi.org/project/pyupgrade/