Should {NEWS, CHANGELOG, README, etc} go into main package or -doc subpackage?

[Vít Ondruch]

Hi,

Can somebody clarify where should go the files mentioned in $SUBJECT if 
the package provides a -doc subpackage? It is obvious that the LICENSE 
file must go into the main package, but what about the others? There are 
packages, which has the $SUBJECT files in main package, but I think they 
should go into -doc subpackage. What else wold be the -doc subpackage 
purpose then?

BTW it would be nice if the guidelines could be clarified regarding this 
issue.

Thank you



Vit

[Michael Schwendt]

On Mon, 10 Sep 2012 15:46:18 +0200, Vít Ondruch wrote:

>  Hi,
>  
>  Can somebody clarify where should go the files mentioned in $SUBJECT if 
>  the package provides a -doc subpackage? It is obvious that the LICENSE 
>  file must go into the main package, but what about the others? There are 
>  packages, which has the $SUBJECT files in main package, but I think they 
>  should go into -doc subpackage. What else wold be the -doc subpackage 
>  purpose then?
>  
>  BTW it would be nice if the guidelines could be clarified regarding this 
>  issue. 
A -doc subpackage is justified to split off _huge_ documentation in order
to reduce the size of an installation, spin, or -devel pkg depchain.
The purpose of -doc packages is not to strip off all documentation of
packages.

Small doc files, such as those you mention (also NEWS, AUTHORS), may be nice
to have available always together with the software - whereas large books or
generated API HTML trees for developers may be considered more optional.

-- 
Fedora release 18 (Spherical Cow) - Linux 3.6.0-0.rc4.git2.1.fc18.x86_64
loadavg: 0.55 0.18 0.10

[Rex Dieter]

On 09/10/2012 08:46 AM, Vít Ondruch wrote:
>  Hi,
>
>  Can somebody clarify where should go the files mentioned in $SUBJECT if
>  the package provides a -doc subpackage? It is obvious that the LICENSE
>  file must go into the main package, but what about the others? There are
>  packages, which has the $SUBJECT files in main package, but I think they
>  should go into -doc subpackage. What else wold be the -doc subpackage
>  purpose then?
>
>  BTW it would be nice if the guidelines could be clarified regarding this
>  issue. 
true the existing basic guideline:
https://fedoraproject.org/wiki/Packaging/Guidelines#Documentation

doesn't explicitly cover that case.  I'd tend to defer this to the 
packagers' best judgment.

My own personal opinion is that README (and the others mentioned to a 
lesser degree) are generally essential so should be included in the main 
package (unless -doc is not optional, ie, is pulled in by main package 
dependencies)

-- rex

[Vít Ondruch]

Dne 10.9.2012 16:04, Michael Schwendt napsal(a):
>  On Mon, 10 Sep 2012 15:46:18 +0200, Vít Ondruch wrote:
>
> > Hi,
> >
> > Can somebody clarify where should go the files mentioned in $SUBJECT if
> > the package provides a -doc subpackage? It is obvious that the LICENSE
> > file must go into the main package, but what about the others? There are
> > packages, which has the $SUBJECT files in main package, but I think they
> > should go into -doc subpackage. What else wold be the -doc subpackage
> > purpose then?
> >
> > BTW it would be nice if the guidelines could be clarified regarding this
> > issue.
>  A -doc subpackage is justified to split off _huge_ documentation in order
>  to reduce the size of an installation, spin, or -devel pkg depchain.
>  The purpose of -doc packages is not to strip off all documentation of
>  packages.
>
>  Small doc files, such as those you mention (also NEWS, AUTHORS), may be nice
>  to have available always together with the software - whereas large books or
>  generated API HTML trees for developers may be considered more optional.
>  
Nicely put, this should definitely go into guidelines.

Vit

[Fernando Nasser]

+1

----- Original Message -----
From: "Rex Dieter" <rdieter(a)math.unl.edu&gt;
To: packaging(a)lists.fedoraproject.org
Sent: Monday, September 10, 2012 10:10:23 AM
Subject: Re: [Fedora-packaging] Should {NEWS, CHANGELOG, README, etc} go into main package
or -doc subpackage?

On 09/10/2012 08:46 AM, Vít Ondruch wrote:
>  Hi,
>
>  Can somebody clarify where should go the files mentioned in $SUBJECT if
>  the package provides a -doc subpackage? It is obvious that the LICENSE
>  file must go into the main package, but what about the others? There are
>  packages, which has the $SUBJECT files in main package, but I think they
>  should go into -doc subpackage. What else wold be the -doc subpackage
>  purpose then?
>
>  BTW it would be nice if the guidelines could be clarified regarding this
>  issue. 
true the existing basic guideline:
https://fedoraproject.org/wiki/Packaging/Guidelines#Documentation

doesn't explicitly cover that case.  I'd tend to defer this to the 
packagers' best judgment.

My own personal opinion is that README (and the others mentioned to a 
lesser degree) are generally essential so should be included in the main 
package (unless -doc is not optional, ie, is pulled in by main package 
dependencies)

-- rex
--
packaging mailing list
packaging(a)lists.fedoraproject.org
https://admin.fedoraproject.org/mailman/listinfo/packaging

[Stanislav Ochotnicky]

Quoting Vít Ondruch (2012-09-10 15:46:18)
>  Hi,
>  
>  It is obvious that the LICENSE file must go into the main package, but
>  what about the others?  
Just a reminder that current guidelines require LICENSE files to be
placed in all independent subpackages (i.e. if a subpackage doesn't
require main package LICENSE has to be included there as well)

-- 
Stanislav Ochotnicky <sochotnicky(a)redhat.com&gt;
Software Engineer - Base Operating Systems Brno

PGP: 7B087241
Red Hat Inc.                               http://cz.redhat.com