Package: debian-policy X-Debbugs-CC: debhelper-de...@lists.alioth.debian.org, debian-python@lists.debian.org
Hi! [ Promised follow up to the Python BoF at DebConf ] For historical reasons, Python 2 modules are packaged as python-foo while Python 3 modules are python3-foo. Documentation was originally only for Python 2 modules (but in any event is normally interpreter independent) and so is found in python-foo-doc packages. Policy §12.3 (from version 3.9.7) recommends that documentation from the python-foo-doc package be installed in /usr/share/doc/python-foo/ and not in /usr/share/doc/python-foo-doc/. From debhelper 10.8, dh_installdocs now does this automatically. In buster, documentation in python-foo-doc is slowly drifting over to /usr/share/doc/python-foo as packages are updated to compat 11. After the release of buster, we can expect to see Python 2 modules being dropped from the archive. Policy §12.3 and debhelper's interpretation of "main package" will suddenly cause documentation move from /usr/share/doc/python-foo to /usr/share/doc/python3-foo. This seems somewhat perverse for the user, will require changes to packaging (doc-base, rules, links) and perhaps code patches to packages that can display their own documentation. The BoF felt it made sense to adopt a standardised approach and to have this sorted prior to the buster release in case any tooling changes are required. This affects about 700 packages. We seek some input from the policy and debhelper people in defining what this approach should be. The following options exist: a) do nothing: allow all the documentation to drift slowly over to /usr/share/doc/python3-foo, probably releasing buster and bullseye with a bit of a mess of locations: /usr/share/doc/python-foo-doc, /usr/share/doc/python-foo, /usr/share/doc/python3-foo. This seems pretty bad for our users. b) keep using /usr/share/doc/python-foo: do we stick with /usr/share/doc/python-foo as a version-independent path even though no such package exists once the Python 2 package is gone? (I think there are currently no /usr/share/doc/ paths that don't match /usr/share/doc/$package) c) coordinated move: do we try to switch the "main package" to the Python 3 variant now so that all documentation moves over to /usr/share/doc/python3-foo? Churning d/control on 700 packages doesn't seem fun, so perhaps debhelper can assist? d) revert to /usr/share/doc/python-foo-doc: do we ignore policy's recommendation, overriding (or changing) dh_installdocs? While /usr/share/doc/main-package is only a recommendation in policy, 700 python-foo-doc packages deliberately ignoring it seems wrong. Thanks in advance for your suggestions! Stuart (on behalf of the Python BoF at DebConf18) -- Stuart Prescott http://www.nanonanonano.net/ stu...@nanonanonano.net Debian Developer http://www.debian.org/ stu...@debian.org GPG fingerprint 90E2 D2C1 AD14 6A1B 7EBB 891D BBC1 7EBB 1396 F2F7
