Bug#823348: Limit the strongest dependencies on supplemental -doc packages

[Russ Allbery]

Control: tag -1 pending

Josh Triplett  writes:

> 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.

Thanks, applied for the next release.

-- 
Russ Allbery (r...@debian.org)   

Bug#823348: Limit the strongest dependencies on supplemental -doc packages

[Niels Thykier]

On Sun, 01 Jan 2017 23:06:17 -0800 Russ Allbery  wrote:
> [...]
> 
> > 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
> > 
> >  
> > 
> > + If package is a build tool, development tool,
> > + command-line tool, or library development package,
> > + package (or package-dev in the case of a
> > + library development package) already provides documentation in
> > + man, info, or plain text format, and package-doc
> > + provides HTML or other formats, package should declare
> > + at most a Suggests on package-doc. Otherwise,
> > + package should declare at most a Recommends on
> > + package-doc.
> > +   
> > +
> > +   
> >   Additional documentation included in the package should be
> >   installed under /usr/share/doc/package.
> >   If the documentation is packaged separately,
> 
> -- 
> Russ Allbery (r...@debian.org)   
> 
> 

Seconded. :)

Thanks,
~Niels





signature.asc
Description: OpenPGP digital signature

Bug#823348: Limit the strongest dependencies on supplemental -doc packages

[Russ Allbery]

Raphael Hertzog  writes:
> On Sat, 31 Dec 2016, Russ Allbery wrote:
>> Looks reasonable to me.  Seconded.

> Seconded.

Thanks!  IIRC, Josh isn't (yet) a DD, so this needs one more second.

> 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
>   
>  
>   
> +   If package is a build tool, development tool,
> +   command-line tool, or library development package,
> +   package (or package-dev in the case of a
> +   library development package) already provides documentation in
> +   man, info, or plain text format, and package-doc
> +   provides HTML or other formats, package should declare
> +   at most a Suggests on package-doc. Otherwise,
> +   package should declare at most a Recommends on
> +   package-doc.
> + 
> +
> + 
> Additional documentation included in the package should be
> installed under /usr/share/doc/package.
> If the documentation is packaged separately,

-- 
Russ Allbery (r...@debian.org)   

Bug#823348: Limit the strongest dependencies on supplemental -doc packages

[Raphael Hertzog]

On Sat, 31 Dec 2016, Russ Allbery wrote:
> Looks reasonable to me.  Seconded.

Seconded.

> 
> > 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
> > 
> >  
> > 
> > + If package is a build tool, development tool,
> > + command-line tool, or library development package,
> > + package (or package-dev in the case of a
> > + library development package) already provides documentation in
> > + man, info, or plain text format, and package-doc
> > + provides HTML or other formats, package should declare
> > + at most a Suggests on package-doc. Otherwise,
> > + package should declare at most a Recommends on
> > + package-doc.
> > +   
> > +
> > +   
> >   Additional documentation included in the package should be
> >   installed under /usr/share/doc/package.
> >   If the documentation is packaged separately,
> 
> -- 
> Russ Allbery (r...@debian.org)   
> 

-- 
Raphaël Hertzog ◈ Debian Developer

Support Debian LTS: http://www.freexian.com/services/debian-lts.html
Learn to master Debian: http://debian-handbook.info/get/


signature.asc
Description: PGP signature

Bug#823348: Limit the strongest dependencies on supplemental -doc packages

[Russ Allbery]

Josh Triplett  writes:

> 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.

[...]

Looks reasonable to me.  Seconded.

> 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
>   
>  
>   
> +   If package is a build tool, development tool,
> +   command-line tool, or library development package,
> +   package (or package-dev in the case of a
> +   library development package) already provides documentation in
> +   man, info, or plain text format, and package-doc
> +   provides HTML or other formats, package should declare
> +   at most a Suggests on package-doc. Otherwise,
> +   package should declare at most a Recommends on
> +   package-doc.
> + 
> +
> + 
> Additional documentation included in the package should be
> installed under /usr/share/doc/package.
> If the documentation is packaged separately,

-- 
Russ Allbery (r...@debian.org)   

Bug#823348: Limit the strongest dependencies on supplemental -doc packages

[Josh Triplett]

[Please CC me on replies, as I didn't receive this mail, and just
happened to see it in the archives.]

On Mon, 22 Aug 2016 13:38:42 +0100 George Bateman  
wrote:
> I'm currently making my first package, Processing. It's a GUI teaching
> tool for (usually Java) programming, with its own standard libraries
> for the code produced. It is currently split up into three packages:
> "processing" the GUI, "libprocessing3-java" the library, and
> "processing-doc" for documentation. It has the following dependency
> relationships:
> 
> processing –Depends→ libprocessing3-java
>–Depends→ processing-doc
> 
> libprocessing3-java –Sugggests→ processing-doc
> 
> This would violate the proposed policy change, but for very good
> reason because no educational program is very effective without some
> documentation.

Policy defines "Recommends" as "packages that would be found together
with this one in all but unusual installations."  That seems entirely
accurate here, and apt installs Recommends by default, so by default a
user who installed processing would get processing-doc.

Unless the processing GUI fails to run without its help files installed,
"Recommends" seems sufficient.  Does processing fail to start because it
expects the help files to exist, or crash/misbehave without the help
files present?

If not, "Recommends" seems appropriate.

> To resolve such issues, I would amend the last sentence of the patch to
> 
> + Otherwise,
> + package should declare at most a Recommends on
> + package-doc, unless package-doc is
> needed for the
> + practical use of package.

That doesn't seem like the right resolution to me.

Bug#823348: Limit the strongest dependencies on supplemental -doc packages

[George Bateman]

Dear Josh,

I'm currently making my first package, Processing. It's a GUI teaching
tool for (usually Java) programming, with its own standard libraries
for the code produced. It is currently split up into three packages:
"processing" the GUI, "libprocessing3-java" the library, and
"processing-doc" for documentation. It has the following dependency
relationships:

processing –Depends→ libprocessing3-java
   –Depends→ processing-doc

libprocessing3-java –Sugggests→ processing-doc

This would violate the proposed policy change, but for very good
reason because no educational program is very effective without some
documentation. Bundling processing-doc with processing would not
resolve the issue, as then libprocessing3-java has no documentation
package available. (And libprocessing3-java will be available as a
stand-alone package as Processing has a number of more experienced
users who prefer Eclipse to the beginners' GUI.)

To resolve such issues, I would amend the last sentence of the patch to

+ Otherwise,
+ package should declare at most a Recommends on
+ package-doc, unless package-doc is
needed for the
+ practical use of package.

Thank you,

George Bateman.

Bug#823348: Limit the strongest dependencies on supplemental -doc packages

[Josh Triplett]

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 
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
 	
 
 	
+	  If package is a build tool, development tool,
+	  command-line tool, or library development package,
+	  package (or package-dev in the case of a
+	  library development package) already provides documentation in
+	  man, info, or plain text format, and package-doc
+	  provides HTML or other formats, package should declare
+	  at most a Suggests on package-doc. Otherwise,
+	  package should declare at most a Recommends on
+	  package-doc.
+	
+
+	
 	  Additional documentation included in the package should be
 	  installed under /usr/share/doc/package.
 	  If the documentation is packaged separately,
-- 
2.8.1