Bug#906949: Clarify documentation location in a Python2-less distribution
Package: debian-policy
X-Debbugs-CC: debhelper-devel@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/ stuart@nanonanonano.net
Debian Developer http://www.debian.org/ stuart@debian.org
GPG fingerprint 90E2 D2C1 AD14 6A1B 7EBB 891D BBC1 7EBB 1396 F2F7
Reply to: