Package: debian-policy Severity: normal Tags: patch Based on a thread on debian-devel about Recommends, I'd like to propose the attached change to policy, which limits the strongest dependency a package should declare on its supplemental -doc package.
This mostly documents existing practice. Packages don't tend to declare Depends on their -doc packages at all. Packages primarily used for development don't tend to declare Recommends on their -doc packages to avoid installing them by default on the systems of developers who just want the package installed to support development of some other package. Likewise, command-line tools that already provide a manpage or a text manual don't tend to declare Recommends on a -doc package providing an HTML manual for that tool. The phrasing of "at most" avoids mandating any minimum dependency relationship, leaving it up to the maintainer's discretion how much the prospective user of a package will want the corresponding -doc package. - Josh Triplett -- System Information: Debian Release: stretch/sid APT prefers unstable APT policy: (500, 'unstable'), (1, 'experimental') Architecture: amd64 (x86_64) Kernel: Linux 4.5.0-1-amd64 (SMP w/4 CPU cores) Locale: LANG=C.UTF-8, LC_CTYPE=C.UTF-8 (charmap=UTF-8) Shell: /bin/sh linked to /bin/dash Init: systemd (via /run/systemd/system)
>From ce0c8de0bf9ad36b7f5c95da25daa16db55fb259 Mon Sep 17 00:00:00 2001 From: Josh Triplett <j...@joshtriplett.org> Date: Tue, 3 May 2016 12:50:54 -0700 Subject: [PATCH] Limit the strongest dependencies on supplemental -doc packages This mostly documents existing practice. Packages don't tend to declare Depends on their -doc packages at all. Packages primarily used for development don't tend to declare Recommends on their -doc packages to avoid installing them by default on the systems of developers who just want the package installed to support development of some other package. Likewise, command-line tools that already provide a manpage or a text manual tend to avoid a Recommends on a -doc package providing an HTML manual for that tool. The phrasing of "at most" avoids mandating any minimum dependency relationship, leaving it up to the maintainer's discretion how much the prospective user of a package will want the corresponding -doc package. --- policy.sgml | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/policy.sgml b/policy.sgml index 404dc73..421e0d1 100644 --- a/policy.sgml +++ b/policy.sgml @@ -10699,6 +10699,18 @@ END-INFO-DIR-ENTRY </p> <p> + If <var>package</var> is a build tool, development tool, + command-line tool, or library development package, + <var>package</var> (or <var>package</var>-dev in the case of a + library development package) already provides documentation in + man, info, or plain text format, and <var>package</var>-doc + provides HTML or other formats, <var>package</var> should declare + at most a <tt>Suggests</tt> on <var>package</var>-doc. Otherwise, + <var>package</var> should declare at most a <tt>Recommends</tt> on + <var>package</var>-doc. + </p> + + <p> Additional documentation included in the package should be installed under <file>/usr/share/doc/<var>package</var></file>. If the documentation is packaged separately, -- 2.8.1
