Update Guide to 4eceed0

Signed-off-by: Michał Górny <mgorny@gentoo.org>

1 files changed, 166 insertions, 0 deletions

diff --git a/guide/_sources/package-maintenance.rst.txt b/guide/_sources/package-maintenance.rst.txt
index 512c477..4853fbe 100644
--- a/guide/_sources/package-maintenance.rst.txt
+++ b/guide/_sources/package-maintenance.rst.txt
@@ -79,3 +79,169 @@ e.g.::
 
 This does not apply to test dependencies — they are not strictly
 necessary to install a new Portage version.
+
+
+Monitoring new package versions
+===============================
+
+PyPI release feeds
+------------------
+The most efficient way to follow new Python package releases are
+the feeds found on PyPI_.  These can be found in the package's
+"Release history" tab, as "RSS feed".
+
+The Gentoo Python project maintains a comprehensive `list of PyPI feeds
+for packages`_ in ``dev-python/`` category (as well as other important
+packages maintained by the Python team) in OPML format.
+
+
+Checking via pip
+----------------
+The `pip list -\-outdated`_ command described in a followup section
+can also be used to verify installed packages against their latest PyPI
+releases.  However, this is naturally limited to packages installed
+on the particular system, and does not account for newer versions being
+already available in the Gentoo repository.
+
+
+Repology
+--------
+Repology_ provides a comprehensive service for tracking distribution
+package versions and upstream releases.  The easiest ways to find Python
+packages present in the Gentoo repository is to search by their
+maintainer's e-mail or category (e.g. ``dev-python``).  When searching
+by name, the majority of Python-specific package use ``python:`` prefix
+in their Repology names.
+
+Unfortunately, Repology is very susceptible to false positives.
+Examples of false positives include other distributions using custom
+version numbers, replacing packages with forks or simply Repology
+confusing different packages with the same name.  If you find false
+positives, please use the 'Report' option to request a correction.
+
+Please also note that Repology is unable to handle the less common
+version numbers that do not have a clear mapping to Gentoo version
+syntax (e.g. ``.post`` releases).
+
+
+Routine checks on installed Python packages
+===========================================
+The following actions are recommended to be run periodically on systems
+used to test Python packages.  They could be run e.g. via post-sync
+actions.
+
+
+pip check
+---------
+``pip check`` (provided by ``dev-python/pip``) can be used to check
+installed packages for missing dependencies and version conflicts:
+
+.. code-block:: text
+
+    $ python3.10 -m pip check
+    meson-python 0.6.0 requires ninja, which is not installed.
+    cx-freeze 6.11.1 requires patchelf, which is not installed.
+    openapi-spec-validator 0.4.0 has requirement openapi-schema-validator<0.3.0,>=0.2.0, but you have openapi-schema-validator 0.3.0.
+    cx-freeze 6.11.1 has requirement setuptools<=60.10.0,>=59.0.1, but you have setuptools 62.6.0.
+
+This tool checks the installed packages for a single Python
+implementation only, so you need to run it for every installed
+interpreter separately.
+
+In some cases the issues are caused by unnecessary version pins
+or upstream packages listing optional dependencies as obligatory.
+The preferred fix is to fix the package metadata rather than modifying
+the dependencies in ebuild.
+
+.. Warning::
+
+   pip does not support the ``Provides`` metadata, so it can
+   produce false positives about ``certifi`` dependency.  Please ignore
+   these:
+
+   .. code-block:: text
+
+       httpcore 0.15.0 requires certifi, which is not installed.
+       httpx 0.23.0 requires certifi, which is not installed.
+       sphobjinv 2.2.2 requires certifi, which is not installed.
+       requests 2.28.0 requires certifi, which is not installed.
+
+
+pip list -\-outdated
+--------------------
+``pip list --outdated`` (provided by ``dev-python/pip``) can be used
+to check whether installed packages are up-to-date.  This can help
+checking for pending version bumps, as well as to detect wrong versions
+in installed metadata:
+
+.. code-block:: text
+
+    $ pip3.11 list --outdated
+    Package                  Version           Latest  Type
+    ------------------------ ----------------- ------- -----
+    dirty-equals             0                 0.4     wheel
+    filetype                 1.0.10            1.0.13  wheel
+    mercurial                6.1.3             6.1.4   sdist
+    node-semver              0.8.0             0.8.1   wheel
+    PyQt-builder             1.12.2            1.13.0  wheel
+    PyQt5                    5.15.6            5.15.7  wheel
+    PyQt5-sip                12.10.1           12.11.0 sdist
+    PyQtWebEngine            5.15.5            5.15.6  wheel
+    Routes                   2.5.1.dev20220522 2.5.1   wheel
+    selenium                 3.141.0           4.3.0   wheel
+    sip                      6.6.1             6.6.2   wheel
+    sphinxcontrib-websupport 1.2.4.dev20220515 1.2.4   wheel
+    uri-template             0.0.0             1.2.0   wheel
+    watchfiles               0.0.0             0.15.0  wheel
+    watchgod                 0.0.dev0          0.8.2   wheel
+
+Again, the action applies to a single Python implementation only
+and needs to be repeated for all of them.
+
+Particularly note the packages with versions containing only zeroes
+in the above list — this is usually a sign that the build system
+does not recognize the version correctly.  In some cases, the only
+working solution would be to sed the correct version in.
+
+The additional ``dev`` suffix is usually appended via ``tag_build``
+option in ``setup.cfg``.  This causes the version to be considered
+older than the actual release, and therefore the respective options need
+to be stripped.
+
+
+gpy-verify-deps
+---------------
+``gpy-verify-deps`` (provided by ``app-portage/gpyutils``) compares
+the ebuild dependencies of all installed Python packages against their
+metadata.  It reports the dependencies that are potentially missing
+in ebuilds, as well as dependencies potentially missing
+``[${PYTHON_USEDEP}]``.  For the latter, it assumes that all
+dependencies listed in package metadata are used as Python modules.
+
+.. code-block:: text
+
+    $ gpy-verify-deps
+    [...]
+    =dev-python/tempest-31.0.0: missing dependency: dev-python/oslo-serialization [*]
+    =dev-python/tempest-31.0.0: missing dependency: dev-python/cryptography [*]
+    =dev-python/tempest-31.0.0: missing dependency: dev-python/stestr [*]
+    =dev-python/versioningit-2.0.0: missing dependency: dev-python/tomli [*]
+    =dev-python/versioningit-2.0.0: missing dependency: dev-python/importlib_metadata [python3.8 python3.9]
+    =dev-python/wstools-0.4.10-r1: missing dependency: dev-python/setuptools [*]
+
+The check is done for all installed interpreters.  The report indicates
+whether the dependency upstream is unconditional (``[*]``) or specific
+to a subset of Python implementations.
+
+Similarly to ``pip check`` results, every dependency needs to be
+verified.  In many cases, upstream metadata lists optional or build-time
+dependencies as runtime dependencies, and it is preferable to strip them
+than to copy the mistakes into the ebuild.
+
+
+.. _PyPI: https://pypi.org/
+
+.. _list of PyPI feeds for packages:
+   https://projects.gentoo.org/python/release-feeds.opml
+
+.. _Repology: https://repology.org/