Debian Bug report logs - #495233
debian-policy: README.source content should be more detailed

version graph

Package: debian-policy; Maintainer for debian-policy is Debian Policy List <debian-policy@lists.debian.org>; Source for debian-policy is src:debian-policy.

Reported by: Lucas Nussbaum <lucas@lucas-nussbaum.net>

Date: Fri, 15 Aug 2008 14:30:05 UTC

Severity: wishlist

Merged with 562254

Found in versions debian-policy/3.8.0.1, debian-policy/3.8.3.0

Reply or subscribe to this bug.

Toggle useless messages

View this report as an mbox folder, status mbox, maintainer mbox


Report forwarded to debian-bugs-dist@lists.debian.org, zack@debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#495233; Package debian-policy. Full text and rfc822 format available.

Acknowledgement sent to Lucas Nussbaum <lucas@lucas-nussbaum.net>:
New Bug report received and forwarded. Copy sent to zack@debian.org, Debian Policy List <debian-policy@lists.debian.org>. Full text and rfc822 format available.

Message #5 received at submit@bugs.debian.org (full text, mbox):

From: Lucas Nussbaum <lucas@lucas-nussbaum.net>
To: submit@bugs.debian.org
Subject: debian-policy: README.source content should be more detailed
Date: Fri, 15 Aug 2008 11:22:51 -0300
Package: debian-policy
Version: 3.8.0.1

Hi,

I really like the idea of documenting special things about a source
package in debian/README.source. However, I think that section 4.14
could be improved a lot.

First, section 4.14 should list things that one does not need to
describe in debian/README.source. For example, the use of one of the
"standard" patch systems (quilt, dpatch, simple-patchsys) doesn't need
to be documented, since every NMUer should be able to work with them.
Another example is build systems: cdbs is used by >20% of our packages,
so I don't think that one need to document its use.

If you look at the packages currently providing a debian/README.source
(see gluck:~lucas/readme.source for a list), it seems that
debian/README.source is used as a way to generate a large number of
different howtos for patch systems. Having a common way to specify that
one should look at another file if looking for documentation about
something.

Also, it would be interesting to extend the use of debian/README.source
to other areas, such as:
- whether the maintainer encourages commits for other people directly to
  the package's VCS.
- the branch layout in the package's VCS.

Maybe we could have a machine-parseable format to specify those, too.
-- 
| Lucas Nussbaum
| lucas@lucas-nussbaum.net   http://www.lucas-nussbaum.net/ |
| jabber: lucas@nussbaum.fr             GPG: 1024D/023B3F4F |




Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#495233; Package debian-policy. Full text and rfc822 format available.

Acknowledgement sent to Giacomo Catenazzi <cate@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. Full text and rfc822 format available.

Message #10 received at 495233@bugs.debian.org (full text, mbox):

From: Giacomo Catenazzi <cate@debian.org>
To: Lucas Nussbaum <lucas@lucas-nussbaum.net>, 495233@bugs.debian.org
Subject: Re: Bug#495233: debian-policy: README.source content should be more detailed
Date: Fri, 15 Aug 2008 16:58:21 +0200
Lucas Nussbaum wrote:

> First, section 4.14 should list things that one does not need to
> describe in debian/README.source. For example, the use of one of the
> "standard" patch systems (quilt, dpatch, simple-patchsys) doesn't need
> to be documented, since every NMUer should be able to work with them.
> Another example is build systems: cdbs is used by >20% of our packages,
> so I don't think that one need to document its use.

I think the better way is do it similar to copyright: for
common patch/build system we should include only a link to
the relative document.
Maybe on a common package (build essential or dpkg-dev) or
on patch system package (but in this case we should push stronger
the maintainer to include the relevant informations).

BTW debian/README.source is not only for the MNUer, but also
for our users, so I prefer redundant documentation.


> Also, it would be interesting to extend the use of debian/README.source
> to other areas, such as:
> - whether the maintainer encourages commits for other people directly to
>   the package's VCS.
> - the branch layout in the package's VCS.

I agree with that.

PS: you should provide a patch!

ciao
   cate




Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#495233; Package debian-policy. Full text and rfc822 format available.

Acknowledgement sent to Russ Allbery <rra@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. Full text and rfc822 format available.

Message #15 received at 495233@bugs.debian.org (full text, mbox):

From: Russ Allbery <rra@debian.org>
To: Giacomo Catenazzi <cate@debian.org>
Cc: 495233@bugs.debian.org, Lucas Nussbaum <lucas@lucas-nussbaum.net>
Subject: Re: Bug#495233: debian-policy: README.source content should be more detailed
Date: Fri, 15 Aug 2008 11:01:08 -0700
Giacomo Catenazzi <cate@debian.org> writes:
> Lucas Nussbaum wrote:

>> First, section 4.14 should list things that one does not need to
>> describe in debian/README.source. For example, the use of one of the
>> "standard" patch systems (quilt, dpatch, simple-patchsys) doesn't need
>> to be documented, since every NMUer should be able to work with them.

I don't agree.  This was one of the things that came up specifically in
the original discussion that led to the README.source compromise.  If
nothing else, README.source tells people that yes, this is bog-standard
quilt or dpatch, so they don't have to figure out which it is and they
don't have to wonder whether there's something weird at work.

I would like this file to continue to contain pointers to the standard
documentation for quilt or dpatch if those patch systems are used.  We
allowed for a pointer specifically so that all you have to do is include a
line or two of reference.  For example, I use:

| This package uses quilt to manage all modifications to the upstream
| source.  Changes are stored in the source package as diffs in
| debian/patches and applied during the build.  Please see:
| 
|     /usr/share/doc/quilt/README.source
| 
| for more information on how to apply the patches, modify patches, or
| remove a patch.

quilt and dpatch could probably usefully recommend boilerplate text.

>> Another example is build systems: cdbs is used by >20% of our packages,
>> so I don't think that one need to document its use.

> I think the better way is do it similar to copyright: for common
> patch/build system we should include only a link to the relative
> document.  Maybe on a common package (build essential or dpkg-dev) or on
> patch system package (but in this case we should push stronger the
> maintainer to include the relevant informations).

Which is what Policy already says, and quilt, for example, provides such a
document for README.source to link to.  So I don't think Policy should be
changed here.

>> Also, it would be interesting to extend the use of debian/README.source
>> to other areas, such as:
>> - whether the maintainer encourages commits for other people directly to
>>   the package's VCS.
>> - the branch layout in the package's VCS.

There was some discussion of this on vcs-pkg, and I'm inclined to agree.
The one potential argument against doing this is that README.source was
intended to document the source package, and those aren't aspects of the
source package, but I think the benefit outweighs a division of topic here
and it's reasonable to put in this file anything that's relevant to
someone wanting to modify it.

-- 
Russ Allbery (rra@debian.org)               <http://www.eyrie.org/~eagle/>




Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#495233; Package debian-policy. Full text and rfc822 format available.

Acknowledgement sent to Lucas Nussbaum <lucas@lucas-nussbaum.net>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. Full text and rfc822 format available.

Message #20 received at 495233@bugs.debian.org (full text, mbox):

From: Lucas Nussbaum <lucas@lucas-nussbaum.net>
To: Russ Allbery <rra@debian.org>
Cc: Giacomo Catenazzi <cate@debian.org>, 495233@bugs.debian.org
Subject: Re: Bug#495233: debian-policy: README.source content should be more detailed
Date: Fri, 15 Aug 2008 15:17:44 -0300
On 15/08/08 at 11:01 -0700, Russ Allbery wrote:
> Giacomo Catenazzi <cate@debian.org> writes:
> > Lucas Nussbaum wrote:
> 
> >> First, section 4.14 should list things that one does not need to
> >> describe in debian/README.source. For example, the use of one of the
> >> "standard" patch systems (quilt, dpatch, simple-patchsys) doesn't need
> >> to be documented, since every NMUer should be able to work with them.
> 
> I don't agree.  This was one of the things that came up specifically in
> the original discussion that led to the README.source compromise.  If
> nothing else, README.source tells people that yes, this is bog-standard
> quilt or dpatch, so they don't have to figure out which it is and they
> don't have to wonder whether there's something weird at work.
> 
> I would like this file to continue to contain pointers to the standard
> documentation for quilt or dpatch if those patch systems are used.  We
> allowed for a pointer specifically so that all you have to do is include a
> line or two of reference.  For example, I use:
> 
> | This package uses quilt to manage all modifications to the upstream
> | source.  Changes are stored in the source package as diffs in
> | debian/patches and applied during the build.  Please see:
> | 
> |     /usr/share/doc/quilt/README.source
> | 
> | for more information on how to apply the patches, modify patches, or
> | remove a patch.
> 
> quilt and dpatch could probably usefully recommend boilerplate text.
> 
> >> Another example is build systems: cdbs is used by >20% of our packages,
> >> so I don't think that one need to document its use.
> 
> > I think the better way is do it similar to copyright: for common
> > patch/build system we should include only a link to the relative
> > document.  Maybe on a common package (build essential or dpkg-dev) or on
> > patch system package (but in this case we should push stronger the
> > maintainer to include the relevant informations).
> 
> Which is what Policy already says, and quilt, for example, provides such a
> document for README.source to link to.  So I don't think Policy should be
> changed here.

But that won't work if we want to include more info in README.source.

What about moving to a machine-parseable format, such as:

Patch-system: quilt
Patch-system-doc: /usr/share/doc/quilt/README.source
-- 
| Lucas Nussbaum
| lucas@lucas-nussbaum.net   http://www.lucas-nussbaum.net/ |
| jabber: lucas@nussbaum.fr             GPG: 1024D/023B3F4F |




Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#495233; Package debian-policy. Full text and rfc822 format available.

Acknowledgement sent to Russ Allbery <rra@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. Full text and rfc822 format available.

Message #25 received at 495233@bugs.debian.org (full text, mbox):

From: Russ Allbery <rra@debian.org>
To: Lucas Nussbaum <lucas@lucas-nussbaum.net>
Cc: Giacomo Catenazzi <cate@debian.org>, 495233@bugs.debian.org
Subject: Re: Bug#495233: debian-policy: README.source content should be more detailed
Date: Fri, 15 Aug 2008 16:35:12 -0700
Lucas Nussbaum <lucas@lucas-nussbaum.net> writes:
> On 15/08/08 at 11:01 -0700, Russ Allbery wrote:
>> Giacomo Catenazzi <cate@debian.org> writes:

>>> I think the better way is do it similar to copyright: for common
>>> patch/build system we should include only a link to the relative
>>> document.  Maybe on a common package (build essential or dpkg-dev) or
>>> on patch system package (but in this case we should push stronger the
>>> maintainer to include the relevant informations).

>> Which is what Policy already says, and quilt, for example, provides
>> such a document for README.source to link to.  So I don't think Policy
>> should be changed here.

> But that won't work if we want to include more info in README.source.

Why not?  I would think you could include whatever information you want
before or after the pointer to the standard quilt documentation.

> What about moving to a machine-parseable format, such as:
>
> Patch-system: quilt
> Patch-system-doc: /usr/share/doc/quilt/README.source

I think that's kind of pointless for human-readable, human-targetted
documention.  Why would machines need to parse README.source?

-- 
Russ Allbery (rra@debian.org)               <http://www.eyrie.org/~eagle/>




Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#495233; Package debian-policy. Full text and rfc822 format available.

Acknowledgement sent to Lucas Nussbaum <lucas@lucas-nussbaum.net>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. Full text and rfc822 format available.

Message #30 received at 495233@bugs.debian.org (full text, mbox):

From: Lucas Nussbaum <lucas@lucas-nussbaum.net>
To: Russ Allbery <rra@debian.org>
Cc: Giacomo Catenazzi <cate@debian.org>, 495233@bugs.debian.org
Subject: Re: Bug#495233: debian-policy: README.source content should be more detailed
Date: Sat, 16 Aug 2008 00:49:50 -0300
On 15/08/08 at 16:35 -0700, Russ Allbery wrote:
> Lucas Nussbaum <lucas@lucas-nussbaum.net> writes:
> > On 15/08/08 at 11:01 -0700, Russ Allbery wrote:
> >> Giacomo Catenazzi <cate@debian.org> writes:
> 
> >>> I think the better way is do it similar to copyright: for common
> >>> patch/build system we should include only a link to the relative
> >>> document.  Maybe on a common package (build essential or dpkg-dev) or
> >>> on patch system package (but in this case we should push stronger the
> >>> maintainer to include the relevant informations).
> 
> >> Which is what Policy already says, and quilt, for example, provides
> >> such a document for README.source to link to.  So I don't think Policy
> >> should be changed here.
> 
> > But that won't work if we want to include more info in README.source.
> 
> Why not?  I would think you could include whatever information you want
> before or after the pointer to the standard quilt documentation.

I thought you meant "link" as in "symlink".

> > What about moving to a machine-parseable format, such as:
> >
> > Patch-system: quilt
> > Patch-system-doc: /usr/share/doc/quilt/README.source
> 
> I think that's kind of pointless for human-readable, human-targetted
> documention.  Why would machines need to parse README.source?

Actually, I find it easier to read that than a 4-5 lines blurb that
contains exactly the same information.

Regarding programs parsing it, For example, apt-get source could display
a message about the patch system in use. Or debcheckout could make use
of the branch layout somehow.
-- 
| Lucas Nussbaum
| lucas@lucas-nussbaum.net   http://www.lucas-nussbaum.net/ |
| jabber: lucas@nussbaum.fr             GPG: 1024D/023B3F4F |




Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#495233; Package debian-policy. Full text and rfc822 format available.

Acknowledgement sent to Bill Allombert <Bill.Allombert@math.u-bordeaux1.fr>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. Full text and rfc822 format available.

Message #35 received at 495233@bugs.debian.org (full text, mbox):

From: Bill Allombert <Bill.Allombert@math.u-bordeaux1.fr>
To: Lucas Nussbaum <lucas@lucas-nussbaum.net>, 495233@bugs.debian.org
Cc: Russ Allbery <rra@debian.org>, Giacomo Catenazzi <cate@debian.org>
Subject: Re: Bug#495233: debian-policy: README.source content should be more detailed
Date: Tue, 19 Aug 2008 17:19:28 +0200
On Fri, Aug 15, 2008 at 03:17:44PM -0300, Lucas Nussbaum wrote:
> On 15/08/08 at 11:01 -0700, Russ Allbery wrote:
> > Giacomo Catenazzi <cate@debian.org> writes:
> > > Lucas Nussbaum wrote:
> > 
> > >> First, section 4.14 should list things that one does not need to
> > >> describe in debian/README.source. For example, the use of one of the
> > >> "standard" patch systems (quilt, dpatch, simple-patchsys) doesn't need
> > >> to be documented, since every NMUer should be able to work with them.
> > 
> > I don't agree.  This was one of the things that came up specifically in
> > the original discussion that led to the README.source compromise.  If
> > nothing else, README.source tells people that yes, this is bog-standard
> > quilt or dpatch, so they don't have to figure out which it is and they
> > don't have to wonder whether there's something weird at work.
> > 
> > I would like this file to continue to contain pointers to the standard
> > documentation for quilt or dpatch if those patch systems are used.  We
> > allowed for a pointer specifically so that all you have to do is include a
> > line or two of reference.  For example, I use:
> > 
> > | This package uses quilt to manage all modifications to the upstream
> > | source.  Changes are stored in the source package as diffs in
> > | debian/patches and applied during the build.  Please see:
> > | 
> > |     /usr/share/doc/quilt/README.source
> > | 
> > | for more information on how to apply the patches, modify patches, or
> > | remove a patch.
> > 
> > quilt and dpatch could probably usefully recommend boilerplate text.
> > 
> > >> Another example is build systems: cdbs is used by >20% of our packages,
> > >> so I don't think that one need to document its use.
> > 
> > > I think the better way is do it similar to copyright: for common
> > > patch/build system we should include only a link to the relative
> > > document.  Maybe on a common package (build essential or dpkg-dev) or on
> > > patch system package (but in this case we should push stronger the
> > > maintainer to include the relevant informations).
> > 
> > Which is what Policy already says, and quilt, for example, provides such a
> > document for README.source to link to.  So I don't think Policy should be
> > changed here.
> 
> But that won't work if we want to include more info in README.source.
> 
> What about moving to a machine-parseable format, such as:
> 
> Patch-system: quilt
> Patch-system-doc: /usr/share/doc/quilt/README.source

This does about the same as grepping the build-dep for quilt.

Cheers,
-- 
Bill. <ballombe@debian.org>

Imagine a large red swirl here. 




Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#495233; Package debian-policy. Full text and rfc822 format available.

Acknowledgement sent to Lucas Nussbaum <lucas@lucas-nussbaum.net>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. Full text and rfc822 format available.

Message #40 received at 495233@bugs.debian.org (full text, mbox):

From: Lucas Nussbaum <lucas@lucas-nussbaum.net>
To: Bill Allombert <Bill.Allombert@math.u-bordeaux1.fr>
Cc: 495233@bugs.debian.org, Russ Allbery <rra@debian.org>, Giacomo Catenazzi <cate@debian.org>
Subject: Re: Bug#495233: debian-policy: README.source content should be more detailed
Date: Tue, 19 Aug 2008 18:58:49 +0200
On 19/08/08 at 17:19 +0200, Bill Allombert wrote:
> On Fri, Aug 15, 2008 at 03:17:44PM -0300, Lucas Nussbaum wrote:
> > On 15/08/08 at 11:01 -0700, Russ Allbery wrote:
> > > Giacomo Catenazzi <cate@debian.org> writes:
> > > > Lucas Nussbaum wrote:
> > > 
> > > >> First, section 4.14 should list things that one does not need to
> > > >> describe in debian/README.source. For example, the use of one of the
> > > >> "standard" patch systems (quilt, dpatch, simple-patchsys) doesn't need
> > > >> to be documented, since every NMUer should be able to work with them.
> > > 
> > > I don't agree.  This was one of the things that came up specifically in
> > > the original discussion that led to the README.source compromise.  If
> > > nothing else, README.source tells people that yes, this is bog-standard
> > > quilt or dpatch, so they don't have to figure out which it is and they
> > > don't have to wonder whether there's something weird at work.
> > > 
> > > I would like this file to continue to contain pointers to the standard
> > > documentation for quilt or dpatch if those patch systems are used.  We
> > > allowed for a pointer specifically so that all you have to do is include a
> > > line or two of reference.  For example, I use:
> > > 
> > > | This package uses quilt to manage all modifications to the upstream
> > > | source.  Changes are stored in the source package as diffs in
> > > | debian/patches and applied during the build.  Please see:
> > > | 
> > > |     /usr/share/doc/quilt/README.source
> > > | 
> > > | for more information on how to apply the patches, modify patches, or
> > > | remove a patch.
> > > 
> > > quilt and dpatch could probably usefully recommend boilerplate text.
> > > 
> > > >> Another example is build systems: cdbs is used by >20% of our packages,
> > > >> so I don't think that one need to document its use.
> > > 
> > > > I think the better way is do it similar to copyright: for common
> > > > patch/build system we should include only a link to the relative
> > > > document.  Maybe on a common package (build essential or dpkg-dev) or on
> > > > patch system package (but in this case we should push stronger the
> > > > maintainer to include the relevant informations).
> > > 
> > > Which is what Policy already says, and quilt, for example, provides such a
> > > document for README.source to link to.  So I don't think Policy should be
> > > changed here.
> > 
> > But that won't work if we want to include more info in README.source.
> > 
> > What about moving to a machine-parseable format, such as:
> > 
> > Patch-system: quilt
> > Patch-system-doc: /usr/share/doc/quilt/README.source
> 
> This does about the same as grepping the build-dep for quilt.

No, a build-dependency such as gnome-pkg-tools or ruby-pkg-tools could
depend on quilt itself. For example, ruby-pkg-tools depends on cdbs, so
each package doesn't depend on cdbs directly.
-- 
| Lucas Nussbaum
| lucas@lucas-nussbaum.net   http://www.lucas-nussbaum.net/ |
| jabber: lucas@nussbaum.fr             GPG: 1024D/023B3F4F |




Severity set to `wishlist' from `normal' Request was from Manoj Srivastava <srivasta@golden-gryphon.com> to control@bugs.debian.org. (Thu, 25 Dec 2008 19:03:09 GMT) Full text and rfc822 format available.

Merged 495233 562254. Request was from Charles Plessy <plessy@debian.org> to control@bugs.debian.org. (Sun, 08 Jan 2012 14:00:39 GMT) Full text and rfc822 format available.

Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#495233; Package debian-policy. (Sun, 08 Jan 2012 14:30:03 GMT) Full text and rfc822 format available.

Acknowledgement sent to Charles Plessy <plessy@debian.org>:
Extra info received and forwarded to list. Copy sent to Debian Policy List <debian-policy@lists.debian.org>. (Sun, 08 Jan 2012 14:30:05 GMT) Full text and rfc822 format available.

Message #49 received at 495233@bugs.debian.org (full text, mbox):

From: Charles Plessy <plessy@debian.org>
To: 495233@bugs.debian.org
Subject: Re: Bug#495233: debian-policy: README.source content should be more detailed
Date: Sun, 8 Jan 2012 23:26:45 +0900
Le Fri, Aug 15, 2008 at 11:22:51AM -0300, Lucas Nussbaum a écrit :
> 
> First, section 4.14 should list things that one does not need to
> describe in debian/README.source. For example, the use of one of the
> "standard" patch systems (quilt, dpatch, simple-patchsys) doesn't need
> to be documented, since every NMUer should be able to work with them.
…
> Also, it would be interesting to extend the use of debian/README.source
> to other areas, such as:
> - whether the maintainer encourages commits for other people directly to
>   the package's VCS.
> - the branch layout in the package's VCS.

Dear all,

more than three years later, the 3.0 (quilt) source format has eroded the use
of patch systems.  The use of debian/README.source to document them has also
been questionned in http://bugs.debian.org/543417, but the less frequent they
become, the more the documentation becomes relevant.

Despite the following notion is still controversial, I think that little by
little, when packages are managed in a VCS, the preferred form for modification
is not the source package downloaded from our archive, but the VCS clone or
checkout itself.

I would therefore like to propose, in line with the original suggestion of
Lucas, to add a paragraph to §4.14 so that it explicitely mentions the
documentation of the VCS where the source package is developed.  This could be
something like the following. 

  When the source package is developped with a version control system and its
  repository is publicly available, README.source may document information not
  available elsewhere such as whether the maintainer encourages commits, if the
  branch layout is not usual.

With my experience limited to make standard packages in a team, I have no other
addition or change to suggest for §4.14.

Have a nice day,

-- 
Charles Plessy
Tsurumi, Kanagawa, Japan




Send a report that this bug log contains spam.


Debian bug tracking system administrator <owner@bugs.debian.org>. Last modified: Sun Apr 20 11:17:56 2014; Machine Name: beach.debian.org

Debian Bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.