Documentation packages and explicit Requires

[Michael Schwendt]

After many years, there still is the occasional packager, who adds
an explicit "Requires: %{name} = %{version}-%{release}" to a noarch -doc
subpackage which contains files one can display with any suitable program
(such as PDF, HTML or TXT files).

I don't know why they do it. The "Requiring Base Package" guidelines
leave enough freedom to not do it and even mention -libs subpackages as one
example where the base dep is not "needed":
https://fedoraproject.org/wiki/Packaging:Guidelines#Requiring_Base_Package

What do other packagers think about this?

Can we please get rid of such bloat in plain Documentation packages?
These dependencies pull in lots of stuff even if one only wants to peruse
the documentation (e.g. when taking a brief look at an API or what an
application can do).

[Mat Booth]

On 23 July 2015 at 12:52, Michael Schwendt <mschwendt(a)gmail.com&gt; wrote:

>  After many years, there still is the occasional packager, who adds
>  an explicit "Requires: %{name} = %{version}-%{release}" to a noarch -doc
>  subpackage which contains files one can display with any suitable program
>  (such as PDF, HTML or TXT files).
>
>  I don't know why they do it. The "Requiring Base Package" guidelines
>  leave enough freedom to not do it and even mention -libs subpackages as one
>  example where the base dep is not "needed":
>  https://fedoraproject.org/wiki/Packaging:Guidelines#Requiring_Base_Package
>
>  What do other packagers think about this?
>
>  Can we please get rid of such bloat in plain Documentation packages?
>  These dependencies pull in lots of stuff even if one only wants to peruse
>  the documentation (e.g. when taking a brief look at an API or what an
>  application can do).
>  --
>  packaging mailing list
>  packaging(a)lists.fedoraproject.org
>  https://admin.fedoraproject.org/mailman/listinfo/packaging 

Totally agree. I seem to recall we removed the requirement for javadoc
packages a long time ago. The cases that still remain where a javadoc
package still requires its base package are likely to be low maintainance
packages that never need touching.

-- 
Mat Booth
http://fedoraproject.org/get-fedora

[Ville Skyttä]

On Thu, Jul 23, 2015 at 11:03 PM, Mat Booth <mat(a)matbooth.co.uk&gt; wrote:
>  On 23 July 2015 at 12:52, Michael Schwendt
> <mschwendt(a)gmail.com&gt; wrote:
> >
> > Can we please get rid of such bloat in plain Documentation packages?
> > These dependencies pull in lots of stuff even if one only wants to peruse
> > the documentation (e.g. when taking a brief look at an API or what an
> > application can do).
>
>  Totally agree. 
Me too.

And while on the subject of documentation packages but unrelated to
the deps issue, standardizing naming on -doc would be nice, the former
is more common and used by other distros.

[Christopher Meng]

On Thu, Jul 23, 2015 at 7:52 AM, Michael Schwendt <mschwendt(a)gmail.com&gt; wrote:
>  After many years, there still is the occasional packager, who adds
>  an explicit "Requires: %{name} = %{version}-%{release}" to a noarch -doc
>  subpackage which contains files one can display with any suitable program
>  (such as PDF, HTML or TXT files).
>
>  I don't know why they do it. The "Requiring Base Package" guidelines
>  leave enough freedom to not do it and even mention -libs subpackages as one
>  example where the base dep is not "needed":
>  https://fedoraproject.org/wiki/Packaging:Guidelines#Requiring_Base_Package
>
>  What do other packagers think about this?
>
>  Can we please get rid of such bloat in plain Documentation packages?
>  These dependencies pull in lots of stuff even if one only wants to peruse
>  the documentation (e.g. when taking a brief look at an API or what an
>  application can do). 
Agree +1

As I've seen how people fiddle with that, doc packaging has been a
mess. Someone name -doc package to -docs, and someone build them as
arch-dependant packages.

-doc subpkg shouldn't require main pkg, just as Mat said above, it's
really irritating to view docs while pulling in lots of dependencies.
Some doc package are really large, and base pkg it pulls is even
larger.

[Jason L Tibbitts III]

> >>>> "VS" == Ville Skyttä
> <ville.skytta(a)iki.fi&gt; writes: 
VS> And while on the subject of documentation packages but unrelated to
VS> the deps issue, standardizing naming on -doc would be nice, the
VS> former is more common and used by other distros.

http://fedoraproject.org/wiki/Packaging:Guidelines#Documentation

"
Or if there's a lot of documentation, consider putting it into a
subpackage. In this case, it is recommended to use *-doc as the
subpackage name.
"

That could be strengthened, I suppose, though I imagine if someone
ignores the recommendation now they'd probably ignore the requirement in
the future.

It would also be easy to make rpmlint or fedora-review (or both)
complain about it.

 - J<

[Richard Fearn]

>  After many years, there still is the occasional packager, who adds
>  an explicit "Requires: %{name} = %{version}-%{release}" to a noarch -doc
>  subpackage which contains files one can display with any suitable program
>  (such as PDF, HTML or TXT files). 
Thanks for your email Michael - I just checked my packages and found a
few -javadoc packages that unnecessarily depend on the base package.

Regards,

Richard

-- 
Richard Fearn
richardfearn(a)gmail.com

[Richard Fearn]

>  And while on the subject of documentation packages but unrelated to
>  the deps issue, standardizing naming on -doc would be nice, the former
>  is more common and used by other distros. 
Do you think that should apply to javadoc packages too? At the moment,
the Java packaging guidelines say:

  "Java API documentation MUST be placed into a sub-package called
%{name}-javadoc."

which is much stronger than the general recommendation that
documentation should go into a -doc package.

Regards,

Richard

-- 
Richard Fearn
richardfearn(a)gmail.com

[Remi Collet]

Le 23/07/2015 13:52, Michael Schwendt a écrit :
>  After many years, there still is the occasional packager, who adds
>  an explicit "Requires: %{name} = %{version}-%{release}" to a noarch -doc
>  subpackage which contains files one can display with any suitable program
>  (such as PDF, HTML or TXT files).
>  
>  I don't know why they do it. The "Requiring Base Package" guidelines
>  leave enough freedom to not do it and even mention -libs subpackages as one
>  example where the base dep is not "needed":
>  https://fedoraproject.org/wiki/Packaging:Guidelines#Requiring_Base_Package
>  
>  What do other packagers think about this? 
Requiring Base package is not mandatory,
but providing the License in all case is mandatory.

So requiring the base package can solves this (and avoid having to
duplicate the LICENSE file in both packages).

It also ensure the documentation fit the installed base package
else you can have foo 1.2 and foo-doc 2.3

Remi.

>  
>  Can we please get rid of such bloat in plain Documentation packages?
>  These dependencies pull in lots of stuff even if one only wants to peruse
>  the documentation (e.g. when taking a brief look at an API or what an
>  application can do).
>  --
>  packaging mailing list
>  packaging(a)lists.fedoraproject.org
>  https://admin.fedoraproject.org/mailman/listinfo/packaging
>

[Ville Skyttä]

On Sat, Jul 25, 2015 at 1:50 PM, Richard Fearn <richardfearn(a)gmail.com&gt; wrote:
> > And while on the subject of documentation packages but unrelated
> to
> > the deps issue, standardizing naming on -doc would be nice, the former
> > is more common and used by other distros.
>
>  Do you think that should apply to javadoc packages too? 
No strong opinions. On the other hand they're a bit different than the
average documentation package but then again I suppose for other
languages API docs go to -doc, and I don't know why Java should be any
different.

[Remi Collet]

Le 25/07/2015 14:04, Remi Collet a écrit :

>  It also ensure the documentation fit the installed base package
>  else you can have foo 1.2 and foo-doc 2.3 
It seems rpm 4.13 will allow

    Requires: (%{name} = %{version}-%{release} IF %{name})

:)

Remi.

[Michael Schwendt]

On Sat, 25 Jul 2015 14:04:30 +0200, Remi Collet wrote:

>  Requiring Base package is not mandatory,
>  but providing the License in all case is mandatory.
>  
>  So requiring the base package can solves this (and avoid having to
>  duplicate the LICENSE file in both packages). 
That's neglectable for -doc subpackages, which are split off because
of their size. A single small license file doesn't make a big different
then.

>  It also ensure the documentation fit the installed base package
>  else you can have foo 1.2 and foo-doc 2.3 
Why would that be a problem?

The documentation does not "need" the base package at install-time
and not at run-time either.

A strict dependency would even make it impossible to install the
documentation without updating the installation.

Btw, lots of dependencies in the Fedora package collection are not
versioned anyway, so on non-updated installations, there can be various
version mismatches (such as unsafe inter-dependencies based on automatic
soname deps without symbol versioning -- one reason why some maintainers
would like strictly versioned inter-dependencies everywhere). Adding them
to -doc subpackages is the wrong place where to start.

[Nico Kadel-Garcia]

On Thu, Jul 23, 2015 at 7:52 AM, Michael Schwendt <mschwendt(a)gmail.com&gt; wrote:
>  After many years, there still is the occasional packager, who adds
>  an explicit "Requires: %{name} = %{version}-%{release}" to a noarch -doc
>  subpackage which contains files one can display with any suitable program
>  (such as PDF, HTML or TXT files).
>
>  I don't know why they do it. The "Requiring Base Package" guidelines
>  leave enough freedom to not do it and even mention -libs subpackages as one
>  example where the base dep is not "needed":
>  https://fedoraproject.org/wiki/Packaging:Guidelines#Requiring_Base_Package
>
>  What do other packagers think about this? 
Depends on the software. Documentation in
/usr/share/doc/[name]-docs-[version] should not be a problem. But as a
theoretical example, having having tomcat6 and tomcat7 both use
/ur/share/tomcat-docs would get nasty, and dangerous. So it does
require a bit of thought as to whether multiple versions of the same
component could have multiple versions of documentation installed,
safely, in parallel.