Debian Bug report logs - #250202
[PROPOSAL] "debian/README.source" file for packages with non-trivial source

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: wouter@debian.org

Date: Fri, 21 May 2004 09:33:06 UTC

Severity: wishlist

Fixed in version debian-policy/3.8.0.0

Done: Russ Allbery <rra@debian.org>

Bug is archived. No further changes may be made.

Toggle useless messages

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


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

Acknowledgement sent to Wouter Verhelst <wouter@grep.be>:
New Bug report received and forwarded. Copy sent to 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: Wouter Verhelst <wouter@grep.be>
To: submit@bugs.debian.org
Subject: mandate a common name for "patched source" and/or "unpacked source"
Date: Fri, 21 May 2004 11:27:27 +0200
[Message part 1 (text/plain, inline)]
Package: debian-policy
Severity: wishlist

OK, I'm sick of this.

There are a number of dbs-style packages out there, that don't give you
the source if you say "dpkg-source -x .dsc"; instead, they give you a
directory with a source tarball and a bunch of patches. While this is
probably a good idea to make maintaining said packages easier, the fact
that they all have different debian/rules targets for unpacking sucks
majorly; if you want to apply a small local patch, you have three
options to find out what the right targets are:
* Guess (which is hardly successful, IME)
* Call one of the more common debian/rules targets, such as "configure"
  or "build", and interrupt it when it starts doing stuff you don't
  actually need.
* Read makefile sources. Usually, this involves tracking where a given
  variable is given a value, by searching a number of included
  makefiles. While not impossible or hard, it's very annoying that this
  has to be done in the first place, and a waste of time IMHO.

Wouldn't it be a good idea to add two targets to the debian/rules file,
say, "unpacked" and "patched" or something[1], which would unpack the
source, resp. patch it using the provided patches? These targets would
be mandatory if an unpacked source package would not provide an unpacked
source tree, and optional otherwise.

Comments?

[1] I don't care what the actual names of the targets would be, and it'd
    probably be a good idea to use names which are actually in use in
    some actual implementations; but I'd like to see this in policy, to
    avoid this mess in the future.

-- 
         EARTH
     smog  |   bricks
 AIR  --  mud  -- FIRE
soda water |   tequila
         WATER
 -- with thanks to fortune
[signature.asc (application/pgp-signature, inline)]

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

Acknowledgement sent to Bill Allombert <allomber@math.u-bordeaux.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 #10 received at 250202@bugs.debian.org (full text, mbox):

From: Bill Allombert <allomber@math.u-bordeaux.fr>
To: Wouter Verhelst <wouter@grep.be>, 250202@bugs.debian.org
Subject: Re: Bug#250202: mandate a common name for "patched source" and/or "unpacked source"o
Date: Fri, 21 May 2004 12:11:42 +0200
On Fri, May 21, 2004 at 11:27:27AM +0200, Wouter Verhelst wrote:
> Package: debian-policy
> Severity: wishlist
> 
> OK, I'm sick of this.
> 
> There are a number of dbs-style packages out there, that don't give you
> the source if you say "dpkg-source -x .dsc"; instead, they give you a
> directory with a source tarball and a bunch of patches. While this is
> probably a good idea to make maintaining said packages easier, the fact
> that they all have different debian/rules targets for unpacking sucks
> majorly; if you want to apply a small local patch, you have three
> options to find out what the right targets are:
> * Guess (which is hardly successful, IME)
> * Call one of the more common debian/rules targets, such as "configure"
>   or "build", and interrupt it when it starts doing stuff you don't
>   actually need.
> * Read makefile sources. Usually, this involves tracking where a given
>   variable is given a value, by searching a number of included
>   makefiles. While not impossible or hard, it's very annoying that this
>   has to be done in the first place, and a waste of time IMHO.
> 
> Wouldn't it be a good idea to add two targets to the debian/rules file,
> say, "unpacked" and "patched" or something[1], which would unpack the
> source, resp. patch it using the provided patches? These targets would
> be mandatory if an unpacked source package would not provide an unpacked
> source tree, and optional otherwise.

I would prefer if they do not require to run such target in the first
place. There is no need for it, you can just ship the patches preapplied
(with dpatch, it is just a matter of making clean depend of patch
instead of unpatch). I heard that doogie is developing a new release of
dbs that would not require to run such target anymore.

Also all my packages with non-trivial source process include a file
./README.source that explain how source should be handled. So that 
could be an alternative solution that does not convey that it is
suitable to require the user to run such target.

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#250202; Package debian-policy. Full text and rfc822 format available.

Acknowledgement sent to Wouter Verhelst <wouter@grep.be>:
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 250202@bugs.debian.org (full text, mbox):

From: Wouter Verhelst <wouter@grep.be>
To: Bill Allombert <allomber@math.u-bordeaux.fr>
Cc: 250202@bugs.debian.org
Subject: Re: Bug#250202: mandate a common name for "patched source" and/or "unpacked source"o
Date: Fri, 21 May 2004 12:56:45 +0200
[Message part 1 (text/plain, inline)]
On Fri, May 21, 2004 at 12:11:42PM +0200, Bill Allombert wrote:
> On Fri, May 21, 2004 at 11:27:27AM +0200, Wouter Verhelst wrote:
> > Wouldn't it be a good idea to add two targets to the debian/rules file,
> > say, "unpacked" and "patched" or something[1], which would unpack the
> > source, resp. patch it using the provided patches? These targets would
> > be mandatory if an unpacked source package would not provide an unpacked
> > source tree, and optional otherwise.
> 
> I would prefer if they do not require to run such target in the first
> place. There is no need for it, you can just ship the patches preapplied
> (with dpatch, it is just a matter of making clean depend of patch
> instead of unpatch).

While, in principle, I have nothing against this, it would make a huge
number of packages InstaBuggy, which clearly is not the way to go.

> I heard that doogie is developing a new release of dbs that would not
> require to run such target anymore.
> 
> Also all my packages with non-trivial source process include a file
> ./README.source that explain how source should be handled.

Hm. That sounds like a good idea, too.

-- 
         EARTH
     smog  |   bricks
 AIR  --  mud  -- FIRE
soda water |   tequila
         WATER
 -- with thanks to fortune
[signature.asc (application/pgp-signature, inline)]

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

Acknowledgement sent to Wouter Verhelst <wouter@grep.be>:
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 250202@bugs.debian.org (full text, mbox):

From: Wouter Verhelst <wouter@grep.be>
To: 250202@bugs.debian.org
Subject: Re: Bug#250202: mandate a common name for "patched source" and/or "unpacked source"
Date: Thu, 3 Jun 2004 08:57:05 +0200
[Message part 1 (text/plain, inline)]
retitle 250202 [PROPOSAL] mandate a "debian/README.source" file for packages with non-trivial source
thanks

On Fri, May 21, 2004 at 12:56:45PM +0200, Wouter Verhelst wrote:
> On Fri, May 21, 2004 at 12:11:42PM +0200, Bill Allombert wrote:
> > On Fri, May 21, 2004 at 11:27:27AM +0200, Wouter Verhelst wrote:
> > > Wouldn't it be a good idea to add two targets to the debian/rules file,
> > > say, "unpacked" and "patched" or something[1], which would unpack the
> > > source, resp. patch it using the provided patches? These targets would
> > > be mandatory if an unpacked source package would not provide an unpacked
> > > source tree, and optional otherwise.
> > 
> > I would prefer if they do not require to run such target in the first
> > place. There is no need for it, you can just ship the patches preapplied
> > (with dpatch, it is just a matter of making clean depend of patch
> > instead of unpatch).
> 
> While, in principle, I have nothing against this, it would make a huge
> number of packages InstaBuggy, which clearly is not the way to go.
> 
> > I heard that doogie is developing a new release of dbs that would not
> > require to run such target anymore.
> > 
> > Also all my packages with non-trivial source process include a file
> > ./README.source that explain how source should be handled.
> 
> Hm. That sounds like a good idea, too.

Since I got no further replies, let me fix it up to a formal proposal.

I propose that the following paragraph be added to the current Debian
policy. I'm looking for seconds.

--- policy.sgml.orig	2004-06-03 08:48:43.000000000 +0200
+++ policy.sgml	2004-06-03 08:55:59.000000000 +0200
@@ -2105,7 +2105,33 @@
 	  and <prgn>dpkg-distaddfile</prgn> should be called to add
 	  the file to the list in <file>debian/files</file>.</p>
       </sect>
-
+      
+      <sect id="readmesource">
+	<heading>Source package handling: debian/README.source</heading>
+
+	<p>
+          When running <prgn>dpkg-source -x</prgn> does not
+          immediately give one a directory with editable source, a
+          package must provide a file debian/README.source which
+          enumerates and documents the debian/rules targets for at
+          least <em>unpacking the source</em> and <em>applying
+          debian-specific patches</em> (if any, or a simple statement
+          that such a target does not exist or is not required if
+          none).</p>
+
+	<p>
+          At the maintainer's option, the file may also document any
+          other bits of the source package that may be of interest to
+          someone unfamiliar with the package (although not
+          necessarily with the upstream source), interested in making
+          modifications to it.</p>
+
+	<p>
+          Although this file is only required in one specific case
+          (see above), maintainers may include a README.source file if
+          they deem it appropriate, even if the above condition is not
+          fulfilled.</p>
+      </sect>
     </chapt>
 
 
-- 
         EARTH
     smog  |   bricks
 AIR  --  mud  -- FIRE
soda water |   tequila
         WATER
 -- with thanks to fortune
[signature.asc (application/pgp-signature, inline)]

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

Acknowledgement sent to Julian Gilbey <jdg@polya.uklinux.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 #25 received at 250202@bugs.debian.org (full text, mbox):

From: Julian Gilbey <jdg@polya.uklinux.net>
To: Wouter Verhelst <wouter@grep.be>, 250202@bugs.debian.org
Subject: Re: Bug#250202: mandate a common name for "patched source" and/or "unpacked source"
Date: Thu, 3 Jun 2004 09:25:42 +0100
On Thu, Jun 03, 2004 at 08:57:05AM +0200, Wouter Verhelst wrote:
> I propose that the following paragraph be added to the current Debian
> policy. I'm looking for seconds.

I second this proposal, in principle, but do we want to instantly make
packages RC-buggy by introducing a must?

> --- policy.sgml.orig	2004-06-03 08:48:43.000000000 +0200
> +++ policy.sgml	2004-06-03 08:55:59.000000000 +0200
> @@ -2105,7 +2105,33 @@
>  	  and <prgn>dpkg-distaddfile</prgn> should be called to add
>  	  the file to the list in <file>debian/files</file>.</p>
>        </sect>
> -
> +      
> +      <sect id="readmesource">
> +	<heading>Source package handling: debian/README.source</heading>
> +
> +	<p>
> +          When running <prgn>dpkg-source -x</prgn> does not
> +          immediately give one a directory with editable source, a
> +          package must provide a file debian/README.source which
> +          enumerates and documents the debian/rules targets for at
> +          least <em>unpacking the source</em> and <em>applying
> +          debian-specific patches</em> (if any, or a simple statement
> +          that such a target does not exist or is not required if
> +          none).</p>
> +
> +	<p>
> +          At the maintainer's option, the file may also document any
> +          other bits of the source package that may be of interest to
> +          someone unfamiliar with the package (although not
> +          necessarily with the upstream source), interested in making
> +          modifications to it.</p>
> +
> +	<p>
> +          Although this file is only required in one specific case
> +          (see above), maintainers may include a README.source file if
> +          they deem it appropriate, even if the above condition is not
> +          fulfilled.</p>
> +      </sect>
>      </chapt>
>  

   Julian

-- 
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

        Julian Gilbey, website: http://www.polya.uklinux.net/
   Debian GNU/Linux Developer, see: http://people.debian.org/~jdg/
     Visit http://www.thehungersite.com/ to help feed the hungry



Changed Bug title. Request was from Julian Gilbey <jdg@polya.uklinux.net> to control@bugs.debian.org. Full text and rfc822 format available.

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

Acknowledgement sent to Wouter Verhelst <wouter@grep.be>:
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 #32 received at 250202@bugs.debian.org (full text, mbox):

From: Wouter Verhelst <wouter@grep.be>
Cc: 250202@bugs.debian.org
Subject: Re: Bug#250202: mandate a common name for "patched source" and/or "unpacked source"
Date: Thu, 3 Jun 2004 18:14:24 +0200
[Message part 1 (text/plain, inline)]
On Thu, Jun 03, 2004 at 09:25:42AM +0100, Julian Gilbey wrote:
> On Thu, Jun 03, 2004 at 08:57:05AM +0200, Wouter Verhelst wrote:
> > I propose that the following paragraph be added to the current Debian
> > policy. I'm looking for seconds.
> 
> I second this proposal, in principle, but do we want to instantly make
> packages RC-buggy by introducing a must?

Uh -- right. Especially since I mentioned that point myself, for this
very proposal :-)

Let's assume I said "should" instead of "must". We can make it a must if
"most" packages that would require it, provide README.source

> > --- policy.sgml.orig	2004-06-03 08:48:43.000000000 +0200
> > +++ policy.sgml	2004-06-03 08:55:59.000000000 +0200
> > @@ -2105,7 +2105,33 @@
> >  	  and <prgn>dpkg-distaddfile</prgn> should be called to add
> >  	  the file to the list in <file>debian/files</file>.</p>
> >        </sect>
> > -
> > +      
> > +      <sect id="readmesource">
> > +	<heading>Source package handling: debian/README.source</heading>
> > +
> > +	<p>
> > +          When running <prgn>dpkg-source -x</prgn> does not
> > +          immediately give one a directory with editable source, a
> > +          package must provide a file debian/README.source which
> > +          enumerates and documents the debian/rules targets for at
> > +          least <em>unpacking the source</em> and <em>applying
> > +          debian-specific patches</em> (if any, or a simple statement
> > +          that such a target does not exist or is not required if
> > +          none).</p>
> > +
> > +	<p>
> > +          At the maintainer's option, the file may also document any
> > +          other bits of the source package that may be of interest to
> > +          someone unfamiliar with the package (although not
> > +          necessarily with the upstream source), interested in making
> > +          modifications to it.</p>
> > +
> > +	<p>
> > +          Although this file is only required in one specific case
> > +          (see above), maintainers may include a README.source file if
> > +          they deem it appropriate, even if the above condition is not
> > +          fulfilled.</p>
> > +      </sect>
> >      </chapt>
> >  
> 
>    Julian
> 
> -- 
> =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
> 
>         Julian Gilbey, website: http://www.polya.uklinux.net/
>    Debian GNU/Linux Developer, see: http://people.debian.org/~jdg/
>      Visit http://www.thehungersite.com/ to help feed the hungry
> 

-- 
         EARTH
     smog  |   bricks
 AIR  --  mud  -- FIRE
soda water |   tequila
         WATER
 -- with thanks to fortune
[signature.asc (application/pgp-signature, inline)]

Changed Bug title. Request was from Wouter Verhelst <wouter@grep.be> to control@bugs.debian.org. Full text and rfc822 format available.

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

Acknowledgement sent to Bill Allombert <allomber@math.u-bordeaux.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 #39 received at 250202@bugs.debian.org (full text, mbox):

From: Bill Allombert <allomber@math.u-bordeaux.fr>
To: Wouter Verhelst <wouter@grep.be>, 250202@bugs.debian.org
Subject: Re: Bug#250202: mandate a common name for "patched source" and/or "unpacked source"
Date: Fri, 11 Jun 2004 20:05:11 +0200
[Message part 1 (text/plain, inline)]
On Thu, Jun 03, 2004 at 08:57:05AM +0200, Wouter Verhelst wrote:
> --- policy.sgml.orig	2004-06-03 08:48:43.000000000 +0200
> +++ policy.sgml	2004-06-03 08:55:59.000000000 +0200
> @@ -2105,7 +2105,33 @@
>  	  and <prgn>dpkg-distaddfile</prgn> should be called to add
>  	  the file to the list in <file>debian/files</file>.</p>
>        </sect>
> -
> +      
> +      <sect id="readmesource">
> +	<heading>Source package handling: debian/README.source</heading>
> +
> +	<p>
> +          When running <prgn>dpkg-source -x</prgn> does not
> +          immediately give one a directory with editable source, a
> +          package must provide a file debian/README.source which
> +          enumerates and documents the debian/rules targets for at
> +          least <em>unpacking the source</em> and <em>applying
> +          debian-specific patches</em> (if any, or a simple statement
> +          that such a target does not exist or is not required if
> +          none).</p>
> +
> +	<p>
> +          At the maintainer's option, the file may also document any
> +          other bits of the source package that may be of interest to
> +          someone unfamiliar with the package (although not
> +          necessarily with the upstream source), interested in making
> +          modifications to it.</p>
> +
> +	<p>
> +          Although this file is only required in one specific case
> +          (see above), maintainers may include a README.source file if
> +          they deem it appropriate, even if the above condition is not
> +          fulfilled.</p>
> +      </sect>
>      </chapt>

I second this proposal.

I used to put the README.source in ./, but I agree that if policy mandate
it, it should be in debian/

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

Imagine a large red swirl here. 
[Message part 2 (application/pgp-signature, inline)]

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

Acknowledgement sent to Don Armstrong <don@donarmstrong.com>:
Extra info received and forwarded to list. Copy sent to debian-policy@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>. Full text and rfc822 format available.

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

From: Don Armstrong <don@donarmstrong.com>
To: 250202@bugs.debian.org
Subject: Re: Bug#250202: mandate a common name for "patched source" and/or "unpacked source"
Date: Fri, 11 Jun 2004 11:43:20 -0700
On Thu, 03 Jun 2004, Wouter Verhelst wrote:
> +          When running <prgn>dpkg-source -x</prgn> does not
> +          immediately give one a directory with editable source, a
> +          package must provide a file debian/README.source which
> +          enumerates and documents the debian/rules targets for at
> +          least <em>unpacking the source</em> and <em>applying
> +          debian-specific patches</em> (if any, or a simple statement
> +          that such a target does not exist or is not required if
> +          none).</p>

Can you consider suggesting default targets for this sort of
unpacking?

It would be nice if eventually these two targets were provided by all
packages, so you could automate the unpacking and applying of patches
if so desired, without having to read debian/README.source

I'm not sure if the targets 'unpack' and 'patch' would work, but they
seem to make the most sense. [perhaps a 'unpatch' target as well would
be usefull?]

Obviously, these wouldn't be 'must', but 'should' directives.


Don Armstrong

-- 
"There's no problem so large it can't be solved by killing the user
off, deleting their files, closing their account and reporting their
REAL earnings to the IRS."
 -- The B.O.F.H..

http://www.donarmstrong.com
http://rzlab.ucr.edu



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

Acknowledgement sent to Jeroen van Wolffelaar <jeroen@wolffelaar.nl>:
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 #49 received at 250202@bugs.debian.org (full text, mbox):

From: Jeroen van Wolffelaar <jeroen@wolffelaar.nl>
To: Wouter Verhelst <wouter@grep.be>
Cc: 250202@bugs.debian.org
Subject: Re: Bug#250202: mandate a common name for "patched source" and/or "unpacked source"
Date: Fri, 11 Jun 2004 20:57:52 +0200
On Thu, Jun 03, 2004 at 08:57:05AM +0200, Wouter Verhelst wrote:
> On Fri, May 21, 2004 at 12:56:45PM +0200, Wouter Verhelst wrote:
> > On Fri, May 21, 2004 at 12:11:42PM +0200, Bill Allombert wrote:
> > > Also all my packages with non-trivial source process include a file
> > > ./README.source that explain how source should be handled.
> > 
> > Hm. That sounds like a good idea, too.
> 
> Since I got no further replies, let me fix it up to a formal proposal.
> 
> I propose that the following paragraph be added to the current Debian
> policy. I'm looking for seconds.
> 
>  (proposal to demand a debian/README.source)

(note: I'm not a DD)

I'm in dubio about this. On the one hand, just demanding a
debian/README.source still doesn't give a general target for unpacked
sources. OTOH, it is a start, and standardizing on a readme file for
how your source package is arranged might be a good thing. But really
demanding such a README... 

In any case, to prevent insta-buggyness, I propose s/must/should/, and I
would change the last paragraph to really encourage the use, not merely
allow it:

| Although this file is only required in one specific case (see above),
| maintainers are encouraged to include a README.source file if the layout
| of the package is not trivial, so aid understanding of it, even if the
| above condition is not fulfilled.

--Jeroen

-- 
Jeroen van Wolffelaar
jeroen@wolffelaar.nl
http://jeroen.A-Eskwadraat.nl



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

Acknowledgement sent to Bill Allombert <allomber@math.u-bordeaux.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 #54 received at 250202@bugs.debian.org (full text, mbox):

From: Bill Allombert <allomber@math.u-bordeaux.fr>
To: Don Armstrong <don@donarmstrong.com>, 250202@bugs.debian.org
Subject: Re: Bug#250202: mandate a common name for "patched source" and/or "unpacked source"
Date: Fri, 11 Jun 2004 21:36:09 +0200
On Fri, Jun 11, 2004 at 11:43:20AM -0700, Don Armstrong wrote:
> 
> On Thu, 03 Jun 2004, Wouter Verhelst wrote:
> > +          When running <prgn>dpkg-source -x</prgn> does not
> > +          immediately give one a directory with editable source, a
> > +          package must provide a file debian/README.source which
> > +          enumerates and documents the debian/rules targets for at
> > +          least <em>unpacking the source</em> and <em>applying
> > +          debian-specific patches</em> (if any, or a simple statement
> > +          that such a target does not exist or is not required if
> > +          none).</p>
> 
> Can you consider suggesting default targets for this sort of
> unpacking?
> 
> It would be nice if eventually these two targets were provided by all
> packages, so you could automate the unpacking and applying of patches
> if so desired, without having to read debian/README.source
> 
> I'm not sure if the targets 'unpack' and 'patch' would work, but they
> seem to make the most sense. [perhaps a 'unpatch' target as well would
> be usefull?]

I already objected to that before. The correct way to proceed is to not
require the use of any targets. There is no real needs for them outside
very awkward situations, and then we don't know what kind of target
would be useful. dpatch do not require any (when clean depends on patch)
and dbs v2 won't either. I would rather move to "You should not require
any target to be run before modifying sources unless it is really
unconvenient, and in this case, document it in debian/README.source",
but obviously we are not yet here.

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#250202; Package debian-policy. Full text and rfc822 format available.

Acknowledgement sent to Wouter Verhelst <wouter@grep.be>:
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 #59 received at 250202@bugs.debian.org (full text, mbox):

From: Wouter Verhelst <wouter@grep.be>
To: Jeroen van Wolffelaar <jeroen@wolffelaar.nl>
Cc: 250202@bugs.debian.org, allomber@math.u-bordeaux.fr, jdg@polya.uklinux.net
Subject: Re: Bug#250202: mandate a common name for "patched source" and/or "unpacked source"
Date: Fri, 11 Jun 2004 22:30:58 +0200
[Message part 1 (text/plain, inline)]
On Fri, Jun 11, 2004 at 08:57:52PM +0200, Jeroen van Wolffelaar wrote:
> On Thu, Jun 03, 2004 at 08:57:05AM +0200, Wouter Verhelst wrote:
> > On Fri, May 21, 2004 at 12:56:45PM +0200, Wouter Verhelst wrote:
> > > On Fri, May 21, 2004 at 12:11:42PM +0200, Bill Allombert wrote:
> > > > Also all my packages with non-trivial source process include a file
> > > > ./README.source that explain how source should be handled.
> > > 
> > > Hm. That sounds like a good idea, too.
> > 
> > Since I got no further replies, let me fix it up to a formal proposal.
> > 
> > I propose that the following paragraph be added to the current Debian
> > policy. I'm looking for seconds.
> > 
> >  (proposal to demand a debian/README.source)
> 
> (note: I'm not a DD)
> 
> I'm in dubio about this. On the one hand, just demanding a
> debian/README.source still doesn't give a general target for unpacked
> sources. 

Indeed; and my first proposal was to require those targets to contain
the same target. However, after thinking about it, and thinking about
Bill's comment quoted above, I came up with the following arguments
against mandating a common name, and for README.source:

* Requiring every package to have the exact same target is quite
  intrusive; the different targets in the debian/rules file may depend
  on eachother, and while it is theoretically possible to just make a
  dummy target which would then list the "real" target in its
  dependencies, doing so would be quite ugly.
* I'm not really up-to-date on how these systems work. All packages I've
  seen do have a target to unpack the source and one to patch it, but
  that doesn't have to mean they all do; so, mandating these targets
  might require some maintainers to do a rewrite of their debian/rules
  file just so they could be compliant with this rule. That would suck.

For these two reasons, implementing the common name could be quite a bit
of work. Since the idea is to make work easier for other people (as
opposed to making the maintainer's job harder), that's a bug. The same
isn't true for README.source; you can write that in just a few minutes
and be done with it.

* README.source is more flexible. Since its use is, by purpose, not
  limited to what's listed in policy, I hope maintainers will have the
  common sense to document other "interesting" targets in that file.
  By design, this can not happen if we choose to mandate common names
  instead of using README.source.

> OTOH, it is a start, and standardizing on a readme file for
> how your source package is arranged might be a good thing. But really
> demanding such a README... 

I don't see what's wrong with that. A policy-compliant README.source
could be just a few lines long; it's not as if would be much of a
problem to create one.

> In any case, to prevent insta-buggyness, I propose s/must/should/,

Yes, that had already been suggested, and I accepted that amendment.

> and I would change the last paragraph to really encourage the use, not
> merely allow it:
> 
> | Although this file is only required in one specific case (see above),
> | maintainers are encouraged to include a README.source file if the layout
> | of the package is not trivial, so aid understanding of it, even if the
                                     ^
				   as to
> | above condition is not fulfilled.

No objection here. If none of the current seconders (that is, Julian
Gilbey and Bill Allombert) object, I'll accept this.

Bill? Julian?

-- 
         EARTH
     smog  |   bricks
 AIR  --  mud  -- FIRE
soda water |   tequila
         WATER
 -- with thanks to fortune
[signature.asc (application/pgp-signature, inline)]

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

Acknowledgement sent to Don Armstrong <don@donarmstrong.com>:
Extra info received and forwarded to list. Copy sent to debian-policy@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>. Full text and rfc822 format available.

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

From: Don Armstrong <don@donarmstrong.com>
To: 250202@bugs.debian.org
Subject: Re: Bug#250202: mandate a common name for "patched source" and/or "unpacked source"
Date: Fri, 11 Jun 2004 13:57:31 -0700
On Fri, 11 Jun 2004, Bill Allombert wrote:
> On Fri, Jun 11, 2004 at 11:43:20AM -0700, Don Armstrong wrote:
> > Can you consider suggesting default targets for this sort of
> > unpacking?
> 
> I already objected to that before.

AFAICT, your objection in <20040521101142.GE5026@seventeen> was to
packages which even required special targets to be unpacked and
patched, as the diff.gz should ship with the patches applied.

> The correct way to proceed is to not require the use of any
> targets. There is no real needs for them outside very awkward
> situations, and then we don't know what kind of target would be
> useful.

Requiring them is a couple steps farther than what I'm suggesting.

I'm suggesting that if packages need to have special targets to unpack
and apply patches, they should by default be named similarly. If a
package has special concerns that require different targets, policy
should allow them.

This is basically an attempt to avoid having maintainers make up their
own names for this process... having to run 'debian/rules untargz
munge;' on one package, 'debian/rules unpack patch' on another,
especially when we could suggest sane defaults to avoid this, seems
silly.

In effect, this would alleviate the need to read debian/README.source
in the most trivial cases where a README.source should be provided.


Don Armstrong

-- 
She was alot like starbucks.
IE, generic and expensive.
 -- hugh macleod http://www.gapingvoid.com/batch3.htm

http://www.donarmstrong.com
http://rzlab.ucr.edu



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

Acknowledgement sent to Bill Allombert <allomber@math.u-bordeaux.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 #69 received at 250202@bugs.debian.org (full text, mbox):

From: Bill Allombert <allomber@math.u-bordeaux.fr>
To: Don Armstrong <don@donarmstrong.com>, 250202@bugs.debian.org
Subject: Re: Bug#250202: mandate a common name for "patched source" and/or "unpacked source"
Date: Fri, 11 Jun 2004 23:59:50 +0200
On Fri, Jun 11, 2004 at 01:57:31PM -0700, Don Armstrong wrote:
> On Fri, 11 Jun 2004, Bill Allombert wrote:
> > On Fri, Jun 11, 2004 at 11:43:20AM -0700, Don Armstrong wrote:
> > > Can you consider suggesting default targets for this sort of
> > > unpacking?
> > 
> > I already objected to that before.
> 
> AFAICT, your objection in <20040521101142.GE5026@seventeen> was to
> packages which even required special targets to be unpacked and
> patched, as the diff.gz should ship with the patches applied.

I was alluding to:
"So that could be an alternative solution that does not convey that it
is suitable to require the user to run such target." 

Policy mandating a name for a target might make it sound like a good idea
to implement such a target, which I disagree with.  

> > The correct way to proceed is to not require the use of any
> > targets. There is no real needs for them outside very awkward
> > situations, and then we don't know what kind of target would be
> > useful.
> 
> Requiring them is a couple steps farther than what I'm suggesting.

I meant "the package should not require the use of any targets" not
"policy should not require the use of any targets".

> I'm suggesting that if packages need to have special targets to unpack
> and apply patches, they should by default be named similarly. If a
> package has special concerns that require different targets, policy
> should allow them.

Yes, but we cannot guess what kind of special targets such packages might need.
So far, all packages I looked at could be packaged to not require unpack
or patch. 

On the other hand, maintainer could use README.source to document how
suitable "upstream tarball" can be build (when upstream does not provide
usable tarball).

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#250202; Package debian-policy. Full text and rfc822 format available.

Acknowledgement sent to Bill Allombert <allomber@math.u-bordeaux.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 #74 received at 250202@bugs.debian.org (full text, mbox):

From: Bill Allombert <allomber@math.u-bordeaux.fr>
To: Wouter Verhelst <wouter@grep.be>
Cc: Jeroen van Wolffelaar <jeroen@wolffelaar.nl>, 250202@bugs.debian.org
Subject: Re: Bug#250202: mandate a common name for "patched source" and/or "unpacked source"
Date: Sat, 12 Jun 2004 00:32:13 +0200
On Fri, Jun 11, 2004 at 10:30:58PM +0200, Wouter Verhelst wrote:
> On Fri, Jun 11, 2004 at 08:57:52PM +0200, Jeroen van Wolffelaar wrote:
> > OTOH, it is a start, and standardizing on a readme file for
> > how your source package is arranged might be a good thing. But really
> > demanding such a README... 
> 
> I don't see what's wrong with that. A policy-compliant README.source
> could be just a few lines long; it's not as if would be much of a
> problem to create one.

Each build system tool (dbs,dpatch,cdbs, etc.) should ship such
README.source and let maintainer copy it to debian/. Sometime the
scripts could do it automatically (when converting to the system,
or in debian/rules clean). Of course README.source would contain
very basic instruction and pointer to the build system documentation.

> > In any case, to prevent insta-buggyness, I propose s/must/should/,
> 
> Yes, that had already been suggested, and I accepted that amendment.

I agree, I also accept it.

> > and I would change the last paragraph to really encourage the use, not
> > merely allow it:
> > 
> > | Although this file is only required in one specific case (see above),
> > | maintainers are encouraged to include a README.source file if the layout
> > | of the package is not trivial, so aid understanding of it, even if the
>                                      ^
> 				   as to
> > | above condition is not fulfilled.
> 
> No objection here. If none of the current seconders (that is, Julian
> Gilbey and Bill Allombert) object, I'll accept this.
> 
> Bill? Julian?

I agree with Jeroen changes.

Basically there are several things you want to do with a source package:
1) Build it umodified. 
   The way to do that is documented and breaking that is most always RC.

2) Modify it and build it.
   README.source should document how to that when the simple procedure
   would fail.

3) Switch to a new upstream version.
   This one is more difficult since we are not responsible for the
   content of new upstream tarball. Nevertheless, I think README.source 
   could document how to proceed in the event of the new upstream
   tarball being nearly identical to the current one, when a special
   procedure is required. (Though we have debian/rules get-orig-source
   already in policy). for example eterm-themes debian/rules
   get-orig-source will grab the themes from the web and build a
   tarball (and check whether they have changed) since upstream does not
   provide such tarball.

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

Imagine a large red swirl here. 



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

Acknowledgement sent to Don Armstrong <don@donarmstrong.com>:
Extra info received and forwarded to list. Copy sent to debian-policy@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>. Full text and rfc822 format available.

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

From: Don Armstrong <don@donarmstrong.com>
To: 250202@bugs.debian.org
Subject: Re: Bug#250202: mandate a common name for "patched source" and/or "unpacked source"
Date: Fri, 11 Jun 2004 16:53:53 -0700
On Fri, 11 Jun 2004, Bill Allombert wrote:
> Policy mandating a name for a target might make it sound like a good
> idea to implement such a target, which I disagree with.

That can be trivially addressed by couching it in language indicating
that fact.

> I meant "the package should not require the use of any targets" not
> "policy should not require the use of any targets".

That may very well be. However, in the cases where they are required,
or at least desired, I see no reason not to recommend a set of
standard names.

> Yes, but we cannot guess what kind of special targets such packages
> might need.

We can't guess them all, definetly. But in the three cases here,
unpacking, patching, and unpatching, we can at least make a suggestion
of reasonable names to be used.


Don Armstrong

-- 
Miracles had become relative common-places since the advent of
entheogens; it now took very unusual circumstances to attract public
attention to sightings of supernatural entities. The latest miracle
had raised the ante on the supernatural: the Virgin Mary had
manifested herself to two children, a dog, and a Public Telepresence
Point.

-- Bruce Sterling, _Holy Fire_ p228

http://www.donarmstrong.com
http://rzlab.ucr.edu



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

Acknowledgement sent to Julian Gilbey <jdg@polya.uklinux.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 #84 received at 250202@bugs.debian.org (full text, mbox):

From: Julian Gilbey <jdg@polya.uklinux.net>
To: Wouter Verhelst <wouter@grep.be>
Cc: Jeroen van Wolffelaar <jeroen@wolffelaar.nl>, 250202@bugs.debian.org, allomber@math.u-bordeaux.fr
Subject: Re: Bug#250202: mandate a common name for "patched source" and/or "unpacked source"
Date: Sun, 13 Jun 2004 08:11:21 +0100
On Fri, Jun 11, 2004 at 10:30:58PM +0200, Wouter Verhelst wrote:
> > and I would change the last paragraph to really encourage the use, not
> > merely allow it:
> > 
> > | Although this file is only required in one specific case (see above),
> > | maintainers are encouraged to include a README.source file if the layout
> > | of the package is not trivial, so aid understanding of it, even if the
>                                      ^
> 				   as to
> > | above condition is not fulfilled.
> 
> No objection here. If none of the current seconders (that is, Julian
> Gilbey and Bill Allombert) object, I'll accept this.
> 
> Bill? Julian?

OK.

   Julian

-- 
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

        Julian Gilbey, website: http://www.polya.uklinux.net/
   Debian GNU/Linux Developer, see: http://people.debian.org/~jdg/
     Visit http://www.thehungersite.com/ to help feed the hungry



Changed Bug submitter from Wouter Verhelst <wouter@grep.be> to wouter@debian.org. Request was from Wouter Verhelst <wouter@grep.be> to control@bugs.debian.org. Full text and rfc822 format available.

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

Acknowledgement sent to Wouter Verhelst <wouter@grep.be>:
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 #91 received at 250202@bugs.debian.org (full text, mbox):

From: Wouter Verhelst <wouter@grep.be>
To: control@bugs.debian.org, 250202@bugs.debian.org
Subject: Get this over with
Date: Mon, 20 Sep 2004 02:43:52 +0200
[Message part 1 (text/plain, inline)]
retitle 250202 [AMENDMENT 20/09/2004] "debian/README.source" file for packages with non-trivial source
thanks

It's been a while since the last mail on this proposal, which reached
the required number of seconders ages ago. I'm assuming the proposal has
been accepted now, and turn this into an amendment. For reference, the
patch as it should be applied is as follows:

--- policy.sgml.orig	2004-09-20 02:35:38.000000000 +0200
+++ policy.sgml	2004-09-20 02:38:37.000000000 +0200
@@ -2097,7 +2097,34 @@
 	  and <prgn>dpkg-distaddfile</prgn> should be called to add
 	  the file to the list in <file>debian/files</file>.</p>
       </sect>
-
+      
+      <sect id="readmesource">
+	<heading>Source package handling: debian/README.source</heading>
+
+	<p>
+          When running <prgn>dpkg-source -x</prgn> does not
+          immediately give one a directory with editable source, a
+          package should provide a file debian/README.source which
+          enumerates and documents the debian/rules targets for at
+          least <em>unpacking the source</em> and <em>applying
+          debian-specific patches</em> (if any, or a simple statement
+          that such a target does not exist or is not required if
+          none).</p>
+
+	<p>
+          At the maintainer's option, the file may also document any
+          other bits of the source package that may be of interest to
+          someone unfamiliar with the package (although not
+          necessarily with the upstream source), interested in making
+          modifications to it.</p>
+
+	<p>
+          Although this file is only required in one specific case
+	  (see above), maintainers are encouraged to include a README.source
+	  file if the layout of the package is not trivial, so as to aid
+	  understanding of it, even if the above condition is not
+	  fulfilled.</p>
+      </sect>
     </chapt>
 
 

-- 
         EARTH
     smog  |   bricks
 AIR  --  mud  -- FIRE
soda water |   tequila
         WATER
 -- with thanks to fortune
[signature.asc (application/pgp-signature, inline)]

Changed Bug title. Request was from Wouter Verhelst <wouter@grep.be> to control@bugs.debian.org. Full text and rfc822 format available.

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

Acknowledgement sent to Manoj Srivastava <srivasta@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 #98 received at 250202@bugs.debian.org (full text, mbox):

From: Manoj Srivastava <srivasta@debian.org>
To: debian-policy@lists.debian.org
Cc: control@bugs.debian.org, 250202@bugs.debian.org
Subject: Re: Bug#250202: Get this over with
Date: Sun, 19 Sep 2004 23:47:55 -0500
retitle 250202 [PROPOSAL] "debian/README.source" file for packages with non-trivial source
thanks

On Mon, 20 Sep 2004 02:43:52 +0200, Wouter Verhelst <wouter@grep.be> said: 


> retitle 250202 [AMENDMENT 20/09/2004] "debian/README.source" file
> for packages with non-trivial source thanks

> It's been a while since the last mail on this proposal, which
> reached the required number of seconders ages ago. I'm assuming the
> proposal has been accepted now, and turn this into an amendment. For
> reference, the patch as it should be applied is as follows:

	Sorry, lack of discussion does not imply consensus. I And
 getting seconds gets you into the proposal stage, and not into the
 accepted amendment status.

	There are still problems with this proposal: it would make all
 affected packages instantly buggy (to be sure, a normal bug, and not
 an RC bug), but we do tend to frown upon that.

	I propose that this be amended to initially just recommend
 that packages create the readme file; and then when that has become
 the way things are being done, then we can move to should/must.

	I would also be more comfortable if there were some indication
 of a wider agreement (more aol posts, perhaps?), but I would take a
 lack of protests as the silent majority being behind this proposal.

	manoj
-- 
"I want more life, fucker!" Roy Batty, in Ridley Scott's Blade Runner
Manoj Srivastava   <srivasta@debian.org>  <http://www.debian.org/%7Esrivasta/>
1024D/BF24424C print 4966 F272 D093 B493 410B  924B 21BA DABB BF24 424C



Changed Bug title. Request was from Manoj Srivastava <srivasta@debian.org> to control@bugs.debian.org. Full text and rfc822 format available.

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

Acknowledgement sent to Wouter Verhelst <wouter@grep.be>:
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 #105 received at 250202@bugs.debian.org (full text, mbox):

From: Wouter Verhelst <wouter@grep.be>
To: debian-policy@lists.debian.org, 250202@bugs.debian.org
Subject: Re: Bug#250202: Get this over with
Date: Mon, 20 Sep 2004 10:28:31 +0200
[Message part 1 (text/plain, inline)]
On Sun, Sep 19, 2004 at 11:47:55PM -0500, Manoj Srivastava wrote:
> On Mon, 20 Sep 2004 02:43:52 +0200, Wouter Verhelst <wouter@grep.be> said: 
> > It's been a while since the last mail on this proposal, which
> > reached the required number of seconders ages ago. I'm assuming the
> > proposal has been accepted now, and turn this into an amendment. For
> > reference, the patch as it should be applied is as follows:
> 
> 	Sorry, lack of discussion does not imply consensus.

Of course not; but I'd say lack of opposition does. There had been none,
AFAIK. I didn't take Don's amendment into account when writing that
previous patch because I hadn't seen many people agree with his
suggestion; but I didn't see a mail saying "I don't like this" from him
either.

>  And getting seconds gets you into the proposal stage, and not into
>  the accepted amendment status.

That's not what policy-process.txt says[1], but I'll take your word for
it.

> 	There are still problems with this proposal: it would make all
>  affected packages instantly buggy (to be sure, a normal bug, and not
>  an RC bug), but we do tend to frown upon that.

(checks) Right. Grmbl. Okay.

> 	I propose that this be amended to initially just recommend
>  that packages create the readme file; and then when that has become
>  the way things are being done, then we can move to should/must.

Accepted.

> 	I would also be more comfortable if there were some indication
>  of a wider agreement (more aol posts, perhaps?), but I would take a
>  lack of protests as the silent majority being behind this proposal.

That's what I did; there were no protests, so I took that as a silent
majority being behind the proposal.

[1]   When a proposal in the BTS has acquired two seconds (apart from the
      proposer), it becomes a formal amendment.  The bug severity is raised
      to "normal" and the bug is retitled to _"[AMENDMENT DD/MM/YYYY] ..."_.

      in policy-process.txt on lines 163-165. I forgot about the
      severity, but oh well.

-- 
         EARTH
     smog  |   bricks
 AIR  --  mud  -- FIRE
soda water |   tequila
         WATER
 -- with thanks to fortune
[signature.asc (application/pgp-signature, inline)]

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

Acknowledgement sent to Marco d'Itri <md@Linux.IT>:
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 #110 received at 250202@bugs.debian.org (full text, mbox):

From: Marco d'Itri <md@Linux.IT>
To: 250202@bugs.debian.org
Subject: Re: Bug#250202: Get this over with
Date: Mon, 20 Sep 2004 10:21:05 +0200
[Message part 1 (text/plain, inline)]
On Sep 20, Wouter Verhelst <wouter@grep.be> wrote:

> +          When running <prgn>dpkg-source -x</prgn> does not
> +          immediately give one a directory with editable source, a
> +          package should provide a file debian/README.source which
> +          enumerates and documents the debian/rules targets for at
> +          least <em>unpacking the source</em> and <em>applying
> +          debian-specific patches</em> (if any, or a simple statement
> +          that such a target does not exist or is not required if
> +          none).</p>
I object to an hard requirement, and I also object to the general idea.
It's not like there are hundred of different packaging scripts, so we
would end up with hundred of similar three-lines README.source files.
I think it would be better to have a standard makefile target for
unpacking/patching which would solve the issue in most situations and
then use README.source when something really complex is going on and
more details are useful.

-- 
ciao, |
Marco | [8074 timf/lAMeuhbc]
[signature.asc (application/pgp-signature, inline)]

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

Acknowledgement sent to Marc 'HE' Brockschmidt <he@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 #115 received at 250202@bugs.debian.org (full text, mbox):

From: Marc 'HE' Brockschmidt <he@debian.org>
To: debian-policy@lists.debian.org, 250202@bugs.debian.org
Subject: Re: Bug#250202: Get this over with
Date: Mon, 20 Sep 2004 18:16:06 +0200
[Message part 1 (text/plain, inline)]
Wouter Verhelst <wouter@grep.be> writes:
> On Sun, Sep 19, 2004 at 11:47:55PM -0500, Manoj Srivastava wrote:
>> On Mon, 20 Sep 2004 02:43:52 +0200, Wouter Verhelst <wouter@grep.be> said: 
>> 	I would also be more comfortable if there were some indication
>>  of a wider agreement (more aol posts, perhaps?), but I would take a
>>  lack of protests as the silent majority being behind this proposal.
> That's what I did; there were no protests, so I took that as a silent
> majority being behind the proposal.

Me too !!!!11 </AOL>

Anyway, i think this would be a good thing (after a few BSPs I know
that not every package's source layout is trivial)

Marc
-- 
$_=')(hBCdzVnS})3..0}_$;//::niam/s~=)]3[))_$(rellac(=_$({pam(esrever })e$.)4/3*
)e$(htgnel+23(rhc,"u"(kcapnu ,""nioj ;|_- |/+9-0z-aZ-A|rt~=e$;_$=e${pam tnirp{y
V2ajFGabus} yV2ajFGa&{gwmclBHIbus}gwmclBHI&{yVGa09mbbus}yVGa09mb&{hBCdzVnSbus';
s/\n//g;s/bus/\nbus/g;eval scalar reverse   # <mailto:marc@marcbrockschmidt.de>
[Message part 2 (application/pgp-signature, inline)]

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

Acknowledgement sent to Wouter Verhelst <wouter@grep.be>:
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 #120 received at 250202@bugs.debian.org (full text, mbox):

From: Wouter Verhelst <wouter@grep.be>
To: Marco d'Itri <md@Linux.IT>, 250202@bugs.debian.org
Subject: Re: Bug#250202: Get this over with
Date: Tue, 21 Sep 2004 00:32:04 +0200
On Mon, Sep 20, 2004 at 10:21:05AM +0200, Marco d'Itri wrote:
> On Sep 20, Wouter Verhelst <wouter@grep.be> wrote:
> > +          When running <prgn>dpkg-source -x</prgn> does not
> > +          immediately give one a directory with editable source, a
> > +          package should provide a file debian/README.source which
> > +          enumerates and documents the debian/rules targets for at
> > +          least <em>unpacking the source</em> and <em>applying
> > +          debian-specific patches</em> (if any, or a simple statement
> > +          that such a target does not exist or is not required if
> > +          none).</p>
> I object to an hard requirement, and I also object to the general idea.
> It's not like there are hundred of different packaging scripts, so we
> would end up with hundred of similar three-lines README.source files.

Perhaps my judgement was clouded by the fact that dbs-alike scripts
aren't synchronized yet; however, at the time I reported this bug, there
were at least a number of (incompatible) dbs-alike scripts out there.

The fact that there is now cdbs (which is gaining more adoption, and is
slowly but surely replacing the older variants) does indeed help. In any
case, if the packages that use such packaging schemes could come to an
agreement without having to go through policy, that would indeed even be
better.

> I think it would be better to have a standard makefile target for
> unpacking/patching which would solve the issue in most situations and
> then use README.source when something really complex is going on and
> more details are useful.

Sounds reasonable.

-- 
         EARTH
     smog  |   bricks
 AIR  --  mud  -- FIRE
soda water |   tequila
         WATER
 -- with thanks to fortune



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

Acknowledgement sent to Marco d'Itri <md@Linux.IT>:
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 #125 received at 250202@bugs.debian.org (full text, mbox):

From: Marco d'Itri <md@Linux.IT>
To: Wouter Verhelst <wouter@grep.be>
Cc: 250202@bugs.debian.org
Subject: Re: Bug#250202: Get this over with
Date: Tue, 21 Sep 2004 00:35:49 +0200
On Sep 21, Wouter Verhelst <wouter@grep.be> wrote:

> > I object to an hard requirement, and I also object to the general idea.
> > It's not like there are hundred of different packaging scripts, so we
> > would end up with hundred of similar three-lines README.source files.
> 
> Perhaps my judgement was clouded by the fact that dbs-alike scripts
> aren't synchronized yet; however, at the time I reported this bug, there
> were at least a number of (incompatible) dbs-alike scripts out there.
This is not important, maintainers just need to add an alias target to
debian/rules.
*Way* easier to maintain and use for everybody involved than writing a
natural language description of the operations involved.

> The fact that there is now cdbs (which is gaining more adoption, and is
> slowly but surely replacing the older variants) does indeed help. In any
> case, if the packages that use such packaging schemes could come to an
> agreement without having to go through policy, that would indeed even be
> better.
All my packages use the "unpack" target because somebody once opened a
bug saying this was a de facto standard. (I did not bother to check.)

-- 
ciao, |
Marco | [8091 alsmF4qJ2LQbU]



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

Acknowledgement sent to Wouter Verhelst <wouter@grep.be>:
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 #130 received at 250202@bugs.debian.org (full text, mbox):

From: Wouter Verhelst <wouter@grep.be>
To: Marco d'Itri <md@Linux.IT>, 250202@bugs.debian.org
Subject: Re: Bug#250202: Get this over with
Date: Tue, 21 Sep 2004 01:28:19 +0200
[Message part 1 (text/plain, inline)]
On Tue, Sep 21, 2004 at 12:35:49AM +0200, Marco d'Itri wrote:
> On Sep 21, Wouter Verhelst <wouter@grep.be> wrote:
> > > I object to an hard requirement, and I also object to the general idea.
> > > It's not like there are hundred of different packaging scripts, so we
> > > would end up with hundred of similar three-lines README.source files.
> > 
> > Perhaps my judgement was clouded by the fact that dbs-alike scripts
> > aren't synchronized yet; however, at the time I reported this bug, there
> > were at least a number of (incompatible) dbs-alike scripts out there.
> This is not important, maintainers just need to add an alias target to
> debian/rules.
> *Way* easier to maintain and use for everybody involved than writing a
> natural language description of the operations involved.
> 
> > The fact that there is now cdbs (which is gaining more adoption, and is
> > slowly but surely replacing the older variants) does indeed help. In any
> > case, if the packages that use such packaging schemes could come to an
> > agreement without having to go through policy, that would indeed even be
> > better.
> All my packages use the "unpack" target because somebody once opened a
> bug saying this was a de facto standard. (I did not bother to check.)

Right.

When starting this proposal, I didn't aim for overdocumentation or
anything similar; I was just fed up with the fact that the Debian source
package format allows one to just 'apt-get source foo; cd
foo-<version>', and start hacking, which obviously is a good thing.

Dbs and other things broke this assumption; because of incompatibilities
among different dbs-alike implementations, you had to dig through an
awful amount of makefiles -- which is not impossible, just an annoyance.
Because I wanted to restore the ability to just go ahead and look at the
source without having to care about packaging details, I started this
proposal.

There have been oppositions to my original idea of mandating a common
name. I accepted the suggestion of using a documentation file to restore
this assumption, but that seems to meet some opposition as well.

Fact is, I don't actually care how the problem is solved, as long as it
is solved. As there obviously are a number of people who do care,
though, I'll just step back here and let those other people handle it --
but please /do/ take care of it. Having something which can be easily
edited is a virtue, and we should make that equally possible within the
entirety of Debian again.

-- 
         EARTH
     smog  |   bricks
 AIR  --  mud  -- FIRE
soda water |   tequila
         WATER
 -- with thanks to fortune
[signature.asc (application/pgp-signature, inline)]

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

Acknowledgement sent to Florian Weimer <fw@deneb.enyo.de>:
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 #135 received at 250202@bugs.debian.org (full text, mbox):

From: Florian Weimer <fw@deneb.enyo.de>
To: Wouter Verhelst <wouter@grep.be>
Cc: 250202@bugs.debian.org
Subject: Re: Bug#250202: Get this over with
Date: Mon, 11 Oct 2004 14:12:18 +0200
* Wouter Verhelst:

>  	  the file to the list in <file>debian/files</file>.</p>

> +          When running <prgn>dpkg-source -x</prgn> does not
> +          immediately give one a directory with editable source, a
> +          package should provide a file debian/README.source which
> +          enumerates and documents the debian/rules targets for at
> +          least <em>unpacking the source</em> and <em>applying
> +          debian-specific patches</em> (if any, or a simple statement
> +          that such a target does not exist or is not required if
> +          none).</p>

This patch is missing a few <file> tags (see the line I quoted above).

Furthermore, I strongly urge you to include a requirement to describe
how further patches can be applied so that they actually end up in the
resulting package.  You really want to make sure that users can
successfully apply patches whose changes are not readily testable
(also called "security patches").

Pointers to reasonably verbose instructions should be sufficient (note
that the dpatch manpage doesn't belong into this category, IMHO).

> +          Although this file is only required in one specific case
> +	  (see above), maintainers are encouraged to include a README.source
> +	  file if the layout of the package is not trivial, so as to aid
> +	  understanding of it, even if the above condition is not
> +	  fulfilled.</p>

I'm not sure if this part is required.  Usually, I'm more interested
in the build process than the actual directory structure.



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

Acknowledgement sent to Florian Weimer <fw@deneb.enyo.de>:
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 #140 received at 250202@bugs.debian.org (full text, mbox):

From: Florian Weimer <fw@deneb.enyo.de>
To: Marco d'Itri <md@Linux.IT>
Cc: 250202@bugs.debian.org, Wouter Verhelst <wouter@grep.be>
Subject: Re: Bug#250202: Get this over with
Date: Mon, 11 Oct 2004 14:30:29 +0200
* Marco d'Itri:

> This is not important, maintainers just need to add an alias target
> to debian/rules.  *Way* easier to maintain and use for everybody
> involved than writing a natural language description of the
> operations involved.

For those using Debian in production it's also important to
permanently apply security patches to source trees.  In some cases,
changes to source trees after unpacking are *not* permanent.

You can't solve this issue by simply adding targets to debian/rules,
I'm afraid.



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

Acknowledgement sent to Marco d'Itri <md@Linux.IT>:
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 #145 received at 250202@bugs.debian.org (full text, mbox):

From: Marco d'Itri <md@Linux.IT>
Cc: 250202@bugs.debian.org
Subject: Re: Bug#250202: Get this over with
Date: Mon, 11 Oct 2004 14:32:07 +0200
On Oct 11, Florian Weimer <fw@deneb.enyo.de> wrote:

> > This is not important, maintainers just need to add an alias target
> > to debian/rules.  *Way* easier to maintain and use for everybody
> > involved than writing a natural language description of the
> > operations involved.
> 
> For those using Debian in production it's also important to
> permanently apply security patches to source trees.  In some cases,
> changes to source trees after unpacking are *not* permanent.
Your point being? I can't see how this is relevant to the issue being
discussed.

-- 
ciao, |
Marco | [8486 stcwjIO7/2A.Y]



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

Acknowledgement sent to Wouter Verhelst <wouter@grep.be>:
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 #150 received at 250202@bugs.debian.org (full text, mbox):

From: Wouter Verhelst <wouter@grep.be>
To: Florian Weimer <fw@deneb.enyo.de>, 250202@bugs.debian.org
Subject: Re: Bug#250202: Get this over with
Date: Mon, 11 Oct 2004 15:21:39 +0200
On Mon, Oct 11, 2004 at 02:12:18PM +0200, Florian Weimer wrote:
> * Wouter Verhelst:
> >  	  the file to the list in <file>debian/files</file>.</p>
> 
> > +          When running <prgn>dpkg-source -x</prgn> does not
> > +          immediately give one a directory with editable source, a
> > +          package should provide a file debian/README.source which
> > +          enumerates and documents the debian/rules targets for at
> > +          least <em>unpacking the source</em> and <em>applying
> > +          debian-specific patches</em> (if any, or a simple statement
> > +          that such a target does not exist or is not required if
> > +          none).</p>
> 
> This patch is missing a few <file> tags (see the line I quoted above).

Indeed.

> Furthermore, I strongly urge you to include a requirement to describe
> how further patches can be applied so that they actually end up in the
> resulting package.  You really want to make sure that users can
> successfully apply patches whose changes are not readily testable
> (also called "security patches").

No objection, even if I find that reasonably easy and self-explanatory.

> Pointers to reasonably verbose instructions should be sufficient (note
> that the dpatch manpage doesn't belong into this category, IMHO).

Of course. The point is to make the life of our users easier, not to
make the life of our maintainers harder.

> > +          Although this file is only required in one specific case
> > +	  (see above), maintainers are encouraged to include a README.source
> > +	  file if the layout of the package is not trivial, so as to aid
> > +	  understanding of it, even if the above condition is not
> > +	  fulfilled.</p>
> 
> I'm not sure if this part is required.  Usually, I'm more interested
> in the build process than the actual directory structure.

This paragraph is about more than just the actual directory structure.
The intention is for people to document any special-case things in their
package management; whether those are special-purpose scripts, obscure
debian/rules targets or strange directory layouts is besides the point.

If that wasn't clear, perhaps it should be reworded, but that's about
it.

-- 
         EARTH
     smog  |   bricks
 AIR  --  mud  -- FIRE
soda water |   tequila
         WATER
 -- with thanks to fortune



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

Acknowledgement sent to Florian Weimer <fw@deneb.enyo.de>:
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 #155 received at 250202@bugs.debian.org (full text, mbox):

From: Florian Weimer <fw@deneb.enyo.de>
To: Marco d'Itri <md@Linux.IT>
Cc: 250202@bugs.debian.org
Subject: Re: Bug#250202: Get this over with
Date: Mon, 11 Oct 2004 16:17:30 +0200
* Marco d'Itri:

> On Oct 11, Florian Weimer <fw@deneb.enyo.de> wrote:
>
>> > This is not important, maintainers just need to add an alias target
>> > to debian/rules.  *Way* easier to maintain and use for everybody
>> > involved than writing a natural language description of the
>> > operations involved.
>> 
>> For those using Debian in production it's also important to
>> permanently apply security patches to source trees.  In some cases,
>> changes to source trees after unpacking are *not* permanent.

> Your point being? I can't see how this is relevant to the issue
> being discussed.

I thought that README.source is intended to help casual packages
maintainers (or people who are forced to do a maintainer's task
because of some emergency).  A way to obtain the real source code from
which the package is built is not sufficient.  Changes to these
sources might not survive a dpkg-buildpackage run in some cases (a big
oops if your critical but non-testable security fix is silently
discarded).



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

Acknowledgement sent to Marco d'Itri <md@Linux.IT>:
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 #160 received at 250202@bugs.debian.org (full text, mbox):

From: Marco d'Itri <md@Linux.IT>
To: 250202@bugs.debian.org
Subject: Re: Bug#250202: Get this over with
Date: Tue, 12 Oct 2004 10:13:58 +0200
[Message part 1 (text/plain, inline)]
On Oct 11, Florian Weimer <fw@deneb.enyo.de> wrote:

> Which part about "emergency maintenance" is so hard to understand?
> 
> The system administrators I know can compile Apache+OpenSSL+PHP from
> scratch, but would have trouble to apply a PHP security patch to the
> Debian package (even though most of them have basic experience with
> the way Debian packages are created).
I do not consider this to be a problem.

It would be stupid to add documentation for build systems in every
non-trivial package.

-- 
ciao, |
Marco | [8506 daW.ZQgq2KvTE]
[signature.asc (application/pgp-signature, inline)]

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

Acknowledgement sent to Colin Watson <cjwatson@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 #165 received at 250202@bugs.debian.org (full text, mbox):

From: Colin Watson <cjwatson@debian.org>
To: Marco d'Itri <md@Linux.IT>, 250202@bugs.debian.org
Subject: Re: Bug#250202: Get this over with
Date: Tue, 12 Oct 2004 11:36:58 +0100
On Tue, Oct 12, 2004 at 10:13:58AM +0200, Marco d'Itri wrote:
> On Oct 11, Florian Weimer <fw@deneb.enyo.de> wrote:
> > Which part about "emergency maintenance" is so hard to understand?
> > 
> > The system administrators I know can compile Apache+OpenSSL+PHP from
> > scratch, but would have trouble to apply a PHP security patch to the
> > Debian package (even though most of them have basic experience with
> > the way Debian packages are created).
> 
> I do not consider this to be a problem.
> 
> It would be stupid to add documentation for build systems in every
> non-trivial package.

If you're going to use systems which many people who need to tweak them
will find difficult to use, then, stupid or not, you need to document
them.

-- 
Colin Watson                                       [cjwatson@debian.org]



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

Acknowledgement sent to Marco d'Itri <md@Linux.IT>:
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 #170 received at 250202@bugs.debian.org (full text, mbox):

From: Marco d'Itri <md@Linux.IT>
Cc: 250202@bugs.debian.org
Subject: Re: Bug#250202: Get this over with
Date: Tue, 12 Oct 2004 12:40:34 +0200
On Oct 12, Colin Watson <cjwatson@debian.org> wrote:

> If you're going to use systems which many people who need to tweak them
> will find difficult to use, then, stupid or not, you need to document
> them.
I do not consider "difficult to use" a system which provides "unpack"
and "diff" targets.

-- 
ciao, |
Marco | [8512 daIQBDfS5bd.Y]



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

Acknowledgement sent to Colin Watson <cjwatson@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 #175 received at 250202@bugs.debian.org (full text, mbox):

From: Colin Watson <cjwatson@debian.org>
To: Marco d'Itri <md@Linux.IT>, 250202@bugs.debian.org
Cc: debian-policy@lists.debian.org
Subject: Re: Bug#250202: Get this over with
Date: Tue, 12 Oct 2004 12:49:27 +0100
On Tue, Oct 12, 2004 at 12:40:34PM +0200, Marco d'Itri wrote:
> On Oct 12, Colin Watson <cjwatson@debian.org> wrote:
> > If you're going to use systems which many people who need to tweak them
> > will find difficult to use, then, stupid or not, you need to document
> > them.
> 
> I do not consider "difficult to use" a system which provides "unpack"
> and "diff" targets.

You don't count, since you've encountered it before. Anything more than
what's documented in /usr/share/doc/debian/source-unpack.txt needs
further documentation.

-- 
Colin Watson                                       [cjwatson@debian.org]



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

Acknowledgement sent to Wouter Verhelst <wouter@grep.be>:
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 #180 received at 250202@bugs.debian.org (full text, mbox):

From: Wouter Verhelst <wouter@grep.be>
To: Marco d'Itri <md@Linux.IT>, 250202@bugs.debian.org
Subject: Re: Bug#250202: Get this over with
Date: Tue, 12 Oct 2004 13:51:01 +0200
[Message part 1 (text/plain, inline)]
On Tue, Oct 12, 2004 at 10:13:58AM +0200, Marco d'Itri wrote:
> On Oct 11, Florian Weimer <fw@deneb.enyo.de> wrote:
> 
> > Which part about "emergency maintenance" is so hard to understand?
> > 
> > The system administrators I know can compile Apache+OpenSSL+PHP from
> > scratch, but would have trouble to apply a PHP security patch to the
> > Debian package (even though most of them have basic experience with
> > the way Debian packages are created).
> 
> I do not consider this to be a problem.

I do.

> It would be stupid to add documentation for build systems in every
> non-trivial package.

We clearly disagree, then.

I'm not saying we should start to document how each and every build
system out there works. However, I do think it should be the
maintainer's job to document any out of the ordinary things he did while
creating his package.

We require that binaries in our binary, compiled packages have
documentation through manpages. Why don't we require documentation for
our source packages?

I've had to tweak source packages on quite a number of occasions now
(usually to create custom-configured packages for a project at work),
and this problem has bothered me more than once. The fact that the
source is there does not matter -- the source is there for each and
every binary in our main archive, too, and yet we still do require
documentation.

This bug is not about creating an interface (the interface to building
debian packages is clear enough), nor is it about making it possible to
do stuff which isn't possible right now (you /can/ still do this, if not
as easily as one would want). It's about making the life of someone who
occasionally wants to modify a Debian package, not harder than it should
be.

-- 
         EARTH
     smog  |   bricks
 AIR  --  mud  -- FIRE
soda water |   tequila
         WATER
 -- with thanks to fortune
[signature.asc (application/pgp-signature, inline)]

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

Acknowledgement sent to Junichi Uekawa <dancer@netfort.gr.jp>:
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 #185 received at 250202@bugs.debian.org (full text, mbox):

From: Junichi Uekawa <dancer@netfort.gr.jp>
To: dpatch-maintainers@lists.alioth.debian.org, cdbs@packages.debian.org, dbs@packages.debian.org
Cc: 250202@bugs.debian.org
Subject: Standardizing make target for 'patch' and 'upstream-source'
Date: Sat, 26 Mar 2005 08:54:32 +0900
[Message part 1 (text/plain, inline)]
Hi,

I'd like to be able to obtain Debian source (patched / unpatched) 
and I would like to know if it's possible to create a standardized 
alias at least for dbs/cdbs/dpatch.

My understanding is that currently the targets are:

	unpack upstream,   apply Debian patch
dbs:    source.build,      source.make
cdbs:   pre-build,         apply-patches
dpatch: already done,      'patch' target


I'm considering of adding
 debian-unpack-upstream/debian-apply-patch
aliases to the above targets.


Would that be feasible?



regards,
	junichi
-- 
Junichi Uekawa, Debian Developer
17D6 120E 4455 1832 9423  7447 3059 BF92 CD37 56F4
http://www.netfort.gr.jp/~dancer/
[Message part 2 (application/pgp-signature, inline)]

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

Acknowledgement sent to Brendan O'Dea <bod@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 #190 received at 250202@bugs.debian.org (full text, mbox):

From: Brendan O'Dea <bod@debian.org>
To: Junichi Uekawa <dancer@netfort.gr.jp>, 250202@bugs.debian.org
Cc: dpkg-dev@packages.debian.org, Colin Walters <walters@debian.org>, Adam Heath <doogie@debian.org>
Subject: Re: Bug#250202: Standardizing make target for 'patch' and 'upstream-source'
Date: Wed, 30 Mar 2005 15:47:25 +1000
On Sat, Mar 26, 2005 at 08:54:32AM +0900, Junichi Uekawa wrote:
>I'd like to be able to obtain Debian source (patched / unpatched)
>and I would like to know if it's possible to create a standardized
>alias at least for dbs/cdbs/dpatch.
>
>My understanding is that currently the targets are:
>
>	unpack upstream,   apply Debian patch
>dbs:    source.build,      source.make
>cdbs:   pre-build,         apply-patches
>dpatch: already done,      'patch' target
>
>
>I'm considering of adding
> debian-unpack-upstream/debian-apply-patch
>aliases to the above targets.

The current proliferation of build systems stems from deficiencies in
dpkg-source.

Requiring the build-dependencies to be installed simply to unpack the
patched source is just as irritating as having to intuit exactly which
rule to use to unpack the upstream source.  There being times when you
want to simply look at the source to determine where a problem may lie
without necessarily building it.

If any change to debian-policy were to be made I'd prefer that the
comment in C.3[0] that the .orig was a "`tar' file containing the source
code from the upstream authors" clarified the meaning of "containing".

My interpretation would be that the .orig.tar.gz *was* the upstream
tarball, renamed or at most unpacked into a .orig directory and repacked
as .tar.gz if upstream uses a different format (.zip, .bz2) or doesn't
unpack into an appropriately named top-level directory.

That is, as opposed to a .orig.tar.gz which contains the upstream
somewhere, which I tend to think is stretching the definition a bit.
YMMV.

I suggest this bug be reassigned as a wishlist to dpkg-dev, for
dpk-source be enhanced to deal with multiple separate patches, upstream
tarballs and so on.

Such enhancements have been suggested[0], although to-date nothing has
materialised, partly because such suggestions have been discouraged[1]
since there is apparently a work-in-progress on dpkg-source v2.

Unfortunately, this work-in-progress has yet to surface (or if it has,
the details have escaped my notice).

Adam Heath reportedly has something at least partially working, and put
a link to some details to the #debian-devel /topic a little while
ago--it seems he's using it to build the xen packages.

Adam:  would you be so kind as to provide a little more detail as to
what's in the works?  Some indication as to whether or not this will see
the light of day within a Debian release cycle would also be nice.

In the absence of details, or an even partial implementation I can only
see the current (ab)usage of build systems continue.

Shoot, I might just write a "dpkg-source -b" replacement myself to
replace my current manual process of patch management.

--bod

[0] Yes, I appreciate that this is an appendix and not strictly policy.
[1] http://lists.debian.org/debian-devel/2002/07/msg01146.html is the
    last I recall, there are almost certainly more.

[2] http://lists.debian.org/debian-devel/2002/07/msg01321.html



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

Acknowledgement sent to David Schmitt <david@schmitt.edv-bus.at>:
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 #195 received at 250202@bugs.debian.org (full text, mbox):

From: David Schmitt <david@schmitt.edv-bus.at>
To: debian-dpkg@lists.debian.org
Cc: Brendan O'Dea <bod@debian.org>, Junichi Uekawa <dancer@netfort.gr.jp>, 250202@bugs.debian.org, dpkg-dev@packages.debian.org, Colin Walters <walters@debian.org>, Adam Heath <doogie@debian.org>
Subject: Re: Bug#250202: Standardizing make target for 'patch' and 'upstream-source'
Date: Wed, 30 Mar 2005 11:37:15 +0200
On Wednesday 30 March 2005 07:47, Brendan O'Dea wrote:
> In the absence of details, or an even partial implementation I can only
> see the current (ab)usage of build systems continue.
>
> Shoot, I might just write a "dpkg-source -b" replacement myself to
> replace my current manual process of patch management.

If one consideres the proliferation of build-systems as a sign for the need of 
different people to handle patch-management differently (compare to the 
various build systems besides debhelper) then a simple dpkg-source -b 
probably won't make the cut for everyone. 

Debians build system always had the nice property that it specified a very 
rigid, rich and reliable interface whithout presuming anything about the 
implementation. 

As a minimalistic approach in this tradition, we should identify what is 
needed(1) by the users of a source package and how this can be interfaced(2) 
on a very high level. Implementation(3) can then be done in the individual 
patch management systems as appropriate.

(1) Needs
---------

Users of a source package need the unpacked source not ready for compilation, 
but ready for inspection and modification. The two major use cases are 
application of (minor) local modifications (security fixes, compile time 
options) and manual or automated inspection of the sourcecode (auditing, 
searching).

This should be possible without installing additional packages besides 
dpkg-dev.

(2) Interface
-------------

To prepare the sourcecode for inspection and/or minor modifications an 
additional argument for debian/rules would fit well into the current model. 

Calling "debian/rules prepare" should leave the tree in a state where the 
source is unpacked, all patches are applied and any change to the tree would 
affect the final binaries.

This target should execute without any Build-Depends installed. Though - as a 
intermediate step - it would be appropriate to error out with a appropriate 
message explaining the needed packages and steps to manually prepare the 
source.

(3) Implementation
------------------

For most patch systems the prepare target can be easily implemented by 
depending on the appropriate patch targets. Some care has to be taken to 
supply the needed code to be independant of the Build-Depends.

"dpkg-source -x" should not default to "prepare"-ing the source since this is 
automatically done for building anyways and would be bad security practice.




Regards, David




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

Acknowledgement sent to Junichi Uekawa <dancer@netfort.gr.jp>:
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 #200 received at 250202@bugs.debian.org (full text, mbox):

From: Junichi Uekawa <dancer@netfort.gr.jp>
To: David Schmitt <david@schmitt.edv-bus.at>
Cc: debian-dpkg@lists.debian.org, Brendan O'Dea <bod@debian.org>, Junichi Uekawa <dancer@netfort.gr.jp>, 250202@bugs.debian.org, dpkg-dev@packages.debian.org, Colin Walters <walters@debian.org>, Adam Heath <doogie@debian.org>
Subject: Re: Bug#250202: Standardizing make target for 'patch' and 'upstream-source'
Date: Thu, 31 Mar 2005 22:51:04 +0900
Hi,

Thanks for getting up a very nice summary.

> If one consideres the proliferation of build-systems as a sign for the need of 
> different people to handle patch-management differently (compare to the 
> various build systems besides debhelper) then a simple dpkg-source -b 
> probably won't make the cut for everyone. 

I agree to your point; I don't think it will be an end-all to 
have a dpkg supporting multiple source.

Considering the freedom of implementation and cost of implementation;
I am thinking that a common-alias target for preparing the debian patched
source code is the best.

As a transition period, I am evaluating whether it is feasible 
to prepare a list of commands required for each package to be 
unpacked and patched.


regards,
	junichi


-- 
Junichi Uekawa, Debian Developer
17D6 120E 4455 1832 9423  7447 3059 BF92 CD37 56F4
http://www.netfort.gr.jp/~dancer/



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

Acknowledgement sent to Scott James Remnant <scott@netsplit.com>:
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 #205 received at 250202@bugs.debian.org (full text, mbox):

From: Scott James Remnant <scott@netsplit.com>
To: Debian Developers <debian-devel@lists.debian.org>, 250202@bugs.debian.org, Dpkg Development <debian-dpkg@lists.debian.org>
Cc: Brendan O'Dea <bod@debian.org>, Junichi Uekawa <dancer@netfort.gr.jp>
Subject: Re: Bug#250202: Standardizing make target for 'patch' and 'upstream-source'
Date: Fri, 01 Apr 2005 01:12:53 +0100
[Message part 1 (text/plain, inline)]
On Wed, 2005-03-30 at 11:37 +0200, David Schmitt wrote:

> To prepare the sourcecode for inspection and/or minor modifications an 
> additional argument for debian/rules would fit well into the current model. 
> 
> Calling "debian/rules prepare" should leave the tree in a state where the 
> source is unpacked, all patches are applied and any change to the tree would 
> affect the final binaries.
> 
> This target should execute without any Build-Depends installed. Though - as a 
> intermediate step - it would be appropriate to error out with a appropriate 
> message explaining the needed packages and steps to manually prepare the 
> source.
> 
I was initially thinking along these lines myself
<http://www.dpkg.org/NewSourceFormat>, however I'm now starting to lean
towards not allowing arbitrary shell to just open up a source package;
it doesn't "feel" safe enough.

I also don't want to break "cd source-version" as the definitive way to
get to the source afterwards, and am not currently sure how to do that
with packages containing multiple tarballs.

There's also the issue of how do you clean or put a source package back
together, when it's got the patches all applied -- how do you know which
patch any modifications should go into?

Scott
-- 
Have you ever, ever felt like this?
Had strange things happen?  Are you going round the twist?
[signature.asc (application/pgp-signature, inline)]

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

Acknowledgement sent to David Schmitt <david@schmitt.edv-bus.at>:
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 #210 received at 250202@bugs.debian.org (full text, mbox):

From: David Schmitt <david@schmitt.edv-bus.at>
To: debian-dpkg@lists.debian.org
Cc: 250202@bugs.debian.org, debian-devel@lists.debian.org
Subject: Re: Bug#250202: Standardizing make target for 'patch' and 'upstream-source'
Date: Fri, 1 Apr 2005 13:39:59 +0200
[Cc:s trimmed. Probably should go to -dpkg]

On Friday 01 April 2005 02:12, Scott James Remnant wrote:
> On Wed, 2005-03-30 at 11:37 +0200, David Schmitt wrote:
> > To prepare the sourcecode for inspection and/or minor modifications an
> > additional argument for debian/rules would fit well into the current
> > model.
> >
> > Calling "debian/rules prepare" should leave the tree in a state where the
> > source is unpacked, all patches are applied and any change to the tree
> > would affect the final binaries.
> >
> > This target should execute without any Build-Depends installed. Though -
> > as a intermediate step - it would be appropriate to error out with a
> > appropriate message explaining the needed packages and steps to manually
> > prepare the source.
>
> I was initially thinking along these lines myself
> <http://www.dpkg.org/NewSourceFormat>, however I'm now starting to lean
> towards not allowing arbitrary shell to just open up a source package;
> it doesn't "feel" safe enough.

As I wrote in my summary:

> "dpkg-source -x" should not default to "prepare"-ing the source since this 
> is automatically done for building anyways and would be bad security 
> practice.  

In the case of "trusted" sources, "dpkg-source --prepare -x *.dsc" can be 
implemented/used. In the case of untrusted source, the packages has to be 
examined regardless of what you want to with it (inspection, modification, 
build). Therefore I think this is a balanced compromise between security and 
flexibility.

> I also don't want to break "cd source-version" as the definitive way to
> get to the source afterwards, and am not currently sure how to do that
> with packages containing multiple tarballs.

Currently, "cd $source-$version" is not /the/ definitive way. If it were, we 
wouldn't have this discussion. 

> There's also the issue of how do you clean or put a source package back
> together, when it's got the patches all applied -- how do you know which
> patch any modifications should go into?

I wrote:
> Calling "debian/rules prepare" should leave the tree in a state where the 
> source is unpacked, all patches are applied and any change to the tree would 
> affect the final binaries.

How this is implemented, is left to the build system.

My underlying workflow assumptions for local modifications:

1$ dpkg-source --prepare -x foo_1.dsc
2$ cp foo-1 foo-1.prepared
3$ (cd foo-1; [apply needed modifications])
4$ diff -ru foo-1.prepared foo-1 > foo-mods.patch
5$ (cd foo-1; fakeroot ./debian/rules binary)

I recognise that this approach wouldn't work for e.g. official Security NMUs.
Though foo-mods.patch should already be quite near the format needed for the 
build systems. Automating 2$ and 4$ integrated with the build system could 
combine them into one step before build and add the patch as last patch in 
the chain to the package.

Working with a package - as opposed to applying a small local/security patch - 
would require a more intimate familarity with the build system anyways.



Regards, David
-- 
- hallo... wie gehts heute?
- *hust* gut *rotz* *keuch*
- gott sei dank kommunizieren wir über ein septisches medium ;)
 -- Matthias Leeb, Uni f. angewandte Kunst, 2005-02-15



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

Acknowledgement sent to Michael Banck <mbanck@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 #215 received at 250202@bugs.debian.org (full text, mbox):

From: Michael Banck <mbanck@debian.org>
To: Debian Developers <debian-devel@lists.debian.org>, 250202@bugs.debian.org, Dpkg Development <debian-dpkg@lists.debian.org>
Subject: Re: Bug#250202: Standardizing make target for 'patch' and 'upstream-source'
Date: Sat, 2 Apr 2005 01:55:58 +0200
On Fri, Apr 01, 2005 at 01:12:53AM +0100, Scott James Remnant wrote:
> On Wed, 2005-03-30 at 11:37 +0200, David Schmitt wrote:
> 
> > To prepare the sourcecode for inspection and/or minor modifications an 
> > additional argument for debian/rules would fit well into the current model. 
> > 
> > Calling "debian/rules prepare" should leave the tree in a state where the 
> > source is unpacked, all patches are applied and any change to the tree would 
> > affect the final binaries.
> > 
> > This target should execute without any Build-Depends installed. Though - as a 
> > intermediate step - it would be appropriate to error out with a appropriate 
> > message explaining the needed packages and steps to manually prepare the 
> > source.
> > 
> I was initially thinking along these lines myself
> <http://www.dpkg.org/NewSourceFormat>, however I'm now starting to lean
> towards not allowing arbitrary shell to just open up a source package;
> it doesn't "feel" safe enough.
> 
> I also don't want to break "cd source-version" as the definitive way to
> get to the source afterwards, and am not currently sure how to do that
> with packages containing multiple tarballs.
> 
> There's also the issue of how do you clean or put a source package back
> together, when it's got the patches all applied -- how do you know which
> patch any modifications should go into?

The variance of different build systems present and the strong feelings
DDs have about them is indication that there might not be the
build-system-to-rule-them-all any time soon.  Your proposal definetely
sounds good (especially the "upload patches individually" part), but it
I guess some time will be needed to shake out the problems (after all,
*every* package up to xfree86 will have to be usefully hackable with it)
and transition to it.


In the meantime, having common targets to get to the source (i.e.
"unpack the source(s)", "patch the source(s)", "do both") seems very
desirable to me, this would help when looking at OPP[1]. IMHO, those
targets should be easy words, like "unpack", "patch", "setup", but I
don't care a lot about them as long as we decide on one.

The issue with how to get patches into your new package is not that
important I think, as this is usually rather straight-forward from
looking at what's in debian/patches already.  Also, the 'clean' target
should unapply any patches, so there's no pressing need to have a common
unpatch target (but it wouldn't hurt I guess).


cheers,

Michael

[1] Other People's Packages
-- 
<HostingGeek> i am thinking of a smart way of exploiting it and once i
        do it will be on slashdot
<ross> WOW SLASHDOT
<HostingGeek> ross: well slashdot take any peace of junk



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

Acknowledgement sent to David Schmitt <david@schmitt.edv-bus.at>:
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 #220 received at 250202@bugs.debian.org (full text, mbox):

From: David Schmitt <david@schmitt.edv-bus.at>
To: debian-dpkg@lists.debian.org
Cc: Scott James Remnant <scott@netsplit.com>, Debian Developers <debian-devel@lists.debian.org>, 250202@bugs.debian.org, Brendan O'Dea <bod@debian.org>, Junichi Uekawa <dancer@netfort.gr.jp>
Subject: Re: Bug#250202: Standardizing make target for 'patch' and 'upstream-source'
Date: Sun, 3 Apr 2005 23:10:19 +0200
On Friday 01 April 2005 02:12, Scott James Remnant wrote:
> I was initially thinking along these lines myself
> <http://www.dpkg.org/NewSourceFormat>, however I'm now starting to lean
> towards not allowing arbitrary shell to just open up a source package;
> it doesn't "feel" safe enough.
>
> I also don't want to break "cd source-version" as the definitive way to
> get to the source afterwards, and am not currently sure how to do that
> with packages containing multiple tarballs.
>
> There's also the issue of how do you clean or put a source package back
> together, when it's got the patches all applied -- how do you know which
> patch any modifications should go into?

Adam Heath claims to have a dbs-ng prototype which does "the right thing".

See http://lists.debian.org/debian-devel/2005/04/msg00062.html


Regards, David
-- 
- hallo... wie gehts heute?
- *hust* gut *rotz* *keuch*
- gott sei dank kommunizieren wir über ein septisches medium ;)
 -- Matthias Leeb, Uni f. angewandte Kunst, 2005-02-15



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

Acknowledgement sent to Junichi Uekawa <dancer@netfort.gr.jp>:
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 #225 received at 250202@bugs.debian.org (full text, mbox):

From: Junichi Uekawa <dancer@netfort.gr.jp>
To: debian-devel@lists.debian.org
Cc: 250202@bugs.debian.org
Subject: Re: intend-to-implement: script to obtain Debian Source
Date: Tue, 12 Apr 2005 22:29:10 +0900
> > unpack: some packages unpack the upstream tarball, some do patching
> > patch: some patch the source tree, some generate patch out of it.
> 2. A policy on what target to have for optional unpacking and patching,
>   and apply a recommendation that is enforced on etch/etch+1
> 
>   That should probably not be unpack/patch since they break existing 
>   makefiles, and as #250202 suggests, unpacked and patched seem to be 
>   good candidates.
> 
>   I'm going to check the output of 
> 
>   make -f debian/rules -n -p |  grep '^[^ ]\+:' | grep -v '^#' 
> 
>   to make sure what targets don't exist.


I've found out that the status is :

patched -- unused
unpacked -- used
unpack -- used 
patch --used


I've used the following script to find out what kind of targets
we have in Debian:


#!/bin/bash

# a script to check debian/rules make targets for all distribution.
cd /mnt/120g-1/dancer/debian-source/sources
ls -1 | while read A; do 
	echo $A;
	( 
	    ulimit -u 200
	    ulimit -t 20
	    cd $A/$A-*/ && make -f debian/rules -n -p | grep '^[^ ]\+:' | grep -v '^#' 
	) > rules/$A  < /dev/null
done



regards,
	junichi



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

Acknowledgement sent to Bill Allombert <allomber@math.u-bordeaux.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 #230 received at 250202@bugs.debian.org (full text, mbox):

From: Bill Allombert <allomber@math.u-bordeaux.fr>
To: Junichi Uekawa <dancer@netfort.gr.jp>, 250202@bugs.debian.org
Cc: debian-devel@lists.debian.org
Subject: Re: Bug#250202: intend-to-implement: script to obtain Debian Source
Date: Tue, 12 Apr 2005 21:52:01 +0200
On Tue, Apr 12, 2005 at 10:29:10PM +0900, Junichi Uekawa wrote:
> > > unpack: some packages unpack the upstream tarball, some do patching
> > > patch: some patch the source tree, some generate patch out of it.
> > 2. A policy on what target to have for optional unpacking and patching,
> >   and apply a recommendation that is enforced on etch/etch+1
> > 
> >   That should probably not be unpack/patch since they break existing 
> >   makefiles, and as #250202 suggests, unpacked and patched seem to be 
> >   good candidates.
> > 
> >   I'm going to check the output of 
> > 
> >   make -f debian/rules -n -p |  grep '^[^ ]\+:' | grep -v '^#' 
> > 
> >   to make sure what targets don't exist.
> 
> 
> I've found out that the status is :
> 
> patched -- unused
> unpacked -- used
> unpack -- used 
> patch --used

I am not sure it is relevant, but there is two way to use dpatch:
either you make clean depend on patch or on unpatch. If clean
depend on patch, then every patches are already applied when running
dpkg-source -x so you don't need to run debian/rules patch. Some
packages actually do that.

Maybe you want to check that.

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#250202; Package debian-policy. Full text and rfc822 format available.

Acknowledgement sent to Wouter Verhelst <wouter@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 #235 received at 250202@bugs.debian.org (full text, mbox):

From: Wouter Verhelst <wouter@debian.org>
To: 250202@bugs.debian.org
Cc: ballombe@debian.org, jdg@polya.uklinux.net
Subject: Alternate proposal
Date: Tue, 26 Apr 2005 11:32:17 +0200
Hi,

There have been two suggestions to fix this issue:
* Mandate common names for debian/rules targets,
* Use a debian/README.source to document used debian/rules targets.

At first sight, these seem to be conflicting, especially if one
considers Bill's objection to suggesting names. However, as I understand
Bill, his main problem is with the fact that suggesting names might make
it sound like a good idea to use such targets. After thinking about this
problem, however, I made an attempt to write a paragraph, the language
of which makes it clear that it is /not/ a good idea to create such a
package, but if one really has to, yada yada.

That being said, a recent post on -devel by Lars Wirzenius[1] made me
realize that this problem is about more than (c)dbs; thus, I've changed
the concept to make it broader.

I'm hereby rescinding all previous proposals I made on #250202, to
replace them with the following:

--- policy.sgml.orig	2005-04-26 11:02:02.000000000 +0200
+++ policy.sgml	2005-04-26 11:28:10.000000000 +0200
@@ -2098,6 +2098,43 @@
 	  the file to the list in <file>debian/files</file>.</p>
       </sect>
 
+      <sect id="readmesource">
+        <heading>Source package handling: <file>debian/README.source</file></heading>
+	<p>
+	  It is assumed that for any Debian package, by running
+	  <prgn>dpkg-source -x</prgn> one can edit files in the
+	  package and build a modified version. This is a good thing;
+	  it allows people not familiar with the package to easily
+	  edit it to prepare non-maintainer uploads, security uploads,
+	  or local modified versions; it also easily allows people to
+	  automatedly audit the source, or to generate statistics over
+	  a large portion of the source packages in the
+	  archive. Maintainers should, therefore, try to avoid doing
+	  anything which might break this assumption.</p>
+	<p>
+	  If, even after this warning, a maintainer still chooses to
+	  do so by either creating the layout of the source package
+	  such that running <prgn>dpkg-source -x</prgn> does not
+	  render editable source, or by managing files anywhere in the
+	  package in such a way that running
+	  <prgn>dpkg-buildpackage</prgn> may overwrite changes, then
+	  they should create a file <file>debian/README.source</file>
+	  documenting the way the source package is structured; such a
+	  file would typically explain to someone not familiar with
+	  the package how to create a modified version of the
+	  package. It would also document any gotchas one might
+	  encounter.</p>
+	<p>
+	  In addition, maintainers should create a target
+	  <tt>source</tt> to the <prgn>debian/rules</prgn> file. This
+	  target, if present, should unpack source archives, apply
+	  patches, generate files, and generally prepare the unpacked
+	  source package to modification. Running <prgn>debian/rules
+	  binary</prgn> after <prgn>debian/rules source</prgn>
+	  <em>must not</em> erase any changes, and it must also not
+	  fail.
+	</p>
+
     </chapt>
 
I think this wording is discouraging enough towards using tarballs in
source packages, while OTOH still allowing it *and* requesting people to
document anything out of the ordinary. I think this is a compromise that
includes all viewpoints, but I'm of course open to other suggestions.

I'm looking for seconds.

[1] http://lists.debian.org/debian-devel/2005/04/msg01006.html

-- 
The amount of time between slipping on the peel and landing on the
pavement is precisely one bananosecond



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

Acknowledgement sent to Frank Lichtenheld <djpig@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 #240 received at 250202@bugs.debian.org (full text, mbox):

From: Frank Lichtenheld <djpig@debian.org>
To: Wouter Verhelst <wouter@debian.org>, 250202@bugs.debian.org
Cc: ballombe@debian.org, jdg@polya.uklinux.net
Subject: Re: Bug#250202: Alternate proposal
Date: Tue, 26 Apr 2005 13:26:41 +0200
On Tue, Apr 26, 2005 at 11:32:17AM +0200, Wouter Verhelst wrote:
> +	  In addition, maintainers should create a target
> +	  <tt>source</tt> to the <prgn>debian/rules</prgn> file. This
> +	  target, if present, should unpack source archives, apply
> +	  patches, generate files, and generally prepare the unpacked
> +	  source package to modification. Running <prgn>debian/rules
> +	  binary</prgn> after <prgn>debian/rules source</prgn>
> +	  <em>must not</em> erase any changes, and it must also not
> +	  fail.

What has happened to the concerns that were mentioned at the beginning
of the discussion to not make many packages instantly buggy?
(Apart from that fact I agree with the proposal, just for the record)

Gruesse,
-- 
Frank Lichtenheld <djpig@debian.org>
www: http://www.djpig.de/



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

Acknowledgement sent to Wouter Verhelst <wouter@grep.be>:
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 #245 received at 250202@bugs.debian.org (full text, mbox):

From: Wouter Verhelst <wouter@grep.be>
To: Frank Lichtenheld <djpig@debian.org>
Cc: 250202@bugs.debian.org, ballombe@debian.org, jdg@polya.uklinux.net
Subject: Re: Bug#250202: Alternate proposal
Date: Tue, 26 Apr 2005 14:37:34 +0200
On Tue, Apr 26, 2005 at 01:26:41PM +0200, Frank Lichtenheld wrote:
> On Tue, Apr 26, 2005 at 11:32:17AM +0200, Wouter Verhelst wrote:
> > +	  In addition, maintainers should create a target
> > +	  <tt>source</tt> to the <prgn>debian/rules</prgn> file. This
> > +	  target, if present, should unpack source archives, apply
> > +	  patches, generate files, and generally prepare the unpacked
> > +	  source package to modification. Running <prgn>debian/rules
> > +	  binary</prgn> after <prgn>debian/rules source</prgn>
> > +	  <em>must not</em> erase any changes, and it must also not
> > +	  fail.
> 
> What has happened to the concerns that were mentioned at the beginning
> of the discussion to not make many packages instantly buggy?

Both cases where I used 'must' do not make packages instantly buggy,
since they only apply to the 'source' target (that is the idea, at
least; if the wording isn't clear enough, I may need to fix that). If
you don't have that target, you don't have to comply with the must. The
'source' target is a 'should', so a package that does not currently have
this target isn't buggy at all.

> (Apart from that fact I agree with the proposal, just for the record)

Is that a formal second?

(if so, please sign the mail)

-- 
The amount of time between slipping on the peel and landing on the
pavement is precisely one bananosecond



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

Acknowledgement sent to Jeroen van Wolffelaar <jeroen@wolffelaar.nl>:
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 #250 received at 250202@bugs.debian.org (full text, mbox):

From: Jeroen van Wolffelaar <jeroen@wolffelaar.nl>
To: 250202@bugs.debian.org
Subject: Re: Bug#250202: Alternate proposal
Date: Tue, 26 Apr 2005 15:37:48 +0200
On Tue, Apr 26, 2005 at 11:32:17AM +0200, Wouter Verhelst wrote:
> I'm hereby rescinding all previous proposals I made on #250202, to
> replace them with the following:
> 
> --- policy.sgml.orig	2005-04-26 11:02:02.000000000 +0200
> +++ policy.sgml	2005-04-26 11:28:10.000000000 +0200
> (...)
>  
> I think this wording is discouraging enough towards using tarballs in
> source packages, while OTOH still allowing it *and* requesting people to
> document anything out of the ordinary. I think this is a compromise that
> includes all viewpoints, but I'm of course open to other suggestions.
> 
> I'm looking for seconds.

Seconded.

(Do we really need to sign seconds to policy proposals? If you do
insist, I will, but I prefer not to need to go through the hassle)

--Jeroen

-- 
Jeroen van Wolffelaar
Jeroen@wolffelaar.nl (also for Jabber & MSN; ICQ: 33944357)
http://Jeroen.A-Eskwadraat.nl



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

Acknowledgement sent to Frank Lichtenheld <djpig@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 #255 received at 250202@bugs.debian.org (full text, mbox):

From: Frank Lichtenheld <djpig@debian.org>
To: Wouter Verhelst <wouter@grep.be>
Cc: 250202@bugs.debian.org, ballombe@debian.org, jdg@polya.uklinux.net
Subject: Re: Bug#250202: Alternate proposal
Date: Tue, 26 Apr 2005 16:07:01 +0200
On Tue, Apr 26, 2005 at 02:37:34PM +0200, Wouter Verhelst wrote:
> On Tue, Apr 26, 2005 at 01:26:41PM +0200, Frank Lichtenheld wrote:
> > On Tue, Apr 26, 2005 at 11:32:17AM +0200, Wouter Verhelst wrote:
> > > +	  In addition, maintainers should create a target
> > > +	  <tt>source</tt> to the <prgn>debian/rules</prgn> file. This
> > > +	  target, if present, should unpack source archives, apply
> > > +	  patches, generate files, and generally prepare the unpacked
> > > +	  source package to modification. Running <prgn>debian/rules
> > > +	  binary</prgn> after <prgn>debian/rules source</prgn>
> > > +	  <em>must not</em> erase any changes, and it must also not
> > > +	  fail.
> > 
> > What has happened to the concerns that were mentioned at the beginning
> > of the discussion to not make many packages instantly buggy?
> 
> Both cases where I used 'must' do not make packages instantly buggy,
> since they only apply to the 'source' target (that is the idea, at
> least; if the wording isn't clear enough, I may need to fix that). If
> you don't have that target, you don't have to comply with the must. The
> 'source' target is a 'should', so a package that does not currently have
> this target isn't buggy at all.

Yeah, but I know quite a few older packages that contain a snippet like:
source diff:
        @echo >&2 'source and diff are obsolete - use dpkg-source -b'; false

Don't know why, this must be way before my time in Debian...
It would be good to check for the amount of packages affected by that nevertheless.

> > (Apart from that fact I agree with the proposal, just for the record)
> 
> Is that a formal second?

Not (yet).

Gruesse,
-- 
Frank Lichtenheld <djpig@debian.org>
www: http://www.djpig.de/



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

Acknowledgement sent to Wouter Verhelst <wouter@grep.be>:
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 #260 received at 250202@bugs.debian.org (full text, mbox):

From: Wouter Verhelst <wouter@grep.be>
To: Frank Lichtenheld <djpig@debian.org>
Cc: 250202@bugs.debian.org, ballombe@debian.org, jdg@polya.uklinux.net
Subject: Re: Bug#250202: Alternate proposal
Date: Tue, 26 Apr 2005 16:14:07 +0200
On Tue, Apr 26, 2005 at 04:07:01PM +0200, Frank Lichtenheld wrote:
> On Tue, Apr 26, 2005 at 02:37:34PM +0200, Wouter Verhelst wrote:
> > Both cases where I used 'must' do not make packages instantly buggy,
> > since they only apply to the 'source' target (that is the idea, at
> > least; if the wording isn't clear enough, I may need to fix that). If
> > you don't have that target, you don't have to comply with the must. The
> > 'source' target is a 'should', so a package that does not currently have
> > this target isn't buggy at all.
> 
> Yeah, but I know quite a few older packages that contain a snippet like:
> source diff:
>         @echo >&2 'source and diff are obsolete - use dpkg-source -b'; false

Oh, right, forgot about that one. Overloading that would certainly not
be a good idea.

Hm.

> Don't know why, this must be way before my time in Debian...
> It would be good to check for the amount of packages affected by that nevertheless.

True. What I'm looking for is something unique; so 'source' is clearly
right out. Perhaps 'edit' could be better, or 'finish'. Suggestions are
most certainly welcome.

-- 
The amount of time between slipping on the peel and landing on the
pavement is precisely one bananosecond



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

Acknowledgement sent to Andreas Barth <aba@not.so.argh.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 #265 received at 250202@bugs.debian.org (full text, mbox):

From: Andreas Barth <aba@not.so.argh.org>
To: Wouter Verhelst <wouter@grep.be>, 250202@bugs.debian.org
Cc: Frank Lichtenheld <djpig@debian.org>, ballombe@debian.org, jdg@polya.uklinux.net
Subject: Re: Bug#250202: Alternate proposal
Date: Tue, 26 Apr 2005 17:10:21 +0200
[Message part 1 (text/plain, inline)]
* Wouter Verhelst (wouter@grep.be) [050426 15:10]:
> On Tue, Apr 26, 2005 at 01:26:41PM +0200, Frank Lichtenheld wrote:
> > On Tue, Apr 26, 2005 at 11:32:17AM +0200, Wouter Verhelst wrote:
> > > +	  In addition, maintainers should create a target
> > > +	  <tt>source</tt> to the <prgn>debian/rules</prgn> file. This
> > > +	  target, if present, should unpack source archives, apply
> > > +	  patches, generate files, and generally prepare the unpacked
> > > +	  source package to modification. Running <prgn>debian/rules
> > > +	  binary</prgn> after <prgn>debian/rules source</prgn>
> > > +	  <em>must not</em> erase any changes, and it must also not
> > > +	  fail.
> > 
> > What has happened to the concerns that were mentioned at the beginning
> > of the discussion to not make many packages instantly buggy?
> 
> Both cases where I used 'must' do not make packages instantly buggy,
> since they only apply to the 'source' target (that is the idea, at
> least; if the wording isn't clear enough, I may need to fix that). If
> you don't have that target, you don't have to comply with the must. The
> 'source' target is a 'should', so a package that does not currently have
> this target isn't buggy at all.
> 
> > (Apart from that fact I agree with the proposal, just for the record)
> 
> Is that a formal second?

At least, this here is a formal second :)


Cheers,
Andi
-- 
   http://home.arcor.de/andreas-barth/
   PGP 1024/89FB5CE5  DC F1 85 6D A6 45 9C 0F  3B BE F1 D0 C5 D1 D9 0C
[signature.asc (application/pgp-signature, inline)]

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

Acknowledgement sent to Jeroen van Wolffelaar <jeroen@wolffelaar.nl>:
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 #270 received at 250202@bugs.debian.org (full text, mbox):

From: Jeroen van Wolffelaar <jeroen@wolffelaar.nl>
To: Frank Lichtenheld <djpig@debian.org>, 250202@bugs.debian.org
Cc: Wouter Verhelst <wouter@grep.be>, ballombe@debian.org, jdg@polya.uklinux.net
Subject: Re: Bug#250202: Alternate proposal
Date: Tue, 26 Apr 2005 17:44:21 +0200
On Tue, Apr 26, 2005 at 04:07:01PM +0200, Frank Lichtenheld wrote:
> On Tue, Apr 26, 2005 at 02:37:34PM +0200, Wouter Verhelst wrote:
> > On Tue, Apr 26, 2005 at 01:26:41PM +0200, Frank Lichtenheld wrote:
> > > On Tue, Apr 26, 2005 at 11:32:17AM +0200, Wouter Verhelst wrote:
> > > > +	  In addition, maintainers should create a target
> > > > +	  <tt>source</tt> to the <prgn>debian/rules</prgn> file. This
> > > > +	  target, if present, should unpack source archives, apply
> > > > +	  patches, generate files, and generally prepare the unpacked
> > > > +	  source package to modification. Running <prgn>debian/rules
> > > > +	  binary</prgn> after <prgn>debian/rules source</prgn>
> > > > +	  <em>must not</em> erase any changes, and it must also not
> > > > +	  fail.
> > > 
> > > What has happened to the concerns that were mentioned at the beginning
> > > of the discussion to not make many packages instantly buggy?
> > 
> > Both cases where I used 'must' do not make packages instantly buggy,
> > since they only apply to the 'source' target (that is the idea, at
> > least; if the wording isn't clear enough, I may need to fix that). If
> > you don't have that target, you don't have to comply with the must. The
> > 'source' target is a 'should', so a package that does not currently have
> > this target isn't buggy at all.
> 
> Yeah, but I know quite a few older packages that contain a snippet like:
> source diff:
>         @echo >&2 'source and diff are obsolete - use dpkg-source -b'; false
> 
> Don't know why, this must be way before my time in Debian...
> It would be good to check for the amount of packages affected by that
> nevertheless.

A bit over 1100 source packages, nearly 15% of the archive or something
like that. (curiously, the big majority of them have 65 spaces after the
colon). Guess there was a lot of copy&pasting going on.

Anyway, > 1100 source packages is way too much to suddenly change.
'unpack-source' or something would be a bit more verbose and more
unlikely to clash.
 
> > > (Apart from that fact I agree with the proposal, just for the record)
> > 
> > Is that a formal second?
> 
> Not (yet).

I still second the idea, but think a better actual name for the target
is due.

--Jeroen

-- 
Jeroen van Wolffelaar
Jeroen@wolffelaar.nl (also for Jabber & MSN; ICQ: 33944357)
http://Jeroen.A-Eskwadraat.nl



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

Acknowledgement sent to David Schmitt <david@schmitt.edv-bus.at>:
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 #275 received at 250202@bugs.debian.org (full text, mbox):

From: David Schmitt <david@schmitt.edv-bus.at>
To: Wouter Verhelst <wouter@grep.be>, 250202@bugs.debian.org
Subject: Re: Bug#250202: Alternate proposal
Date: Tue, 26 Apr 2005 19:01:59 +0200
On Tuesday 26 April 2005 16:14, Wouter Verhelst wrote:
> On Tue, Apr 26, 2005 at 04:07:01PM +0200, Frank Lichtenheld wrote:
> > Don't know why, this must be way before my time in Debian...
> > It would be good to check for the amount of packages affected by that
> > nevertheless.
>
> True. What I'm looking for is something unique; so 'source' is clearly
> right out. Perhaps 'edit' could be better, or 'finish'. Suggestions are
> most certainly welcome.

'prepare' ?



Regards, David
-- 
- hallo... wie gehts heute?
- *hust* gut *rotz* *keuch*
- gott sei dank kommunizieren wir über ein septisches medium ;)
 -- Matthias Leeb, Uni f. angewandte Kunst, 2005-02-15



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

Acknowledgement sent to Russ Allbery <rra@stanford.edu>:
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 #280 received at 250202@bugs.debian.org (full text, mbox):

From: Russ Allbery <rra@stanford.edu>
To: 250202@bugs.debian.org
Subject: Re: Bug#250202: Alternate proposal
Date: Tue, 26 Apr 2005 11:57:53 -0700
David Schmitt <david@schmitt.edv-bus.at> writes:
> On Tuesday 26 April 2005 16:14, Wouter Verhelst wrote:

>> True. What I'm looking for is something unique; so 'source' is clearly
>> right out. Perhaps 'edit' could be better, or 'finish'. Suggestions are
>> most certainly welcome.

> 'prepare' ?

dbs, one of the larger contributors to this particular packaging style,
uses "setup", so if "setup" was used all the dbs packages at least would
immediately satisfy the should.

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



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

Acknowledgement sent to Wouter Verhelst <wouter@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 #285 received at 250202@bugs.debian.org (full text, mbox):

From: Wouter Verhelst <wouter@debian.org>
To: Russ Allbery <rra@stanford.edu>, 250202@bugs.debian.org
Subject: Re: Bug#250202: Alternate proposal
Date: Tue, 26 Apr 2005 21:25:12 +0200
On Tue, Apr 26, 2005 at 11:57:53AM -0700, Russ Allbery wrote:
> David Schmitt <david@schmitt.edv-bus.at> writes:
> > On Tuesday 26 April 2005 16:14, Wouter Verhelst wrote:
> 
> >> True. What I'm looking for is something unique; so 'source' is clearly
> >> right out. Perhaps 'edit' could be better, or 'finish'. Suggestions are
> >> most certainly welcome.
> 
> > 'prepare' ?
> 
> dbs, one of the larger contributors to this particular packaging style,
> uses "setup", so if "setup" was used all the dbs packages at least would
> immediately satisfy the should.

Yes, that would be an option; but only if running 'dpkg-buildpackage'
after executing the 'setup' target would not erase any local changes, or
do other unexpected things. I'm not familiar enough with dbs to know
whether this is the case.

That being said, there are other systems, such as cdbs, that have other
defaults. I'm not sure whether it's a good idea to pick one, and ignore
the other -- but I don't really care about that bit, either.

-- 
The amount of time between slipping on the peel and landing on the
pavement is precisely one bananosecond



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

Acknowledgement sent to Russ Allbery <rra@stanford.edu>:
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 #290 received at 250202@bugs.debian.org (full text, mbox):

From: Russ Allbery <rra@stanford.edu>
To: 250202@bugs.debian.org
Subject: Re: Bug#250202: Alternate proposal
Date: Tue, 26 Apr 2005 12:57:56 -0700
Wouter Verhelst <wouter@debian.org> writes:
> On Tue, Apr 26, 2005 at 11:57:53AM -0700, Russ Allbery wrote:

>> dbs, one of the larger contributors to this particular packaging style,
>> uses "setup", so if "setup" was used all the dbs packages at least
>> would immediately satisfy the should.

> Yes, that would be an option; but only if running 'dpkg-buildpackage'
> after executing the 'setup' target would not erase any local changes, or
> do other unexpected things. I'm not familiar enough with dbs to know
> whether this is the case.

As near as I can tell (I'm not very familiar with dbs, having just adopted
a package that uses it but not having used it before that), it would
preserve any local changes.  (Just untarring the upstream source, making
changes, and then building the package would not preserve local changes as
near as I can tell.)

> That being said, there are other systems, such as cdbs, that have other
> defaults. I'm not sure whether it's a good idea to pick one, and ignore
> the other -- but I don't really care about that bit, either.

It looks like the equivalent target in cdbs when running in DBS mode is
"post-patches", although the makefiles are a bit harder for me to follow.
Not as intuitive of a name, but it looks like it's mostly intended to be
an internal generic hook.

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



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

Acknowledgement sent to Junichi Uekawa <dancer@netfort.gr.jp>:
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 #295 received at 250202@bugs.debian.org (full text, mbox):

From: Junichi Uekawa <dancer@netfort.gr.jp>
To: Wouter Verhelst <wouter@debian.org>, 250202@bugs.debian.org
Cc: ballombe@debian.org, jdg@polya.uklinux.net
Subject: Re: Bug#250202: Alternate proposal
Date: Sun, 12 Jun 2005 16:00:17 +0900
Hi,

> That being said, a recent post on -devel by Lars Wirzenius[1] made me
> realize that this problem is about more than (c)dbs; thus, I've changed
> the concept to make it broader.
> 
> I'm hereby rescinding all previous proposals I made on #250202, to
> replace them with the following:

Your proposal met some objections due to the fact that 'source' is an
already widely used keyword; and is in a limbo state although two 
developers already seconded it.

AFAICT, no action has been taken after approx two months.
Care to give an update?



regards,
	junichi

-- 
Junichi Uekawa, Debian Developer   http://www.netfort.gr.jp/~dancer/
183A 70FC 4732 1B87 57A5  CE82 D837 7D4E E81E 55C1 



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

Acknowledgement sent to Wouter Verhelst <wouter@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 #300 received at 250202@bugs.debian.org (full text, mbox):

From: Wouter Verhelst <wouter@debian.org>
To: Junichi Uekawa <dancer@netfort.gr.jp>, 250202@bugs.debian.org
Cc: ballombe@debian.org, jdg@polya.uklinux.net
Subject: Re: Bug#250202: Alternate proposal
Date: Sun, 12 Jun 2005 11:24:04 +0200
[Message part 1 (text/plain, inline)]
On Sun, Jun 12, 2005 at 04:00:17PM +0900, Junichi Uekawa wrote:
> Hi,
> 
> > That being said, a recent post on -devel by Lars Wirzenius[1] made me
> > realize that this problem is about more than (c)dbs; thus, I've changed
> > the concept to make it broader.
> > 
> > I'm hereby rescinding all previous proposals I made on #250202, to
> > replace them with the following:
> 
> Your proposal met some objections due to the fact that 'source' is an
> already widely used keyword; and is in a limbo state although two 
> developers already seconded it.
> 
> AFAICT, no action has been taken after approx two months.
> Care to give an update?

Yes. I would've done so earlier, but I thought it more urgent to work on
helping to get Sarge out the door than to finish up this proposal :-)

Anyway. Thanks to your excellent research in
<87fyxwcee1.dancerj@netfort.gr.jp> in this bug (and your reminder on IRC
that you did this :-), we know that the "patched" target is not used by
any package yet. Thus, I'll modify the proposal that I set out in
<20050426093217.GN4948@country.grep.be> to say the target should be
"patched", rather than "source". For reference, the proposal as it now
reads follows; as always, I'm looking for seconds.

--- policy.sgml.orig	2005-06-12 11:18:28.000000000 +0200
+++ policy.sgml	2005-06-12 11:19:47.000000000 +0200
@@ -2098,6 +2098,43 @@
 	  the file to the list in <file>debian/files</file>.</p>
       </sect>
 
+      <sect id="readmesource">
+        <heading>Source package handling: <file>debian/README.source</file></heading>
+	<p>
+	  It is assumed that for any Debian package, by running
+	  <prgn>dpkg-source -x</prgn> one can edit files in the
+	  package and build a modified version. This is a good thing;
+	  it allows people not familiar with the package to easily
+	  edit it to prepare non-maintainer uploads, security uploads,
+	  or local modified versions; it also easily allows people to
+	  automatedly audit the source, or to generate statistics over
+	  a large portion of the source packages in the
+	  archive. Maintainers should, therefore, try to avoid doing
+	  anything which might break this assumption.</p>
+	<p>
+	  If, even after this warning, a maintainer still chooses to
+	  do so by either creating the layout of the source package
+	  such that running <prgn>dpkg-source -x</prgn> does not
+	  render editable source, or by managing files anywhere in the
+	  package in such a way that running
+	  <prgn>dpkg-buildpackage</prgn> may overwrite changes, then
+	  they should create a file <file>debian/README.source</file>
+	  documenting the way the source package is structured; such a
+	  file would typically explain to someone not familiar with
+	  the package how to create a modified version of the
+	  package. It would also document any gotchas one might
+	  encounter.</p>
+	<p>
+	  In addition, maintainers should create a target
+	  <tt>patched</tt> to the <prgn>debian/rules</prgn> file. This
+	  target, if present, should unpack source archives, apply
+	  patches, generate files, and generally prepare the unpacked
+	  source package to modification. Running <prgn>debian/rules
+	  binary</prgn> after <prgn>debian/rules patched</prgn>
+	  <em>must not</em> erase any changes, and it must also not
+	  fail.
+	</p>
+
     </chapt>

-- 
The amount of time between slipping on the peel and landing on the
pavement is precisely one bananosecond
[signature.asc (application/pgp-signature, inline)]

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

Acknowledgement sent to Bill Allombert <allomber@math.u-bordeaux.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 #305 received at 250202@bugs.debian.org (full text, mbox):

From: Bill Allombert <allomber@math.u-bordeaux.fr>
To: Wouter Verhelst <wouter@debian.org>
Cc: Junichi Uekawa <dancer@netfort.gr.jp>, 250202@bugs.debian.org
Subject: Re: Bug#250202: Alternate proposal
Date: Sun, 12 Jun 2005 13:06:10 +0200
On Sun, Jun 12, 2005 at 11:24:04AM +0200, Wouter Verhelst wrote:
> +	<p>
> +	  If, even after this warning, a maintainer still chooses to
> +	  do so by either creating the layout of the source package
> +	  such that running <prgn>dpkg-source -x</prgn> does not
> +	  render editable source, or by managing files anywhere in the
> +	  package in such a way that running
> +	  <prgn>dpkg-buildpackage</prgn> may overwrite changes, then
> +	  they should create a file <file>debian/README.source</file>
> +	  documenting the way the source package is structured; such a
> +	  file would typically explain to someone not familiar with
> +	  the package how to create a modified version of the
> +	  package. It would also document any gotchas one might
> +	  encounter.</p>
> +	<p>
> +	  In addition, maintainers should create a target
> +	  <tt>patched</tt> to the <prgn>debian/rules</prgn> file. This
> +	  target, if present, should unpack source archives, apply
> +	  patches, generate files, and generally prepare the unpacked
> +	  source package to modification. Running <prgn>debian/rules
> +	  binary</prgn> after <prgn>debian/rules patched</prgn>
> +	  <em>must not</em> erase any changes, and it must also not
> +	  fail.
> +	</p>
> +
>      </chapt>

I would like to make one comment:

There are essentially two ways to use patch systems like dpatch: In
debian/rules have 'clean' depend on 'unpatch' or on 'patch'.  While the
standard way is to depend on 'unpatch', if you make it depends on
'patch', then all patches are applied by "dpkg-source -x" and you don't
need the 'patched' target anymore. The cost on implementing the
'patched' target is higher than fixing the 'clean' dependency.

There are some cases like dbs where this will not work, so 'patched' is
still worthwhile, but before asking the other packages to implement
'patched', we should consider to ask them implementing 'clean: patch'
instead.

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#250202; Package debian-policy. Full text and rfc822 format available.

Acknowledgement sent to Junichi Uekawa <dancer@netfort.gr.jp>:
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 #310 received at 250202@bugs.debian.org (full text, mbox):

From: Junichi Uekawa <dancer@netfort.gr.jp>
To: Bill Allombert <allomber@math.u-bordeaux.fr>
Cc: Wouter Verhelst <wouter@debian.org>, Junichi Uekawa <dancer@netfort.gr.jp>, 250202@bugs.debian.org
Subject: Re: Bug#250202: Alternate proposal
Date: Sun, 12 Jun 2005 20:56:25 +0900
Hi,

> I would like to make one comment:
> 
> There are essentially two ways to use patch systems like dpatch: In
> debian/rules have 'clean' depend on 'unpatch' or on 'patch'.  While the
> standard way is to depend on 'unpatch', if you make it depends on
> 'patch', then all patches are applied by "dpkg-source -x" and you don't
> need the 'patched' target anymore. The cost on implementing the
> 'patched' target is higher than fixing the 'clean' dependency.
> 
> There are some cases like dbs where this will not work, so 'patched' is
> still worthwhile, but before asking the other packages to implement
> 'patched', we should consider to ask them implementing 'clean: patch'
> instead.

Hmm..

There are more packages than dpatch and dbs floating around
in Debian; and I consider it to be a step forward to move this way,
rather than trying to fix each patching script.


regards,
	junichi

-- 
Junichi Uekawa, Debian Developer   http://www.netfort.gr.jp/~dancer/
183A 70FC 4732 1B87 57A5  CE82 D837 7D4E E81E 55C1 



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

Acknowledgement sent to Bill Allombert <allomber@math.u-bordeaux.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 #315 received at 250202@bugs.debian.org (full text, mbox):

From: Bill Allombert <allomber@math.u-bordeaux.fr>
To: Junichi Uekawa <dancer@netfort.gr.jp>, 250202@bugs.debian.org
Cc: Wouter Verhelst <wouter@debian.org>
Subject: Re: Bug#250202: Alternate proposal
Date: Sun, 12 Jun 2005 14:38:46 +0200
On Sun, Jun 12, 2005 at 08:56:25PM +0900, Junichi Uekawa wrote:
> Hi,
> 
> > I would like to make one comment:
> > 
> > There are essentially two ways to use patch systems like dpatch: In
> > debian/rules have 'clean' depend on 'unpatch' or on 'patch'.  While the
> > standard way is to depend on 'unpatch', if you make it depends on
> > 'patch', then all patches are applied by "dpkg-source -x" and you don't
> > need the 'patched' target anymore. The cost on implementing the
> > 'patched' target is higher than fixing the 'clean' dependency.
> > 
> > There are some cases like dbs where this will not work, so 'patched' is
> > still worthwhile, but before asking the other packages to implement
> > 'patched', we should consider to ask them implementing 'clean: patch'
> > instead.
> 
> Hmm..
> 
> There are more packages than dpatch and dbs floating around
> in Debian; and I consider it to be a step forward to move this way,
> rather than trying to fix each patching script.

My fix is not dpatch specific and I wrote " 'patched' is still
worthwhile" for a reason, did not I ?

I am unsure the patched interface is sufficient to make any changes to 
a package: you also need a interface to add new patches, and 'patched'
does not provide any.

Switching to 'clean: patch' allow to make changes the normal way, since
theses changes are 'applied' on top of the package-provided patches
instead of before in the 'clean: unpatch' set up.

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#250202; Package debian-policy. Full text and rfc822 format available.

Acknowledgement sent to Wouter Verhelst <wouter@grep.be>:
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 #320 received at 250202@bugs.debian.org (full text, mbox):

From: Wouter Verhelst <wouter@grep.be>
To: Bill Allombert <allomber@math.u-bordeaux.fr>
Cc: Junichi Uekawa <dancer@netfort.gr.jp>, 250202@bugs.debian.org
Subject: Re: Bug#250202: Alternate proposal
Date: Sun, 12 Jun 2005 16:31:16 +0200
On Sun, Jun 12, 2005 at 01:06:10PM +0200, Bill Allombert wrote:
> There are essentially two ways to use patch systems like dpatch: In
> debian/rules have 'clean' depend on 'unpatch' or on 'patch'.  While the
> standard way is to depend on 'unpatch', if you make it depends on
> 'patch', then all patches are applied by "dpkg-source -x" and you don't
> need the 'patched' target anymore. The cost on implementing the
> 'patched' target is higher than fixing the 'clean' dependency.

I disagree. If the semantics behind 'patch' in dpatch already implement
what the 'patched' target would require, then all that is required is to
add a rule to a makefile which says

patched: patch

and there you go; there's no high cost to implement it this way. This
rule can be added to a debian/rules file, or (better yet) to the dpatch
include files (which would fix it everywhere). If there is no target
that already implements the required semantics for 'patched', then there
indeed is a cost to implement it, but this cost will exist either way.
I don't see how the cost to implement it this way would be higher than
requesting the 'clean' way.

I agree that having a tarball in the unpacked source is not a good idea
anyhow, but the proposal already discourages that (and motivates this
discouragement).

Am I missing something?

-- 
The amount of time between slipping on the peel and landing on the
pavement is precisely one bananosecond



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

Acknowledgement sent to Luk Claes <luk@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 #325 received at 250202@bugs.debian.org (full text, mbox):

From: Luk Claes <luk@debian.org>
To: Wouter Verhelst <wouter@debian.org>, 250202@bugs.debian.org
Cc: Junichi Uekawa <dancer@netfort.gr.jp>, ballombe@debian.org, jdg@polya.uklinux.net
Subject: Re: Bug#250202: Alternate proposal
Date: Mon, 13 Jun 2005 08:10:11 +0200
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Wouter Verhelst wrote:
> On Sun, Jun 12, 2005 at 04:00:17PM +0900, Junichi Uekawa wrote:
> 
>>Hi,

Hi

[...]
> Anyway. Thanks to your excellent research in
> <87fyxwcee1.dancerj@netfort.gr.jp> in this bug (and your reminder on IRC
> that you did this :-), we know that the "patched" target is not used by
> any package yet. Thus, I'll modify the proposal that I set out in
> <20050426093217.GN4948@country.grep.be> to say the target should be
> "patched", rather than "source". For reference, the proposal as it now
> reads follows; as always, I'm looking for seconds.

Count me in.

> --- policy.sgml.orig	2005-06-12 11:18:28.000000000 +0200
> +++ policy.sgml	2005-06-12 11:19:47.000000000 +0200
> @@ -2098,6 +2098,43 @@
>  	  the file to the list in <file>debian/files</file>.</p>
>        </sect>
>  
> +      <sect id="readmesource">
> +        <heading>Source package handling: <file>debian/README.source</file></heading>
> +	<p>
> +	  It is assumed that for any Debian package, by running
> +	  <prgn>dpkg-source -x</prgn> one can edit files in the
> +	  package and build a modified version. This is a good thing;
> +	  it allows people not familiar with the package to easily
> +	  edit it to prepare non-maintainer uploads, security uploads,
> +	  or local modified versions; it also easily allows people to
> +	  automatedly audit the source, or to generate statistics over
> +	  a large portion of the source packages in the
> +	  archive. Maintainers should, therefore, try to avoid doing
> +	  anything which might break this assumption.</p>
> +	<p>
> +	  If, even after this warning, a maintainer still chooses to
> +	  do so by either creating the layout of the source package
> +	  such that running <prgn>dpkg-source -x</prgn> does not
> +	  render editable source, or by managing files anywhere in the
> +	  package in such a way that running
> +	  <prgn>dpkg-buildpackage</prgn> may overwrite changes, then
> +	  they should create a file <file>debian/README.source</file>
> +	  documenting the way the source package is structured; such a
> +	  file would typically explain to someone not familiar with
> +	  the package how to create a modified version of the
> +	  package. It would also document any gotchas one might
> +	  encounter.</p>
> +	<p>
> +	  In addition, maintainers should create a target
> +	  <tt>patched</tt> to the <prgn>debian/rules</prgn> file. This
> +	  target, if present, should unpack source archives, apply
> +	  patches, generate files, and generally prepare the unpacked
> +	  source package to modification. Running <prgn>debian/rules
> +	  binary</prgn> after <prgn>debian/rules patched</prgn>
> +	  <em>must not</em> erase any changes, and it must also not
> +	  fail.
> +	</p>
> +
>      </chapt>
> 

Seconded.

Cheers

Luk
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.1 (GNU/Linux)

iD8DBQFCrSND5UTeB5t8Mo0RAlsrAKDIu/+02TuTusdzPxlMitSWyveugACgxrmm
P3zd/huyybxS3HKOnyQv3xM=
=qEUu
-----END PGP SIGNATURE-----



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

Acknowledgement sent to Sven Mueller <debian@incase.de>:
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 #330 received at 250202@bugs.debian.org (full text, mbox):

From: Sven Mueller <debian@incase.de>
To: 250202-subscribe@bugs.debian.org, 250202@bugs.debian.org
Subject: Re: Bug#250202 [PROPOSAL] "debian/README.source" file for packages with non-trivial source
Date: Wed, 18 Jan 2006 21:48:38 +0100
Hi.

I just wanted to say a few things about this topic, even though the bug
has been inactive for a while.

I notice two things:

Bill (forgive me if I got the name wrong, I didn't re-check before
writing this mail) wants sources to be unpacked by dpkg-source -x in a
way that patches (like those from dpatch) are already applied.
However: There is a problem with the approach he suggested: If I were to
list the "patch" target instead of the "unpatch" target as a dependency
of the "clean" target, the dpatch-patches would end up twice inside the
.diff.gz: Once in debian/patches and once already applied (and in
addition, there would be the tracking data dpatch puts in
debian/patched). Quite the contrary of the cleanup-effect wanted by
using dpatch in the first place.

On the other hand, I can understand why people would like to immediately
see the final, fully patched source tree when they extracted them with
dpkg-source -x, without the need to install anything besides dpkg-source.

But, seeing all the pro's and con's in this bug's log, I would prefer
(as has been suggested) some change to the policy, requiring (or at
least strongly suggesting: should-style rules) suitable documentation of
how to get to the fully unpackged and fully packed source with minimal
additional software. And some documentation how to get own changes to
get built into the package (not overwritten by debian/rules clean).

regards,
Sven



Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#250202; 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 #335 received at 250202@bugs.debian.org (full text, mbox):

From: Russ Allbery <rra@debian.org>
To: 250202@bugs.debian.org, wouter@debian.org
Subject: Re: Bug#250202: "debian/README.source" file for packages with non-trivial source
Date: Tue, 01 Jan 2008 22:54:06 -0800
This is the last Policy bug I had tagged as wording.  It started with a
proposal for a README.source file documenting how to do things with a
package that uses a non-trivial source format, and then expanded into
standardizing debian/rules targets for doing various things.

Having reviewed the entire bug thread, I think there are a few
misconceptions and a few different cases mingled together, so I'm going to
attempt a summary.

The original concern was being able to unpack a Debian source package and
immediately start patching it, with a goal of creating a modified source
package (for local modifications, security fixes, RC bug fixes, or what
have you).  Among the source package formats in Debian, I know of two
possible situations:

dbs-style systems

    A dbs-style system is one in which the .orig.tar.gz file contains an
    archive of the upstream source, rather than an unpacked copy.  After
    extracting a source package that uses one of these systems, one will
    generally have only an upstream source archive and a debian directory.

    In order to start making any modifications, one has to run some
    debian/rules target to unpack the upstream source and apply any
    patches that were shipped in the debian directory (or sometimes
    upstream patches shipped alongside the upstream source in the
    .orig.tar.gz).

    It may be possible in some cases to modify the resulting source and
    then build a binary package without doing any further.  However, in
    order to generate a source package, and probably even to generate a
    binary package unless one uses dpkg-buildpackage -nc, the
    modifications to the upstream source usually have to be saved in the
    form of a patch and put somewhere else in the package to be included
    in the source package and applied properly on build.

Patch systems

    A patch system is less comprehensive in its reorganization of the
    package.  The upstream source is handled in the conventional manner
    and unpacking the Debian source package results in the pristine
    upstream source and a debian directory that contains all the patches
    to be applied (generally in a debian/patches directory).

    *If* the modifications that one wants to make to the package don't
    overlap with any of the changes made by the patches, one can make
    direct modifications to the resulting source, build binary and source
    packages, and everything will work.  The Debian *.diff.gz will contain
    a mixture of direct modifications and patch-system-managed
    modifications, which will be somewhat confusing going forward and may
    result in the problems explained in the next paragraph, but it often
    works in simple cases.

    If, however, the patches overlap, one generally has to use the patch
    system to add a new patch.  This will be the only way to get the
    sequencing right, let the patch system cleanly apply and unapply
    patches, and generally work as expected.

There is one possible exception worth noting: Bill Allombert mentioned in
the bug log that it's possible to make the clean target depend on the
patch target when using dpatch, everything will work, and people can
unpack the source and make direct changes on top of all the applied
patches.  Presumably if there are overlapping changes, this will break
further use of dpatch until the changes have been extracted as a regular
patch, but normal package builds may continue to work.  I don't see any
mention of this in the dpatch documentation as a recommended option.  A
similar technique could be used with quilt, although with quilt it would
bloat the diff even further due to the contents of the .pc directory.

Now, I think that everyone (possibly except Marco) agrees with the basic
idea of providing a README.source file explaining how to deal with a
package that has a non-trivial source layout.  In particular, I think
someone needs to know how to do all of the following:

1. Generate the fully patched sources, the sources in the state in which
   they'll be built, so that one can check to see if problems have been
   patched, look at the source, and so forth.

2. Add a new patch to the build process (including any special techniques
   to use to generate the patch if there's an easier tool than recursive
   diff from an unmodified package and the like).

3. Remove an existing patch from the build process.

4. Ideally, explain how to upgrade the package to a new upstream version,
   although this should probably be optional.

However, when we get into standardizing targets, this gets a lot murkier.
I think the discussion above makes it clear that the only thing that we
can really address with a target is point 1 above.  For all of the
systems, in the general case of modifications that overlap with existing
patches, I don't think we can provide targets that do 2.  3 and 4 are
obviously outside what a target can do.

Accordingly, I think moving forward with specifying a README.source file
that explains the above three or four points is something we can reach
consensus on.  I'm not as sure about standardizing a target for 1 (setup,
unpack, and patch are all currently in use), but I suppose that we could
standardize on patched.  This does raise insta-buggy issues since existing
packages don't provide that target.

However, I don't think it's going to work to say that after running some
target, people should be able to make modifications and run
dpkg-buildpackage and expect to have that work.  In each case, it looks
like there are cases where that isn't going to work, and I don't think
it's viable to say that those patch systems can't be used.

So, finally, I propose the following patch:

--- orig/policy.sgml
+++ mod/policy.sgml
@@ -1926,6 +1926,19 @@
 		possible is a good idea.
 	      </p>
 	    </item>
+
+	    <tag><tt>patched</tt> (optional)</tag>
+	    <item>
+	      <p>
+		This target performs whatever additional actions are
+		required to make the source ready for editing (unpacking
+		additional upstream archives, applying patches, etc.).
+		It is recommended to be implemented for any package where
+		<tt>dpkg-source -x</tt> does not result in source ready
+		for additional modification.  See
+		<ref id="readmesource">.
+	      </p>
+	    </item>
 	  </taglist>
 
 	<p>
@@ -2076,6 +2089,50 @@
 	  the file to the list in <file>debian/files</file>.</p>
       </sect>
 
+      <sect>
+	<heading>Source package handling:
+	  <file>debian/README.source</file></heading>
+
+	<p>
+	  If running <prgn>dpkg-source -x</prgn> on a source package
+	  doesn't produce the source of the package, ready for editing,
+	  and allow one to make changes and run
+	  <prng>dpkg-buildpackage</prgn to produce a modified package
+	  without taking any additional steps, creating a
+	  <file>debian/README.source</file> documentation file is
+	  recommended.  This file should explain how to do all of the
+	  following:
+	    <enumlist>
+	      <item>Generate the fully patched source, in a form ready for
+	      editing, that would be built to create Debian
+	      packages.  Doing this with a <tt>patched</tt> target in
+	      <file>debian/rules</file> is recommended; see
+	      <ref id="debianrules">.</item>
+	      <item>Modify the source and save those modifications so that
+	      they will be applied when building the package.</item>
+	      <item>Remove existing source modifications that previously
+	      were applied.</item>
+	      <item>Optionally, document what steps are necessary to
+	      upgrade the Debian source package to a new upstream version,
+	      if applicable.</item>
+	    </enumlist>
+	  This explanation should include specific commands and mention
+	  any additional required Debian packages.  It should not assume
+	  familiarity with any specific Debian packaging system or patch
+	  management tools.
+	</p>
+
+	<p>
+	  <file>debian/README.source</file> may also include any other
+	  information that would be helpful to someone modifying the
+	  source package.  Even if the package doesn't fit the above
+	  description, maintainers are encouraged to document in a
+	  <file>debian/README.source</file> file any source package with a
+	  particularly complex or unintuitive source layout or build
+	  system (for example, a package that builds the same source
+	  multiple times to generate different binary packages).
+	</p>
+      </sect>
     </chapt>

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




Tags added: patch Request was from Russ Allbery <rra@debian.org> to control@bugs.debian.org. (Wed, 02 Jan 2008 07:00:02 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#250202; Package debian-policy. Full text and rfc822 format available.

Acknowledgement sent to Colin Watson <cjwatson@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 #342 received at 250202@bugs.debian.org (full text, mbox):

From: Colin Watson <cjwatson@debian.org>
To: Russ Allbery <rra@debian.org>, 250202@bugs.debian.org
Cc: wouter@debian.org
Subject: Re: Bug#250202: "debian/README.source" file for packages with non-trivial source
Date: Wed, 2 Jan 2008 12:21:10 +0000
On Tue, Jan 01, 2008 at 10:54:06PM -0800, Russ Allbery wrote:
> Accordingly, I think moving forward with specifying a README.source file
> that explains the above three or four points is something we can reach
> consensus on.  I'm not as sure about standardizing a target for 1 (setup,
> unpack, and patch are all currently in use), but I suppose that we could
> standardize on patched.  This does raise insta-buggy issues since existing
> packages don't provide that target.

This is only a mild objection (I think this is too valuable a change for
me to want to stand in its way), but I am curious why you picked a
target name which AFAIK isn't used by more than a handful of existing
packages, rather than one of the ones which are common? In the latter
case, at least we'd have a head-start on implementation.

(If patched is in use by one of the major patch systems today and I just
forgot about it, please let me know.)

-- 
Colin Watson                                       [cjwatson@debian.org]




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

Acknowledgement sent to Wouter Verhelst <w@uter.be>:
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 #347 received at 250202@bugs.debian.org (full text, mbox):

From: Wouter Verhelst <w@uter.be>
To: Russ Allbery <rra@debian.org>
Cc: 250202@bugs.debian.org
Subject: Re: Bug#250202: "debian/README.source" file for packages with non-trivial source
Date: Wed, 2 Jan 2008 15:45:34 +0100
[Message part 1 (text/plain, inline)]
Hi Russ,

First, thanks for your great work on this bug.

On Tue, Jan 01, 2008 at 10:54:06PM -0800, Russ Allbery wrote:
> This is the last Policy bug I had tagged as wording.  It started with a
> proposal for a README.source file documenting how to do things with a
> package that uses a non-trivial source format, and then expanded into
> standardizing debian/rules targets for doing various things.
> 
> Having reviewed the entire bug thread, I think there are a few
> misconceptions and a few different cases mingled together, so I'm going to
> attempt a summary.
> 
> The original concern was being able to unpack a Debian source package and
> immediately start patching it, with a goal of creating a modified source
> package (for local modifications, security fixes, RC bug fixes, or what
> have you).

I think that sums it up quite right, yeah :)

> Among the source package formats in Debian, I know of two possible
> situations:
[...summary of patch systems snipped...]
> Now, I think that everyone (possibly except Marco) agrees with the basic
> idea of providing a README.source file explaining how to deal with a
> package that has a non-trivial source layout.  In particular, I think
> someone needs to know how to do all of the following:
> 
> 1. Generate the fully patched sources, the sources in the state in which
>    they'll be built, so that one can check to see if problems have been
>    patched, look at the source, and so forth.
> 
> 2. Add a new patch to the build process (including any special techniques
>    to use to generate the patch if there's an easier tool than recursive
>    diff from an unmodified package and the like).
> 
> 3. Remove an existing patch from the build process.
> 
> 4. Ideally, explain how to upgrade the package to a new upstream version,
>    although this should probably be optional.
> 
> However, when we get into standardizing targets, this gets a lot murkier.
> I think the discussion above makes it clear that the only thing that we
> can really address with a target is point 1 above.  For all of the
> systems, in the general case of modifications that overlap with existing
> patches, I don't think we can provide targets that do 2.  3 and 4 are
> obviously outside what a target can do.

Yes, that seems correct. I hadn't thought of that problem, actually, but
now that you mention it, I don't think there are ways of making that
easy. In short, as you show, sticking to just adding one or more
optional targets to debian/rules isn't going to cut it.

> Accordingly, I think moving forward with specifying a README.source file
> that explains the above three or four points is something we can reach
> consensus on.  I'm not as sure about standardizing a target for 1 (setup,
> unpack, and patch are all currently in use), but I suppose that we could
> standardize on patched.  This does raise insta-buggy issues since existing
> packages don't provide that target.
> 
> However, I don't think it's going to work to say that after running some
> target, people should be able to make modifications and run
> dpkg-buildpackage and expect to have that work.  In each case, it looks
> like there are cases where that isn't going to work, and I don't think
> it's viable to say that those patch systems can't be used.

Makes sense.

> So, finally, I propose the following patch:
> 
> --- orig/policy.sgml
> +++ mod/policy.sgml
> @@ -1926,6 +1926,19 @@
>  		possible is a good idea.
>  	      </p>
>  	    </item>
> +
> +	    <tag><tt>patched</tt> (optional)</tag>
> +	    <item>
> +	      <p>
> +		This target performs whatever additional actions are
> +		required to make the source ready for editing (unpacking
> +		additional upstream archives, applying patches, etc.).
> +		It is recommended to be implemented for any package where
> +		<tt>dpkg-source -x</tt> does not result in source ready
> +		for additional modification.  See
> +		<ref id="readmesource">.
> +	      </p>
> +	    </item>
>  	  </taglist>
>  
>  	<p>
> @@ -2076,6 +2089,50 @@
>  	  the file to the list in <file>debian/files</file>.</p>
>        </sect>
>  
> +      <sect>
> +	<heading>Source package handling:
> +	  <file>debian/README.source</file></heading>
> +
> +	<p>
> +	  If running <prgn>dpkg-source -x</prgn> on a source package
> +	  doesn't produce the source of the package, ready for editing,
> +	  and allow one to make changes and run
> +	  <prng>dpkg-buildpackage</prgn to produce a modified package
                                    ---^
Seems you've missed a > there.

> +	  without taking any additional steps, creating a
> +	  <file>debian/README.source</file> documentation file is
> +	  recommended.  This file should explain how to do all of the
> +	  following:
> +	    <enumlist>
> +	      <item>Generate the fully patched source, in a form ready for
> +	      editing, that would be built to create Debian
> +	      packages.  Doing this with a <tt>patched</tt> target in
> +	      <file>debian/rules</file> is recommended; see
> +	      <ref id="debianrules">.</item>
> +	      <item>Modify the source and save those modifications so that
> +	      they will be applied when building the package.</item>
> +	      <item>Remove existing source modifications that previously
> +	      were applied.</item>
> +	      <item>Optionally, document what steps are necessary to
> +	      upgrade the Debian source package to a new upstream version,
> +	      if applicable.</item>
> +	    </enumlist>
> +	  This explanation should include specific commands and mention
> +	  any additional required Debian packages.  It should not assume
> +	  familiarity with any specific Debian packaging system or patch
> +	  management tools.
> +	</p>
> +
> +	<p>
> +	  <file>debian/README.source</file> may also include any other
> +	  information that would be helpful to someone modifying the
> +	  source package.  Even if the package doesn't fit the above
> +	  description, maintainers are encouraged to document in a
> +	  <file>debian/README.source</file> file any source package with a
> +	  particularly complex or unintuitive source layout or build
> +	  system (for example, a package that builds the same source
> +	  multiple times to generate different binary packages).
> +	</p>
> +      </sect>
>      </chapt>

I guess it was obvious from my above comments, but I'll second this
patch (or accept it as a replacement of my original one, or whatever
procedure requires me to do now).

Thanks again,

-- 
<Lo-lan-do> Home is where you have to wash the dishes.
  -- #debian-devel, Freenode, 2004-09-22
[signature.asc (application/pgp-signature, inline)]

Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#250202; 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 #352 received at 250202@bugs.debian.org (full text, mbox):

From: Russ Allbery <rra@debian.org>
To: Colin Watson <cjwatson@debian.org>
Cc: 250202@bugs.debian.org, wouter@debian.org
Subject: Re: Bug#250202: "debian/README.source" file for packages with non-trivial source
Date: Wed, 02 Jan 2008 14:55:16 -0800
Colin Watson <cjwatson@debian.org> writes:
> On Tue, Jan 01, 2008 at 10:54:06PM -0800, Russ Allbery wrote:

>> Accordingly, I think moving forward with specifying a README.source
>> file that explains the above three or four points is something we can
>> reach consensus on.  I'm not as sure about standardizing a target for 1
>> (setup, unpack, and patch are all currently in use), but I suppose that
>> we could standardize on patched.  This does raise insta-buggy issues
>> since existing packages don't provide that target.

> This is only a mild objection (I think this is too valuable a change for
> me to want to stand in its way), but I am curious why you picked a
> target name which AFAIK isn't used by more than a handful of existing
> packages, rather than one of the ones which are common? In the latter
> case, at least we'd have a head-start on implementation.

> (If patched is in use by one of the major patch systems today and I just
> forgot about it, please let me know.)

Part of the original thread was picking something that currently wasn't
used so that we could be assured that we weren't changing the semantics of
something already out there.  However, we could standardize patch instead
of patched, which will pick up quilt and dpatch at least.  It would cause
problems if one of the other systems used patch to mean something
different, but I'm not aware of one that does.  dbs doesn't appear to.

-- 
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#250202; 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 #357 received at 250202@bugs.debian.org (full text, mbox):

From: Russ Allbery <rra@debian.org>
To: 250202@bugs.debian.org
Subject: Re: Bug#250202: "debian/README.source" file for packages with non-trivial source
Date: Wed, 02 Jan 2008 14:58:18 -0800
Wouter Verhelst <w@uter.be> writes:

> Hi Russ,
>
> First, thanks for your great work on this bug.

Thanks!  It feels good to go back and resolve long-standing issues.

>> +	  <prng>dpkg-buildpackage</prgn to produce a modified package
>                                     ---^
> Seems you've missed a > there.

Thanks, fixed in my repository.

-- 
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#250202; Package debian-policy. Full text and rfc822 format available.

Acknowledgement sent to Junichi Uekawa <dancer@netfort.gr.jp>:
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 #362 received at 250202@bugs.debian.org (full text, mbox):

From: Junichi Uekawa <dancer@netfort.gr.jp>
To: Russ Allbery <rra@debian.org>, 250202@bugs.debian.org
Cc: Colin Watson <cjwatson@debian.org>, wouter@debian.org
Subject: Re: Bug#250202: "debian/README.source" file for packages with non-trivial source
Date: Fri, 04 Jan 2008 19:34:15 +0900
Hi,

> > (If patched is in use by one of the major patch systems today and I just
> > forgot about it, please let me know.)
> 
> Part of the original thread was picking something that currently wasn't
> used so that we could be assured that we weren't changing the semantics of
> something already out there.  However, we could standardize patch instead
> of patched, which will pick up quilt and dpatch at least.  It would cause
> problems if one of the other systems used patch to mean something
> different, but I'm not aware of one that does.  dbs doesn't appear to.
> 

Yup, I seem to remember that only a few non-standard ones used 'patch'
in a different semantics.

Nice to see this long-standing issue progress. :)

regards,
	junichi
-- 
dancer@{debian.org,netfort.gr.jp}   Debian Project




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

Acknowledgement sent to Jörg Sommer <joerg@alea.gnuu.de>:
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 #367 received at 250202@bugs.debian.org (full text, mbox):

From: Jörg Sommer <joerg@alea.gnuu.de>
To: Russ Allbery <rra@debian.org>
Cc: 250202@bugs.debian.org, wouter@debian.org
Subject: Re: Bug#250202: "debian/README.source" file for packages with non-trivial source
Date: Tue, 8 Jan 2008 21:15:25 +0100
[Message part 1 (text/plain, inline)]
Hi,

Russ Allbery schrieb am Tue 01. Jan, 22:54 (-0800):
> +	  <file>debian/README.source</file> documentation file is
> +	  recommended.  This file should explain how to do all of the
> +	  following:
> +	    <enumlist>
> +	      <item>Generate the fully patched source, in a form ready for
> +	      editing, that would be built to create Debian
> +	      packages.  Doing this with a <tt>patched</tt> target in
> +	      <file>debian/rules</file> is recommended; see
> +	      <ref id="debianrules">.</item>
> +	      <item>Modify the source and save those modifications so that
> +	      they will be applied when building the package.</item>
> +	      <item>Remove existing source modifications that previously
> +	      were applied.</item>

Should this be the opposite of the first item or should this describe how
to remove user modifications, i.e. bring the tree in the state after
doing debian/rules patched?

The rest looks good and I agree that such a source is useful, but it
should also be allowed to refer to a central document like
/u/s/d/dpatch/README.source. I expect that many README.source look the
same.

Bye, Jörg.
-- 
„Wer im Usenet gelesen werden will, sollte leserorientiert schreiben. Wer nur
 für sich schreiben will, dem ist mit einem Tagebuch vielleicht besser
 geholfen. Gelesen zu werden ist kein Recht, sondern ein Privileg.“
     Thore Tams in <90tfv8$49b$1@keks.kruemel.dyndns.org>
[signature.asc (application/pgp-signature, inline)]

Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#250202; 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 #372 received at 250202@bugs.debian.org (full text, mbox):

From: Russ Allbery <rra@debian.org>
To: Jörg Sommer <joerg@alea.gnuu.de>
Cc: 250202@bugs.debian.org, wouter@debian.org
Subject: Re: Bug#250202: "debian/README.source" file for packages with non-trivial source
Date: Tue, 08 Jan 2008 12:36:07 -0800
Jörg Sommer <joerg@alea.gnuu.de> writes:
> Russ Allbery schrieb am Tue 01. Jan, 22:54 (-0800):

>> +	  <file>debian/README.source</file> documentation file is
>> +	  recommended.  This file should explain how to do all of the
>> +	  following:
>> +	    <enumlist>
>> +	      <item>Generate the fully patched source, in a form ready for
>> +	      editing, that would be built to create Debian
>> +	      packages.  Doing this with a <tt>patched</tt> target in
>> +	      <file>debian/rules</file> is recommended; see
>> +	      <ref id="debianrules">.</item>
>> +	      <item>Modify the source and save those modifications so that
>> +	      they will be applied when building the package.</item>
>> +	      <item>Remove existing source modifications that previously
>> +	      were applied.</item>
>
> Should this be the opposite of the first item or should this describe
> how to remove user modifications, i.e. bring the tree in the state after
> doing debian/rules patched?

What I was trying to get at here was documentation on how to remove a
patch that was previously in the Debian package but which should go away
for some reason (perhaps it introduces a security vulnerability).  So it's
not really related to the first item.

I'll try to think of a better way of phrasing that.

> The rest looks good and I agree that such a source is useful, but it
> should also be allowed to refer to a central document like
> /u/s/d/dpatch/README.source. I expect that many README.source look the
> same.

I don't think that needs any change to the above wording.  If
README.source refers to another existing file that documents those things,
that seems to me to satisfy the above.  Although I suppose we could
explicitly add something like "The instructions may refer to a
documentation file installed by one of the package build dependencies,
provided that it clearly explains these tasks and isn't a general
reference manual."

-- 
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#250202; Package debian-policy. Full text and rfc822 format available.

Acknowledgement sent to Wouter Verhelst <w@uter.be>:
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 #377 received at 250202@bugs.debian.org (full text, mbox):

From: Wouter Verhelst <w@uter.be>
To: Russ Allbery <rra@debian.org>
Cc: Jörg Sommer <joerg@alea.gnuu.de>, 250202@bugs.debian.org
Subject: Re: Bug#250202: "debian/README.source" file for packages with non-trivial source
Date: Wed, 9 Jan 2008 15:19:17 +0100
On Tue, Jan 08, 2008 at 12:36:07PM -0800, Russ Allbery wrote:
> Jörg Sommer <joerg@alea.gnuu.de> writes:
> > The rest looks good and I agree that such a source is useful, but it
> > should also be allowed to refer to a central document like
> > /u/s/d/dpatch/README.source. I expect that many README.source look the
> > same.
> 
> I don't think that needs any change to the above wording.  If
> README.source refers to another existing file that documents those things,
> that seems to me to satisfy the above.  Although I suppose we could
> explicitly add something like "The instructions may refer to a
> documentation file installed by one of the package build dependencies,
> provided that it clearly explains these tasks and isn't a general
> reference manual."

That seems like a good idea, actually; not because I expect people won't
refer to other documents in the absense of such a clause, but rather
because I feel it to be quite likely that they _will_ refer to general
reference manuals otherwise.

Thanks,

-- 
<Lo-lan-do> Home is where you have to wash the dishes.
  -- #debian-devel, Freenode, 2004-09-22




Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#250202; 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 #382 received at 250202@bugs.debian.org (full text, mbox):

From: Russ Allbery <rra@debian.org>
To: 250202@bugs.debian.org
Subject: Re: Bug#250202: "debian/README.source" file for packages with non-trivial source
Date: Tue, 04 Mar 2008 19:32:50 -0800
Okay, here is a new and hopefully final version of the README.source
patch.  If you have any other comments or concerns, please speak up now;
otherwise, I will apply this patch for the next Policy release.

--- orig/policy.sgml
+++ mod/policy.sgml
@@ -1926,6 +1926,19 @@
 		possible is a good idea.
 	      </p>
 	    </item>
+
+	    <tag><tt>patch</tt> (optional)</tag>
+	    <item>
+	      <p>
+		This target performs whatever additional actions are
+		required to make the source ready for editing (unpacking
+		additional upstream archives, applying patches, etc.).
+		It is recommended to be implemented for any package where
+		<tt>dpkg-source -x</tt> does not result in source ready
+		for additional modification.  See
+		<ref id="readmesource">.
+	      </p>
+	    </item>
 	  </taglist>
 
 	<p>
@@ -2076,6 +2089,57 @@
 	  the file to the list in <file>debian/files</file>.</p>
       </sect>
 
+      <sect>
+	<heading>Source package handling:
+	  <file>debian/README.source</file></heading>
+
+	<p>
+	  If running <prgn>dpkg-source -x</prgn> on a source package
+	  doesn't produce the source of the package, ready for editing,
+	  and allow one to make changes and run
+	  <prng>dpkg-buildpackage</prgn> to produce a modified package
+	  without taking any additional steps, creating a
+	  <file>debian/README.source</file> documentation file is
+	  recommended.  This file should explain how to do all of the
+	  following:
+	    <enumlist>
+	      <item>Generate the fully patched source, in a form ready for
+	      editing, that would be built to create Debian
+	      packages.  Doing this with a <tt>patch</tt> target in
+	      <file>debian/rules</file> is recommended; see
+	      <ref id="debianrules">.</item>
+	      <item>Modify the source and save those modifications so that
+	      they will be applied when building the package.</item>
+	      <item>Remove source modifications that are currently being
+	      applied when building the package.</item>
+	      <item>Optionally, document what steps are necessary to
+	      upgrade the Debian source package to a new upstream version,
+	      if applicable.</item>
+	    </enumlist>
+	  This explanation should include specific commands and mention
+	  any additional required Debian packages.  It should not assume
+	  familiarity with any specific Debian packaging system or patch
+	  management tools.
+	</p>
+
+	<p>
+	  This explanation may refer to a documentation file installed by
+	  one of the package's build dependencies provided that the
+	  referenced documentation clearly explains these tasks and is not
+	  a general reference manual.
+	</p>
+
+	<p>
+	  <file>debian/README.source</file> may also include any other
+	  information that would be helpful to someone modifying the
+	  source package.  Even if the package doesn't fit the above
+	  description, maintainers are encouraged to document in a
+	  <file>debian/README.source</file> file any source package with a
+	  particularly complex or unintuitive source layout or build
+	  system (for example, a package that builds the same source
+	  multiple times to generate different binary packages).
+	</p>
+      </sect>
     </chapt>

-- 
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#250202; Package debian-policy. Full text and rfc822 format available.

Acknowledgement sent to Raphael Hertzog <hertzog@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 #387 received at 250202@bugs.debian.org (full text, mbox):

From: Raphael Hertzog <hertzog@debian.org>
To: Russ Allbery <rra@debian.org>, 250202@bugs.debian.org
Subject: Re: Bug#250202: "debian/README.source" file for packages with non-trivial source
Date: Wed, 5 Mar 2008 09:00:26 +0100
[Message part 1 (text/plain, inline)]
On Tue, 04 Mar 2008, Russ Allbery wrote:
> Okay, here is a new and hopefully final version of the README.source
> patch.  If you have any other comments or concerns, please speak up now;
> otherwise, I will apply this patch for the next Policy release.

Seconded.

-- 
Raphaël Hertzog

Le best-seller français mis à jour pour Debian Etch :
http://www.ouaza.com/livre/admin-debian/
[signature.asc (application/pgp-signature, inline)]

Tags added: pending Request was from Russ Allbery <rra@debian.org> to control@bugs.debian.org. (Sun, 16 Mar 2008 21:10:09 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#250202; 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 #394 received at 250202@bugs.debian.org (full text, mbox):

From: Russ Allbery <rra@debian.org>
To: 250202@bugs.debian.org
Subject: Re: Bug#250202: "debian/README.source" file for packages with non-trivial source
Date: Sun, 16 Mar 2008 14:10:07 -0700
Raphael Hertzog <hertzog@debian.org> writes:
> On Tue, 04 Mar 2008, Russ Allbery wrote:

>> Okay, here is a new and hopefully final version of the README.source
>> patch.  If you have any other comments or concerns, please speak up
>> now; otherwise, I will apply this patch for the next Policy release.

> Seconded.

Thanks, this has now been applied to my repository.

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




Tags removed: patch Request was from Russ Allbery <rra@debian.org> to control@bugs.debian.org. (Mon, 17 Mar 2008 05:57:03 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#250202; Package debian-policy. Full text and rfc822 format available.

Acknowledgement sent to Frank Küster <frank@kuesterei.ch>:
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 #401 received at 250202@bugs.debian.org (full text, mbox):

From: Frank Küster <frank@kuesterei.ch>
To: Russ Allbery <rra@debian.org>
Cc: 250202@bugs.debian.org
Subject: Re: Bug#250202: "debian/README.source" file for packages with non-trivial source
Date: Tue, 29 Apr 2008 21:36:22 +0200
Russ Allbery <rra@debian.org> wrote:

> +	<p>
> +	  <file>debian/README.source</file> may also include any other
> +	  information that would be helpful to someone modifying the
> +	  source package.  Even if the package doesn't fit the above
> +	  description, maintainers are encouraged to document in a
> +	  <file>debian/README.source</file> file any source package with a
> +	  particularly complex or unintuitive source layout or build
> +	  system (for example, a package that builds the same source
> +	  multiple times to generate different binary packages).
> +	</p>
> +      </sect>
>      </chapt>

I suggest to end this paragraph with

+	  system (for example, a package that builds the same source
+	  multiple times to generate different binary packages, or a
+	  package which had to change the upstream tarball due to
+	  technical or license reasons).

Rationale: The developer's reference describes in 

6.7.8 Best practices for orig.tar.gz files

how to document properly any changes that need to be done to the
orig.tar.gz, and recommends the name README.Debian-source. This is the
only mention of that filename in devref, and README.source is not
mentioned at all.

Actually, I think that name, README.Debian-source, is even better for
the patch system issue, too, since it's about Debian-specific
modifications of the source. But anyway, I think that we can expect
either of the names already being in use, following the advice of the
developer's reference, whereas documenting the multiple binary package
thing in that file is probably new. If we give examples, we should
indeed use the most relevant ones.

Regards, Frank


-- 
Frank Küster
Debian Developer (teTeX/TeXLive)




Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#250202; 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 #406 received at 250202@bugs.debian.org (full text, mbox):

From: Russ Allbery <rra@debian.org>
To: Frank Küster <frank@kuesterei.ch>
Cc: 250202@bugs.debian.org
Subject: Re: Bug#250202: "debian/README.source" file for packages with non-trivial source
Date: Tue, 29 Apr 2008 13:53:44 -0700
Frank Küster <frank@kuesterei.ch> writes:

> I suggest to end this paragraph with
>
> +	  system (for example, a package that builds the same source
> +	  multiple times to generate different binary packages, or a
> +	  package which had to change the upstream tarball due to
> +	  technical or license reasons).
>
> Rationale: The developer's reference describes in 
>
> 6.7.8 Best practices for orig.tar.gz files
>
> how to document properly any changes that need to be done to the
> orig.tar.gz, and recommends the name README.Debian-source. This is the
> only mention of that filename in devref, and README.source is not
> mentioned at all.

As discussed on -mentors (and I believe I also filed a bug against
devref), I believe the devref instructions are wrong.  The proper location
for this information is debian/copyright, which is already required to
contain information about the provenance of the upstream source.

> Actually, I think that name, README.Debian-source, is even better for
> the patch system issue, too, since it's about Debian-specific
> modifications of the source.

It's already in the debian/ directory, so the additional Debian- seems
redundant to me.  If the existing file name were in widespread use, the
redundancy wouldn't really matter, but I don't get that impression.

-- 
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#250202; Package debian-policy. Full text and rfc822 format available.

Acknowledgement sent to Frank Küster <frank@kuesterei.ch>:
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 #411 received at 250202@bugs.debian.org (full text, mbox):

From: Frank Küster <frank@kuesterei.ch>
To: Russ Allbery <rra@debian.org>
Cc: 250202@bugs.debian.org
Subject: Re: Bug#250202: "debian/README.source" file for packages with non-trivial source
Date: Thu, 01 May 2008 11:33:38 +0200
Russ Allbery <rra@debian.org> wrote:

> Frank Küster <frank@kuesterei.ch> writes:
>
>> The developer's reference describes in 
>>
>> 6.7.8 Best practices for orig.tar.gz files
>>
>> how to document properly any changes that need to be done to the
>> orig.tar.gz, and recommends the name README.Debian-source. This is the
>> only mention of that filename in devref, and README.source is not
>> mentioned at all.
>
> As discussed on -mentors (and I believe I also filed a bug against
> devref), 

You probably mean
http://thread.gmane.org/gmane.linux.debian.devel.mentors/18439/focus=18450

> I believe the devref instructions are wrong.  The proper location
> for this information is debian/copyright, which is already required to
> contain information about the provenance of the upstream source.

I would argue that if the changes to the orig.tar.gz have been made for
other reasons than DFSG-freeness, debian/copyright is the wrong
place. Such reasons could be

- creating a single tar.gz from multiple upstream locations or from an
  unpacked tree (TeXLive only distributes CD images, from which we skip
  the part needed for Live CDs or installation from CD)

- changing the format of the upstream archive, e.g. if it comes as a ZIP
  file instead of tar.gz, or tar.$compression_not_supported_by_dpkg

- reducing the size of the tarball to 10% by removing the included
  library sources, hard-linked binaries for lots of OSes/arches and/or
  the specialized build systems for some of them

That simply doesn't fit into debian/copyright, and I think using a
special README file targetted at developers is in order. Alternatively,
one could use the get-orig-tar target in debian/rules, but that would
probably require lengthy commens in that file explaining why this is
done. 

If the orig.tar.gz is repackaged (at least in part) because of licening
issues, then this needs to be documented *additionally* in
debian/copyright. 

>> Actually, I think that name, README.Debian-source, is even better for
>> the patch system issue, too, since it's about Debian-specific
>> modifications of the source.
>
> It's already in the debian/ directory, so the additional Debian- seems
> redundant to me.

Yes, you are right.

So, as for this bug, I still think that the info in devref is correct,
and should be included in the example in policy, if policy gives an
example at all. 

If you think that the information in devref is incorrect, please file a
bug and Cc me; I don't think we should discuss this here (although I can
already say that I don't seem to agree with some things you said in the
thread above).

Regards, Frank

-- 
Frank Küster
Debian Developer (teTeX/TeXLive)




Information forwarded to debian-bugs-dist@lists.debian.org, Debian Policy List <debian-policy@lists.debian.org>:
Bug#250202; 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 #416 received at 250202@bugs.debian.org (full text, mbox):

From: Russ Allbery <rra@debian.org>
To: Frank Küster <frank@kuesterei.ch>
Cc: 250202@bugs.debian.org
Subject: Re: Bug#250202: "debian/README.source" file for packages with non-trivial source
Date: Thu, 01 May 2008 05:21:05 -0700
Frank Küster <frank@kuesterei.ch> writes:
> Russ Allbery <rra@debian.org> wrote:

>> I believe the devref instructions are wrong.  The proper location for
>> this information is debian/copyright, which is already required to
>> contain information about the provenance of the upstream source.

I take this back -- devref has apparently already been changed.  I should
have checked first.  devref now says:

   1. must contain detailed information how the repackaged source was
      obtained, and how this can be reproduced in the debian/copyright. It
      is also a good idea to provide a get-orig-source target in your
      debian/rules file that repeats the process, as described in the
      Policy Manual, Main building script: debian/rules.

and I don't see a reference to README.Debian-source.

> I would argue that if the changes to the orig.tar.gz have been made for
> other reasons than DFSG-freeness, debian/copyright is the wrong
> place.

Putting this information in debian/copyright is unrelated to DFSG-freeness
or the license of the software.  debian/copyright has several purposes
specified in Policy, not just the license information, and one of them is
to state the provenance of the source:

    In addition, the copyright file must say where the upstream sources
    (if any) were obtained.

Explaining where and how the .orig.tar.gz file was generated to me falls
into the category of saying where the upstream source was obtained.

> So, as for this bug, I still think that the info in devref is correct,
> and should be included in the example in policy, if policy gives an
> example at all. 

I feel rather strongly (to be honest, more strongly than I should, since
it's really bikeshed-painting at some level, but I have a hard time
getting myself to realize that) about putting the source information in
debian/copyright and hence am not willing to make this change in the
absence of a clearer consensus that I'm wrong.

-- 
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#250202; 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 #421 received at 250202@bugs.debian.org (full text, mbox):

From: Bill Allombert <Bill.Allombert@math.u-bordeaux1.fr>
To: Russ Allbery <rra@debian.org>, 250202@bugs.debian.org
Subject: Re: Bug#250202: "debian/README.source" file for packages with non-trivial source
Date: Thu, 1 May 2008 15:02:37 +0200
On Thu, May 01, 2008 at 05:21:05AM -0700, Russ Allbery wrote:
> Frank Küster <frank@kuesterei.ch> writes:
> > Russ Allbery <rra@debian.org> wrote:
> 
> >> I believe the devref instructions are wrong.  The proper location for
> >> this information is debian/copyright, which is already required to
> >> contain information about the provenance of the upstream source.
> 
> I take this back -- devref has apparently already been changed.  I should
> have checked first.  devref now says:
> 
>    1. must contain detailed information how the repackaged source was
>       obtained, and how this can be reproduced in the debian/copyright. It
>       is also a good idea to provide a get-orig-source target in your
>       debian/rules file that repeats the process, as described in the
>       Policy Manual, Main building script: debian/rules.
> 
> and I don't see a reference to README.Debian-source.
> 
> > I would argue that if the changes to the orig.tar.gz have been made for
> > other reasons than DFSG-freeness, debian/copyright is the wrong
> > place.
> 
> Putting this information in debian/copyright is unrelated to DFSG-freeness
> or the license of the software.  debian/copyright has several purposes
> specified in Policy, not just the license information, and one of them is
> to state the provenance of the source:
> 
>     In addition, the copyright file must say where the upstream sources
>     (if any) were obtained.
> 
> Explaining where and how the .orig.tar.gz file was generated to me falls
> into the category of saying where the upstream source was obtained.

It does not. Let assume we removed some non-source files from the tarball
and repacked it. The upstream sources files were still obtained from
upstream website. The policy blurb does not say 'how the source 
package were built' and I do not think this necessarily belong in
debian/copyright. 

However if you build the tarball from two or more upstream source,
you have to mention that in the copyright file. If you change the
upstream source in a way that affect its licences status (e.g.
by removing non-free file) you have to document the discrepancy.

But I do not think the technical detail of the repacking belong there.

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#250202; 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 #426 received at 250202@bugs.debian.org (full text, mbox):

From: Russ Allbery <rra@debian.org>
To: 250202@bugs.debian.org
Subject: Re: Bug#250202: "debian/README.source" file for packages with non-trivial source
Date: Thu, 01 May 2008 06:14:43 -0700
Bill Allombert <Bill.Allombert@math.u-bordeaux1.fr> writes:
> On Thu, May 01, 2008 at 05:21:05AM -0700, Russ Allbery wrote:

>> Explaining where and how the .orig.tar.gz file was generated to me
>> falls into the category of saying where the upstream source was
>> obtained.

> It does not.

Yes, actually, it does.

You're entitled to a different opinion, but I can say canonically and
without possibility of contradiction that *to me* this falls into the
category of saying where the upstream source was obtained.

(Sorry, pet peeve.)

-- 
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#250202; Package debian-policy. Full text and rfc822 format available.

Acknowledgement sent to Frank Küster <frank@kuesterei.ch>:
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 #431 received at 250202@bugs.debian.org (full text, mbox):

From: Frank Küster <frank@kuesterei.ch>
To: Russ Allbery <rra@debian.org>
Cc: 250202@bugs.debian.org
Subject: Re: Bug#250202: "debian/README.source" file for packages with non-trivial source
Date: Thu, 01 May 2008 21:44:13 +0200
Russ Allbery <rra@debian.org> wrote:

> Frank Küster <frank@kuesterei.ch> writes:
>> Russ Allbery <rra@debian.org> wrote:
>
>>> I believe the devref instructions are wrong.  The proper location for
>>> this information is debian/copyright, which is already required to
>>> contain information about the provenance of the upstream source.
>
> I take this back -- devref has apparently already been changed.  I should
> have checked first.

I was also using an outdated copy... 

> Putting this information in debian/copyright is unrelated to DFSG-freeness
> or the license of the software.  debian/copyright has several purposes
> specified in Policy, not just the license information, and one of them is
> to state the provenance of the source:
>
>     In addition, the copyright file must say where the upstream sources
>     (if any) were obtained.
>
> Explaining where and how the .orig.tar.gz file was generated to me falls
> into the category of saying where the upstream source was obtained.

I must admit I wasn't aware of that.

> I feel rather strongly (to be honest, more strongly than I should, since
> it's really bikeshed-painting at some level, but I have a hard time
> getting myself to realize that) about putting the source information in
> debian/copyright and hence am not willing to make this change in the
> absence of a clearer consensus that I'm wrong.

I agree with you now.

Regards, Frank
-- 
Frank Küster
Debian Developer (teTeX/TeXLive)




Reply sent to Russ Allbery <rra@debian.org>:
You have taken responsibility. Full text and rfc822 format available.

Notification sent to wouter@debian.org:
Bug acknowledged by developer. Full text and rfc822 format available.

Message #436 received at 250202-close@bugs.debian.org (full text, mbox):

From: Russ Allbery <rra@debian.org>
To: 250202-close@bugs.debian.org
Subject: Bug#250202: fixed in debian-policy 3.8.0.0
Date: Wed, 04 Jun 2008 23:32:03 +0000
Source: debian-policy
Source-Version: 3.8.0.0

We believe that the bug you reported is fixed in the latest version of
debian-policy, which is due to be installed in the Debian FTP archive:

debian-policy_3.8.0.0.dsc
  to pool/main/d/debian-policy/debian-policy_3.8.0.0.dsc
debian-policy_3.8.0.0.tar.gz
  to pool/main/d/debian-policy/debian-policy_3.8.0.0.tar.gz
debian-policy_3.8.0.0_all.deb
  to pool/main/d/debian-policy/debian-policy_3.8.0.0_all.deb



A summary of the changes between this version and the previous one is
attached.

Thank you for reporting the bug, which will now be closed.  If you
have further comments please address them to 250202@bugs.debian.org,
and the maintainer will reopen the bug report if appropriate.

Debian distribution maintenance software
pp.
Russ Allbery <rra@debian.org> (supplier of updated debian-policy package)

(This message was generated automatically at their request; if you
believe that there is a problem with it please contact the archive
administrators by mailing ftpmaster@debian.org)


-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Format: 1.8
Date: Wed, 04 Jun 2008 15:53:27 -0700
Source: debian-policy
Binary: debian-policy
Architecture: source all
Version: 3.8.0.0
Distribution: unstable
Urgency: low
Maintainer: Debian Policy List <debian-policy@lists.debian.org>
Changed-By: Russ Allbery <rra@debian.org>
Description: 
 debian-policy - Debian Policy Manual and related documents
Closes: 65577 186700 209008 250202 291460 367984 379150 392362 403391 422552 430649 431813 440420 442070 452105 455602 458910 473761 475731 480551 481640 481954
Changes: 
 debian-policy (3.8.0.0) unstable; urgency=low
 .
   * Bug fix: "[PROPOSAL] "debian/README.source" file for packages with
     non-trivial source", thanks to Wouter Verhelst, Jörg Sommer, Colin Watson,
     and Junichi Uekawa                                       (Closes: #250202).
   * Bug fix: "[AMENDMENT 11/02/2008] Manual page encoding", thanks to
     Colin Watson                                             (Closes: #440420).
   * Bug fix: "[PROPOSAL] common interface for parallel building in
     DEB_BUILD_OPTIONS", thanks to Loïc Minier, Peter Samuelson, and Robert
     Millan                                                   (Closes: #209008).
   * Bug fix: "Please clarify splitting/syntax of DEB_BUILD_OPTIONS", thanks to
     Loïc Minier, Peter Samuelson, Robert Millan, and Guillem Jover
                                                              (Closes: #430649).
   * Bug fix: "Documentation for Breaks in dpkg", thanks to Ian Jackson
                                                              (Closes: #379150).
   * Bug fix: "support for wrapped Uploaders should now be mandatory"
                                                              (Closes: #431813).
   * Bug fix: "[PROPOSAL] Add should not embed code from other packages",
     thanks to Neil McGovern, Colin Watson, Bill Allombert, Steve Langasek,
     Kurt Roeckx, and others                                  (Closes: #392362).
   * Bug fix: "Homepage field in debian/control undocumented", thanks to
     Mario Iseli                                              (Closes: #452105).
   * Bug fix: "Policy inconsistent with reality: base subsection no longer
     used", thanks to Magnus Holmgren, Bernd Zeimetz, and Colin Watson
                                                              (Closes: #442070).
   * Bug fix: "Inclusion of Apache Software License versions in
     /usr/share/common-licenses", thanks to Barry Hawkins     (Closes: #291460).
   * Bug fix: "[Amended] copyright should include notice if a package is
     not a part of Debian distribution", thanks to Taketoshi Sano
                                                              (Closes: #65577).
   * Bug fix: "scripts as configuration files: should vs. must", thanks to Frank
     Küster                                                   (Closes: #403391).
   * Bug fix: "debconf specification should allow underscores in template
     names", thanks to Colin Watson                           (Closes: #473761).
   * Bug fix: "clarify handling of run-time and compile-time support programs",
     thanks to Goswin Brederlow and Raphael Hertzog           (Closes: #367984).
   * Policy: better document version ranking and empty Debian revisions
     Wording: Russ Allbery <rra@debian.org>
     Seconded: Raphaël Hertzog <hertzog@debian.org>
     Seconded: Manoj Srivastava <srivasta@debian.org>
     Seconded: Guillem Jover <guillem@debian.org>
     Closes: #186700, #458910
   * Policy: remove obsolete app-defaults and Xresources provisions
     Wording: Julien Cristau <jcristau@debian.org>
     Seconded: Russ Allbery <rra@debian.org>
     Closes: #480551
   * Bug fix: "Examples of dpkg frontends should mention apt now", thanks
     to Josh Triplett                                         (Closes: #455602).
   * Bug fix: "Minor typos and wording suggestions", thanks to Michael
     Tautschnig                                               (Closes: #422552).
   * Bug fix: "substvar reference moved from dpkg-source(1) to
     deb-substvars(5)", thanks to Ian Beckwith                (Closes: #475731).
   * Policy: bugs fixed in NMUs are now closed rather than marked fixed
     Wording: Russ Allbery <rra@debian.org> (thanks, Sandro Tosi)
     Closes: #481640
   * Policy: C.1.4, C.1.8: minor typos
     Wording: Sandro Tosi <matrixhasu@gmail.com>
     Closes: #481954
   * Remove the now-obsolete policy-process document.
   * Add an md5sums control file.
   * Add Vcs-Browser and Vcs-Git control fields.
   * Remove build system support for FHS 2.1 and FSSTND, mostly commented out.
   * Remove more temporary files created by the build.
   * Remove the FSSTND license from debian/copyright; no FSSTND files are
     currently part of policy.
   * Update FHS copyright dates in debian/copyright.
   * Standardize the spacing around headings in upgrading-checklist.html.
   * Remove old ChangeLog files and metadata headers in maintainer scripts
     and debian/rules.
Checksums-Sha1: 
 f42b9921908670eb41c04940875084bc07750592 1095 debian-policy_3.8.0.0.dsc
 3eda45d7ca5563bab8bfda93286137071979385c 638655 debian-policy_3.8.0.0.tar.gz
 73680c98bc62507858aa055bcf1f1688a812f5ba 1588552 debian-policy_3.8.0.0_all.deb
Checksums-Sha256: 
 507a048bc7c84039910843e284d8e0e305778224346fd981c6f749176cc79220 1095 debian-policy_3.8.0.0.dsc
 8321b1dddd3ddd55a09539c842084ea05a731265c4c5847997957a552ba1aaa4 638655 debian-policy_3.8.0.0.tar.gz
 6c2083f50ccaa5a2f2d7a89febd320cf3a862b3204157324ffd9b363daac3e58 1588552 debian-policy_3.8.0.0_all.deb
Files: 
 37ff33fb3ccebc4f87e23fd7b91e7859 1095 doc optional debian-policy_3.8.0.0.dsc
 2565d6eaceac0aa2d093538048c1b8ed 638655 doc optional debian-policy_3.8.0.0.tar.gz
 3b153faeec899cdf1199d4d46c5d8859 1588552 doc optional debian-policy_3.8.0.0_all.deb

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.6 (GNU/Linux)

iD8DBQFIRyNB+YXjQAr8dHYRAt4NAKDbO1f3BlmKT5SgMVf4AHE2Z7bPTgCffcnI
Kwa3jEGgq+PV6dwiurjmSAc=
=wCDz
-----END PGP SIGNATURE-----





Bug archived. Request was from Debbugs Internal Request <owner@bugs.debian.org> to internal_control@bugs.debian.org. (Fri, 04 Jul 2008 07:27:22 GMT) Full text and rfc822 format available.

Send a report that this bug log contains spam.


Debian bug tracking system administrator <owner@bugs.debian.org>. Last modified: Sun Apr 20 10:50:50 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.