Trac #31321: build/pkgs: Add some missing install-requires metadata, …

…add some documentation to the developer's guide

Dmitry Marakasov (repology.org) points out that some metadata are
missing in our `build/pkgs/`.
https://github.com/repology/repology-
updater/issues/1118#issuecomment-771102608

We fix this so that the SageMath distribution can be listed as a
repository on repology.org

URL: https://trac.sagemath.org/31321
Reported by: mkoeppe
Ticket author(s): Matthias Koeppe
Reviewer(s): Dima Pasechnik

build/pkgs/texttable/install-requires.txt

@@ -0,0 +1 @@
+texttable >=1.6.3

build/pkgs/wheel/install-requires.txt

@@ -0,0 +1,2 @@
+# https://trac.sagemath.org/ticket/31050 - version constraint for macOS Big Sur support
+wheel >=0.36.2

src/doc/en/developer/packaging.rst

@@ -545,9 +545,58 @@ Where ``sdh_pip_install`` is a function provided by ``sage-dist-helpers`` that
 points to the correct ``pip`` for the Python used by Sage, and includes some
 default flags needed for correct installation into Sage.
 
-If pip will not work, you may use ``sdh_setup_bdist_wheel``, followed by
+If pip will not work but a command like ``python3 setup.py install``
+will, you may use ``sdh_setup_bdist_wheel``, followed by
 ``sdh_store_and_pip_install_wheel .``.
 
+For ``spkg-check.in`` script templates, make sure to call
+``sage-python23`` rather than ``python``. This will ensure that the
+correct version of Python is used to check the package.
+The same holds for ; for example, the ``scipy`` ``spkg-check.in``
+file contains the line
+
+.. CODE-BLOCK:: bash
+
+    exec sage-python23 spkg-check.py
+
+All normal Python packages must have a file ``install-requires.txt``.
+If a Python package is available on PyPI, this file must contain the
+name of the package as it is known to PyPI.  Optionally,
+``install-requires.txt`` can encode version constraints (such as lower
+and upper bounds).  The constraints are in the format of the
+``install_requires`` key of `setup.cfg
+<https://setuptools.readthedocs.io/en/latest/userguide/declarative_config.html>`_
+or `setup.py
+<https://packaging.python.org/discussions/install-requires-vs-requirements/#id5>`_.
+
+The files may include comments (starting with ``#``) that explain why a particular lower
+bound is warranted or why we wish to include or reject certain versions.
+
+For example:
+
+.. CODE-BLOCK:: bash
+
+    $ cat build/pkgs/sphinx/package-version.txt
+    3.1.2.p0
+    $ cat build/pkgs/sphinx/install-requires.txt
+    # gentoo uses 3.2.1
+    sphinx >=3, <3.3
+
+The comments may include links to Trac tickets, as in the following example:
+
+.. CODE-BLOCK:: bash
+
+    $ cat build/pkgs/packaging/install-requires.txt
+    packaging >=18.0
+    # Trac #30975: packaging 20.5 is known to work but we have to silence "DeprecationWarning: Creating a LegacyVersion"
+
+The currently encoded version constraints are merely a starting point.
+Developers and downstream packagers are invited to refine the version
+constraints based on their experience and tests.  When a package
+update is made in order to pick up a critical bug fix from a newer
+version, then the lower bound should be adjusted.
+
+
 .. _section-spkg-SPKG-txt:
 
 The SPKG.rst or SPKG.txt File