diff options
Diffstat (limited to 'guide/_sources/package-maintenance.rst.txt')
| -rw-r--r-- | guide/_sources/package-maintenance.rst.txt | 166 |
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/ |