Add discussion "Is setup.py deprecated?"

source/discussions/index.rst

@@ -13,3 +13,4 @@ specific topic. If you're just trying to get stuff done, see
    install-requires-vs-requirements
    wheel-vs-egg
    src-layout-vs-flat-layout
+   setup-py-deprecated

source/discussions/setup-py-deprecated.rst

@@ -0,0 +1,114 @@
+===========================
+Is ``setup.py`` deprecated?
+===========================
+
+No, :term:`setup.py` is not deprecated,
+it is a valid configuration file for :ref:`setuptools`
+that happens to be written in Python, instead of in *TOML* for example
+(a similar practice is used by other tools
+like *nox* and its ``nox.py`` configuration file,
+or *pytest* and ``conftest.py``).
+
+It is however deprecated to run ``python setup.py`` as a command line tool.
+
+This means for example that the following commands **MUST NOT** be run anymore:
+
+* ``python setup.py install``
+* ``python setup.py develop``
+* ``python setup.py sdist``
+* ``python setup.py bdist_wheel``
+
+
+What commands should be used instead?
+=====================================
+
+In short:
+
++---------------------------------+----------------------------------------+
+| Deprecated                      | Current recommendation                 |
++=================================+========================================+
+| ``python setup.py install``     | ``python -m pip install .``            |
++---------------------------------+----------------------------------------+
+| ``python setup.py develop``     | ``python -m pip install --editable .`` |
++---------------------------------+----------------------------------------+
+| ``python setup.py sdist``       | ``python -m build`` [#needs-build]_    |
++---------------------------------+                                        |
+| ``python setup.py bdist_wheel`` |                                        |
++---------------------------------+----------------------------------------+
+
+
+.. [#needs-build] This requires the :ref:`build` dependency.
+    It is recommended to always build and publish both the source distribution
+    and wheel of a project, which is what ``python -m build`` does.
+    If necessary the ``--sdist`` and ``--wheel`` options can be used
+    to generate only one or the other.
+
+
+In order to install a setuptools based project,
+it was common to run ``setup.py``'s ``install`` command such as:
+``python setup.py install``.
+
+Nowadays the recommended method is to use :ref:`pip` directly
+with a command like this one: ``python -m pip install .``.
+Where the dot ``.`` is actually a file system path,
+it is the path notation for the current directory.
+Indeed *pip* accepts a path to
+a project's source tree directory on the local filesystem
+as argument to its ``install`` sub-command.
+So the this would be also a valid command:
+``python -m pip install path/to/project``.
+
+As for the installation in *develop* mode aka *editable* mode,
+instead of ``python setup.py develop``
+one can use the ``--editable`` option of pip's *install* sub-command:
+``python -m pip install --editable .``.
+
+One recommended, simple, and straightforward method of building
+:term:`source distributions <Source Distribution (or "sdist")>`
+and :term:`wheels <Wheel>`
+is to use the :ref:`build` tool with a command like
+``python -m build``
+which triggers the generation of both distribution formats.
+If necessary the ``--sdist`` and ``--wheel`` options can be used
+to generate only one or the other.
+Note that the build tool needs to be installed separately.
+
+
+Should ``setup.py`` be deleted?
+===============================
+
+Although the usage of ``setup.py`` as an executable script is deprecated,
+its usage as a configuration file for setuptools is absolutely fine.
+There is likely no modification needed in ``setup.py``.
+
+.. todo::
+
+    Link to a (still to be written) page about "modernizing a setup.py project"
+
+
+Is the ``pyproject.toml`` file mandatory?
+=========================================
+
+No, it is not necessary for a project to have a ``pyproject.toml`` file.
+The standard fallback behavior for a :term:`build frontend <Build Frontend>`
+in absence of a ``pyproject.toml`` file and its ``[build-system]`` table
+is to assume that the :term:`build backend <Build Backend>` is setuptools.
+
+There are certain advantages to have a ``pyproject.toml`` file
+with a standard ``[build-system]`` table
+at the root of a project source tree directory tree, though.
+
+
+Why? What does it all mean?
+===========================
+
+One way to look at it is that setuptools' scope
+has now been reduced to the role of a build backend.
+
+
+Where to read more about this?
+==============================
+
+* https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html
+
+* https://setuptools.pypa.io/en/latest/deprecated/commands.html