Path: csiph.com!news.redatomik.org!aioe.org!bofh.it!news.nic.it!robomod
From: Stuart Prescott <stuart@debian.org>
Newsgroups: linux.debian.bugs.dist,linux.debian.maint.python,linux.debian.policy
Subject: Bug#906949: Clarify documentation location in a Python2-less distribution
Date: Wed, 22 Aug 2018 17:30:01 +0200
Message-ID: <wpDf3-Je-5@gated-at.bofh.it>
Old-Return-Path: <debbugs@buxtehude.debian.org>
Reply-To: Stuart Prescott <stuart@debian.org>, 906949@bugs.debian.org
Original-Sender: Stuart Prescott <stuart@nanonanonano.net>
Resent-To: debian-bugs-dist@lists.debian.org
Resent-Cc: debhelper-devel@lists.alioth.debian.org, debian-python@lists.debian.org, Debian Policy Editors <debian-policy@lists.debian.org>
Sender: robomod@news.nic.it
User-Agent: KMail/5.2.3 (Linux/4.9.0-7-amd64; KDE/5.28.0; x86_64; ; )
MIME-Version: 1.0
Content-Transfer-Encoding: quoted-printable
Content-Type: text/plain; charset="iso-8859-1"
Approved: robomod@news.nic.it
Lines: 82
Organization: linux.* mail to news gateway
Xref: csiph.com linux.debian.bugs.dist:914137 linux.debian.maint.python:10839 linux.debian.policy:6811

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 ]

=46or historical reasons, Python 2 modules are packaged as python-foo while=
=20
Python 3 modules are python3-foo. Documentation was originally only for=20
Python 2 modules (but in any event is normally interpreter independent) and=
=20
so is found in python-foo-doc packages.

Policy =A712.3 (from version 3.9.7) recommends that documentation from the=
=20
python-foo-doc package be installed in /usr/share/doc/python-foo/ and not i=
n=20
/usr/share/doc/python-foo-doc/. From debhelper 10.8, dh_installdocs now doe=
s=20
this automatically. In buster, documentation in python-foo-doc is slowly=20
drifting over to /usr/share/doc/python-foo as packages are updated to compa=
t=20
11.

After the release of buster, we can expect to see Python 2 modules being=20
dropped from the archive. Policy =A712.3 and debhelper's interpretation of=
=20
"main package" will suddenly cause documentation move from=20
/usr/share/doc/python-foo to /usr/share/doc/python3-foo. This seems somewha=
t=20
perverse for the user, will require changes to packaging (doc-base, rules,=
=20
links) and perhaps code patches to packages that can display their own=20
documentation.

The BoF felt it made sense to adopt a standardised approach and to have thi=
s=20
sorted prior to the buster release in case any tooling changes are required=
=2E=20
This affects about 700 packages.

We seek some input from the policy and debhelper people in defining what th=
is=20
approach should be. The following options exist:

a) do nothing: allow all the documentation to drift slowly over to=20
/usr/share/doc/python3-foo, probably releasing buster and bullseye with a b=
it=20
of a mess of locations: /usr/share/doc/python-foo-doc,=20
/usr/share/doc/python-foo, /usr/share/doc/python3-foo. This seems pretty ba=
d=20
for our users.

b) keep using /usr/share/doc/python-foo: do we stick with=20
/usr/share/doc/python-foo as a version-independent path even though no such=
=20
package exists once the Python 2 package is gone? (I think there are=20
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=
=20
variant now so that all documentation moves over to=20
/usr/share/doc/python3-foo? Churning d/control on 700 packages doesn't seem=
=20
fun, so perhaps debhelper can assist?

d) revert to /usr/share/doc/python-foo-doc: do we ignore policy's=20
recommendation, overriding (or changing) dh_installdocs? While=20
/usr/share/doc/main-package is only a recommendation in policy, 700=20
python-foo-doc packages deliberately ignoring it seems wrong.

Thanks in advance for your suggestions!

Stuart
(on behalf of the Python BoF at DebConf18)

=2D-=20
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