Debian Bug report logs - #278524
developers-reference: Please add documentation on handling of orig.tar.gz files

version graph

Package: developers-reference; Maintainer for developers-reference is Developers Reference Maintainers <debian-policy@lists.debian.org>; Source for developers-reference is src:developers-reference.

Reported by: Frank Küster <frank@kuesterei.ch>

Date: Wed, 27 Oct 2004 14:48:04 UTC

Severity: wishlist

Tags: patch

Fixed in version developers-reference/3.3.6

Done: Andreas Barth <aba@not.so.argh.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, Henning Makholm <henning@makholm.net>, Frank K�ster <frank@debian.org>, Adam Di Carlo <aph@debian.org>:
Bug#278524; Package developers-reference. Full text and rfc822 format available.

Acknowledgement sent to Frank Küster <frank@kuesterei.ch>:
New Bug report received and forwarded. Copy sent to Henning Makholm <henning@makholm.net>, Frank K�ster <frank@debian.org>, Adam Di Carlo <aph@debian.org>. Full text and rfc822 format available.

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

From: Frank Küster <frank@kuesterei.ch>
To: Debian Bug Tracking System <submit@bugs.debian.org>
Subject: developers-reference: Please add documentation on handling of orig.tar.gz files
Date: Wed, 27 Oct 2004 16:39:06 +0200
Package: developers-reference
Version: CVS-1.245
Severity: wishlist
Tags: patch

Dear Henning, dear Developers'-Reference-Team,

A couple of weeks ago I promised to Andreas Barth that I would
contribute a text on the proper handling of orig.tar.gz files. Here it
comes; it is mainly based on your, Henning's, mail to debian-devel
from January this year:

http://lists.debian.org/debian-devel/2004/01/msg01796.html

Therefore I would like to ask whether you agree with what I wrote and
with including it into the developers' reference. You wrote that you
intended it to be inserted into section 6.4.1, but either the numbers
have changed, or you made a typo. I have put it at the beginning of
"6. Best Packagin Practices", because the orig.tar.gz file is what you
start with.

I have added one more section on adding or changing binary files, and
tried to summarise the discussion on -devel about this. Please read
the part on dbs carefully - I tried to be neutral on it, although I
personally dislike its approach.

There's one point where I am not decided, and this is reflected by an
alternative text that is in the patch as a comment: I am unsure about
the right way to document the changes made. Currently, it seems to be
common to document the repackaging in README.Debian. But shouldn't
this rather be within the orig.tar.gz file in README.Debian-source or
similar? It should be possible to use the orig.tar.gz outside Debian,
and these "outsiders" should also have an easy way to find out what
has been changed.

Maybe this depends on the type of change - for a recompression it is
clearly not necessary. But generally, I would prefer a file in the
tarball. Should we take this discussion to -devel?

Regards, Frank

-- System Information
Debian Release: 3.0-bunk-2
Architecture: i386
Kernel: Linux alhambra 2.4.27 #1 Sam Sep 25 11:29:41 CEST 2004 i686
Locale: LANG=de_DE@euro, LC_CTYPE=de_DE@euro

Index: developers-reference.sgml
===================================================================
RCS file: /cvs/debian-doc/ddp/manuals.sgml/developers-reference/developers-reference.sgml,v
retrieving revision 1.245
diff -u -r1.245 developers-reference.sgml
--- developers-reference.sgml	8 Oct 2004 08:03:59 -0000	1.245
+++ developers-reference.sgml	27 Oct 2004 14:24:58 -0000
@@ -3409,6 +3409,214 @@
 from Debian developers.  Feel free to pick and choose whatever works
 best for you.
 
+    <sect id="bpp-origtargz">
+        <heading>Best practices for <file>orig.tar.gz</file> files</heading>
+	<p>
+   There are two kinds of original source tarballs: Pristine source
+   and repackaged upstream source.
+	</p>
+	<sect1 id="pristine source">
+	   <heading>Pristine source</heading>
+	   <p>   
+The defining characteristic of a pristine source tarball is that the
+.orig.tar.gz file is byte-for-byte identical to a tarball officially
+distributed to the upstream author. 
+<footnote>
+We cannot prevent upstream authors from changing the tarball
+they distribute without also upping the version number, so
+there can be no guarantee that a pristine tarball is identical
+to what upstream <em>currently</em> distributing at any point in
+time. All that can be expected is that it is identical to
+something that upstream once <em>did</em> distribute.
+
+If a difference arises later (say, if upstream notices that he wasn't
+using maximal comression in his original distribution and then
+re-<tt>gzip</tt>s it), that's just too bad. Since there is no good way
+to upload a new .orig.tar.gz for the same version, there is not even
+any point in treating this situation as a bug.
+</footnote>
+This makes it possible to use checksums to easily verify that all
+changes between Debian's version and upstream's are contained in the
+Debian diff. Also, if the original source is huge, upstream authors
+and others who already have the upstream tarball can (in principle)
+save download time if they want to inspect your packaging in detail.
+           </p>
+  	   <p>
+There is no universally accepted guidelines that upstream authors
+follow regarding to the directory structure inside their tarball, but
+dpkg-source is nevertheless able to deal with most upstream tarballs
+as pristine source. Its strategy is equivalent to the following:
+	  </p>
+	  <p>
+	  <enumlist>
+	     <item>
+Unpack the tarball in a empty temporary dicectory by doing
+
+<example>
+zcat path/to/&lt;packagename&gt;_&lt;upstream-version&gt;.orig.tar.gz | tar xf -
+</example>
+             </item>
+             <item>
+If, after this, the temporary directory contains nothing but one
+directory and no other files, rename that directory to
+<tt>&lt;packagename&gt;-&lt;upstream-version&gt;(.orig)</tt>, and be
+done. The name of the top-level directory in the tarball does not
+matter, and is forgotten.
+             </item>
+	     <item>
+Otherwise, the upstream tarball must have been packaged without
+a common top-level directory (shame on the upstream author!).
+Rename the temporary directory <em>itself</em> to
+<tt>&lt;packagename&gt;-&lt;upstream-version&gt;(.orig)</tt>.
+             </item>
+          </enumlist>
+	  </p>
+	  </sect1>
+	  <sect1 id="repackaged origtargz">
+	     <heading>Repackaged upstream source</heading>
+	     <p>
+You <strong>should</strong> upload packages with a pristine source
+tarball if possible, but there are various reasons why it might not be
+possible. This is the case if upstream does not distribute the source
+as gzipped tar at all, or if upstream's tarball contains non-DFGS-free
+material that you must remove before uploading.
+             </p>
+	     <p>
+In these cases the developer must construct a suitable .orig.tar.gz
+file himself. We refer to such a tarball as a "repackaged upstream
+source". Note that this is different from a Debian-native package; a
+repackaged source still comes with Debian-specific changes in a
+separate <tt>.diff.gz</tt> and still has a version number composed of
+<tt>&lt;upstream-version&gt;</tt> and
+<tt>&lt;debian-revision&gt;</tt>.
+             </p>
+	     <p>
+There may be cases where it is desirable to repackage the source even
+though upstream distributes a <tt>.tar.gz</tt> that could in principle
+be used in its pristine form. The most obvious is if
+<em>significant</em> space savings can be achieved by recompressing
+the tar archive or by removing genuinely useless cruft from the
+upstream archive. Use your own discretion here, but be prepared to
+defend your decision if you repackage source that could have been
+pristine.
+             </p>
+	     <p>
+A repackaged .orig.tar.gz
+             </p>
+	     <p>	     
+	     <enumlist>
+	     <item>
+<strong>must</strong> contain detailed, reproducible information how
+the repackaged source was obtained in <file>README.debian</file> or a
+similar file.
+	     </item>
+<!-- 	     <item> -->
+<!-- <strong>should</strong> contain a file called -->
+<!-- <file>README.Debian-source</file> or similar in which the process of -->
+<!-- repackaging is documented -->
+<!-- <footnote> -->
+<!-- This should be a "<em>must</em>" clause. It isn't because it is -->
+<!-- common, but bad practise to document this only in -->
+<!-- <file>README.debian</file>, i.e. in the <tt>diff.gz</tt>. -->
+<!-- </footnote>. -->
+<!-- 	     </item> -->
+	     <item>
+<!-- besides that,  --><strong>must not</strong> contain any file that does not come from the
+upstream author(s), or whose contents has been changed by you.
+<footnote>
+As a special exception, if the omission of non-free files would lead
+to the source failing to build without assistance from the Debian
+diff, it might be appropriate to instead edit the files, omitting only
+the non-free parts of them, and/or explain the situation in a
+README.Debian-source <!-- or similarly named --> file in the root of the source
+tree. But in that case please also urge the upstream author to make
+the non-free components easier seperable from the rest of the source.
+</footnote>
+             </item>
+	     <item>
+<p>
+<strong>should</strong>, except where impossible for legal reasons,
+preserve the entire building and portablility infrastructure provided
+by the upstream author. For example, it is not appropriate to omit
+source files that are used only when building on MS-DOS, or to omit a
+Makefile provided by upstream even if the first thing your
+<file>debian/rules</file> does is to overwrite it by running a
+configure script.
+</p>
+<p>
+(<em>Rationale:</em> It is common for Debian users who need to build
+software for non-Debian platforms to fetch the source from a Debian
+mirror rather than trying to locate a canonical upstream distribution
+point).
+</p>             </item>
+	     <item>
+<strong>should</strong> use
+<tt>&lt;packagename&gt;-&lt;upstream-version&gt;.orig</tt> as the name
+of the top-level directory in its tarball. This makes it possible to
+distinguish pristine tarballs from repackaged ones.
+             </item>
+	     <item>
+<strong>should</strong> be gzipped with maximal compression.
+             </item>
+	     </enumlist>
+	     </p>
+	     <p>
+The canonical way to meet the latter two points it to let
+<tt>dpkg-source -b</tt> construct the repackaged tarball from an
+unpacked directory.
+            </p>
+	</sect1>
+	<sect1 id="changed-binfiles">
+	<heading>Changing binary files "in" the <tt>diff.gz</tt></heading>
+	<p>
+Sometimes it is necessary to change binary files contained in the
+original tarball, or to add binary files that are not in it.
+<!-- <footnote> -->
+<!-- TODO: Find a simple example where this is necessary -->
+<!-- One reason for this might be  -->
+<!-- </footnote> -->
+If this is done by simply copying the files into the debianized
+source tree, <prgn>dpkg-source</prgn> will not be able to handle
+this. There are several possible ways to work around this. All have
+their advantages and disadvantages, and it is up to the maintainer to
+decide which to choose:
+           <list>
+	   <item>
+Create a repackaged upstream source and include the new or changed
+binary files in the repackaged <tt>orig.tar.gz</tt>. The disadvantage
+is that in this case the change is obscured and can only be found by
+looking into <file>README.Debian-source</file>.
+	   </item>
+	   <item>
+Include the file in the <file>debian</file> directory in
+<prgn>uuencode</prgn>d (or similar) form
+<footnote>
+The file should have a name that makes it clear which binary file it
+encodes. Usually, some postfix indicating the encoding should be
+appended to the original filename.
+</footnote>.  
+The file would then be decoded and copied to its place during the
+build process. The change will be visible quite easy, and the source
+can be kept pristine. On the other hand, this requires additional
+build-dependencies and might increase the danger of packaging bugs.
+        </item> 
+	<item>
+Some packages use <prgn>dbs</prgn> to manage patches to their upstream
+source, and always create a new <tt>orig.tar.gz</tt> file that
+contains the real <tt>orig.tar.gz</tt> in its toplevel
+directory. While this is questionable with respect to the preference
+for pristine source, it offers a compromise approach when binary files
+have to be changed: The modified or added binary files can be put into
+the newly created <tt>orig.tar.gz</tt> file, besides the real
+one. Thus they are clearly visible without getting problems within the
+<tt>diff.gz</tt>. The drawbacks, however, are the similar as for
+<prgn>uuencode</prgn>d files.
+	</item>
+        </list>
+	</p>
+	</sect1>
+    </sect>
+
     <sect id="bpp-debian-rules">
         <heading>Best practices for <file>debian/rules</file></heading>
         <p>



Information forwarded to debian-bugs-dist@lists.debian.org, Adam Di Carlo <aph@debian.org>:
Bug#278524; Package developers-reference. Full text and rfc822 format available.

Acknowledgement sent to Henning Makholm <henning@makholm.net>:
Extra info received and forwarded to list. Copy sent to Adam Di Carlo <aph@debian.org>. Full text and rfc822 format available.

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

From: Henning Makholm <henning@makholm.net>
To: Frank Küster <frank@kuesterei.ch>, 278524@bugs.debian.org
Cc: Debian Bug Tracking System <submit@bugs.debian.org>
Subject: Re: Bug#278524: developers-reference: Please add documentation on handling of orig.tar.gz files
Date: Wed, 27 Oct 2004 16:41:54 +0100
Scripsit Frank Küster

> Therefore I would like to ask whether you agree with what I wrote and
> with including it into the developers' reference.

It is OK with me, though I'm still not sure that "must" rules belong
in developers-reference.

> You wrote that you intended it to be inserted into section 6.4.1,
> but either the numbers have changed, or you made a typo.

I think the numbers have changed - there is a
    - reorder "Best Packaging Practices" a bit
changelog entry from since I wrote my emails. I don't remember what
6.4.1 used to be, though...

> I have added one more section on adding or changing binary files, and
> tried to summarise the discussion on -devel about this. Please read
> the part on dbs carefully - I tried to be neutral on it, although I
> personally dislike its approach.

I think the option

> +Create a repackaged upstream source and include the new or changed
> +binary files in the repackaged <tt>orig.tar.gz</tt>. The disadvantage
> +is that in this case the change is obscured and can only be found by
> +looking into <file>README.Debian-source</file>.

conflicts with the earlier

> +<!-- besides that,  --><strong>must not</strong> contain any file that does not come from the
> +upstream author(s), or whose contents has been changed by you.
> +<footnote>

It is true that some people on debian-devel suggested that changing
the file directly in the orig.tar.gz. But if they are right, then
there can be no "must" rule that forbids this strategy.

> +<strong>must</strong> contain detailed, reproducible information how
> +the repackaged source was obtained in <file>README.debian</file> or a
> +similar file.

Hm, "reproducible".... A cross-reference to the get-orig-source target
of debian/rules, defined by Policy §4.8 might be appropriate here. Or
might not; I'm not sure that the get-orig-source target is more than
vaporware.

> +Sometimes it is necessary to change binary files contained in the
> +original tarball, or to add binary files that are not in it.
> +<!-- <footnote> -->
> +<!-- TODO: Find a simple example where this is necessary -->
> +<!-- One reason for this might be  -->
> +<!-- </footnote> -->

Hm, perhaps the trademark-free-icons-for-Mozilla issue? (Unless the
icons in questions are xpm's).

-- 
Henning Makholm            "And why should I talk slaves' and fools' talk? I
                       don't want him to live for ever, and I know that he's
                   not going to live for ever whether I want him to or not."



Information forwarded to debian-bugs-dist@lists.debian.org, Adam Di Carlo <aph@debian.org>:
Bug#278524; Package developers-reference. Full text and rfc822 format available.

Acknowledgement sent to Henning Makholm <henning@makholm.net>:
Extra info received and forwarded to list. Copy sent to Adam Di Carlo <aph@debian.org>. Full text and rfc822 format available.

Information forwarded to debian-bugs-dist@lists.debian.org, Adam Di Carlo <aph@debian.org>:
Bug#278524; Package developers-reference. Full text and rfc822 format available.

Acknowledgement sent to frank@kuesterei.ch (Frank Küster):
Extra info received and forwarded to list. Copy sent to Adam Di Carlo <aph@debian.org>. Full text and rfc822 format available.

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

From: frank@kuesterei.ch (Frank Küster)
To: Henning Makholm <henning@makholm.net>
Cc: 278524@bugs.debian.org, Frank Küster <frank@debian.org>
Subject: Re: Bug#278524: developers-reference: Please add documentation on handling of orig.tar.gz files
Date: Wed, 27 Oct 2004 18:13:25 +0200
Henning Makholm <henning@makholm.net> wrote:

> Scripsit Frank Küster
>
>> Therefore I would like to ask whether you agree with what I wrote and
>> with including it into the developers' reference.
>
> It is OK with me, though I'm still not sure that "must" rules belong
> in developers-reference.

That's right. But on the other hand, I'd prefer to have the rule
somewhere rather than nowhere, and policy is frozen. If after some
"testing" inside the developers-reference some parts of this turn out to
be policy'able, we can still move them.

> I think the option
>
>> +Create a repackaged upstream source and include the new or changed
>> +binary files in the repackaged <tt>orig.tar.gz</tt>. The disadvantage
>> +is that in this case the change is obscured and can only be found by
>> +looking into <file>README.Debian-source</file>.
>
> conflicts with the earlier
>
>> +<!-- besides that,  --><strong>must not</strong> contain any file that does not come from the
>> +upstream author(s), or whose contents has been changed by you.
>> +<footnote>

Right. I intended to use README.debian, not README.Debian-source.

> It is true that some people on debian-devel suggested that changing
> the file directly in the orig.tar.gz. But if they are right, then
> there can be no "must" rule that forbids this strategy.

You're right, this is inconsistent. Either we need to restrict the "must
not contain" to non-binary files (change in new 6.1.2), or we should
forbid repackaging for the addition/change of binary files (change in
new 6.1.3).

>> +<strong>must</strong> contain detailed, reproducible information how
>> +the repackaged source was obtained in <file>README.debian</file> or a
>> +similar file.
>
> Hm, "reproducible".... A cross-reference to the get-orig-source target
> of debian/rules, defined by Policy §4.8 might be appropriate here. Or
> might not; I'm not sure that the get-orig-source target is more than
> vaporware.

Maybe it's vaporware because it's not in the developers-reference, only
in policy, which nobody reads? I'll give it a try.

>> +Sometimes it is necessary to change binary files contained in the
>> +original tarball, or to add binary files that are not in it.
>> +<!-- <footnote> -->
>> +<!-- TODO: Find a simple example where this is necessary -->
>> +<!-- One reason for this might be  -->
>> +<!-- </footnote> -->
>
> Hm, perhaps the trademark-free-icons-for-Mozilla issue? (Unless the
> icons in questions are xpm's).

Can you give me an URL, or just write the footnote? I can imagine what
happened, but I don't really know.

Thank you, Frank
-- 
Frank Küster
Inst. f. Biochemie der Univ. Zürich
Debian Developer




Information forwarded to debian-bugs-dist@lists.debian.org, Adam Di Carlo <aph@debian.org>:
Bug#278524; Package developers-reference. Full text and rfc822 format available.

Acknowledgement sent to Henning Makholm <henning@makholm.net>:
Extra info received and forwarded to list. Copy sent to Adam Di Carlo <aph@debian.org>. Full text and rfc822 format available.

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

From: Henning Makholm <henning@makholm.net>
To: Frank Küster <frank@kuesterei.ch>
Cc: 278524@bugs.debian.org
Subject: Re: Bug#278524: developers-reference: Please add documentation on handling of orig.tar.gz files
Date: Wed, 27 Oct 2004 17:23:37 +0100
Scripsit Frank Küster
> Henning Makholm <henning@makholm.net> wrote:

> > It is true that some people on debian-devel suggested that changing
> > the file directly in the orig.tar.gz. But if they are right, then
> > there can be no "must" rule that forbids this strategy.

> You're right, this is inconsistent. Either we need to restrict the "must
> not contain" to non-binary files (change in new 6.1.2), or we should
> forbid repackaging for the addition/change of binary files (change in
> new 6.1.3).

Debian-devel did not really reach a consensus last time. It might be
worth trying to bring it up again.

> > Hm, perhaps the trademark-free-icons-for-Mozilla issue? (Unless the
> > icons in questions are xpm's).

> Can you give me an URL, or just write the footnote?

Right now, neither: too much real-life pressure to go digging in the
list archives. I skipped most of the threads concerning that issue on
debian-legal, so all I remember was that there was at least talk that
we'd have to replace some instances of the fox-and-planet icon. I
don't remember exactly how it came out.

-- 
Henning Makholm                        "*Jeg* tænker *strax* på kirkemødet i
                     Konstantinopel i 381 e.Chr. om det arianske kætteri..."



Information forwarded to debian-bugs-dist@lists.debian.org, Adam Di Carlo <aph@debian.org>:
Bug#278524; Package developers-reference. Full text and rfc822 format available.

Acknowledgement sent to opal@debian.org:
Extra info received and forwarded to list. Copy sent to Adam Di Carlo <aph@debian.org>. Full text and rfc822 format available.

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

From: Ola Lundqvist <opal@debian.org>
To: Frank Küster <frank@kuesterei.ch>, 278524@bugs.debian.org
Subject: Re: Bug#278524: developers-reference: Please add documentation on handling of orig.tar.gz files
Date: Wed, 27 Oct 2004 22:20:05 +0200
Hello

Some comments on the text below.

On Wed, Oct 27, 2004 at 04:39:06PM +0200, Frank Küster wrote:
> +  	   <p>
> +There is no universally accepted guidelines that upstream authors
> +follow regarding to the directory structure inside their tarball, but
> +dpkg-source is nevertheless able to deal with most upstream tarballs
> +as pristine source. Its strategy is equivalent to the following:
> +	  </p>

I suggest that you rephrase the following text to make it more clear that
it is dpkg-source that do this. I missed this little crucial part and thought
that this is what I should do. :)

> +	  <p>
> +	  <enumlist>
> +	     <item>
> +Unpack the tarball in a empty temporary dicectory by doing
It unpacks ...
> +
> +<example>
> +zcat path/to/&lt;packagename&gt;_&lt;upstream-version&gt;.orig.tar.gz | tar xf -
> +</example>
> +             </item>
> +             <item>
> +If, after this, the temporary directory contains nothing but one
> +directory and no other files, rename that directory to

....                             it renames that ...

> +<tt>&lt;packagename&gt;-&lt;upstream-version&gt;(.orig)</tt>, and be
> +done. The name of the top-level directory in the tarball does not

Remove ", and be done.".

> +matter, and is forgotten.
> +             </item>
> +	     <item>
> +Otherwise, the upstream tarball must have been packaged without
> +a common top-level directory (shame on the upstream author!).
> +Rename the temporary directory <em>itself</em> to
> +<tt>&lt;packagename&gt;-&lt;upstream-version&gt;(.orig)</tt>.
> +             </item>

Do dpkg-source handle this? I assume so but it is not perfectly clear.

> +          </enumlist>
> +	  </p>
> +	  </sect1>
> +	  <sect1 id="repackaged origtargz">
> +	     <heading>Repackaged upstream source</heading>
> +	     <p>
> +You <strong>should</strong> upload packages with a pristine source
> +tarball if possible, but there are various reasons why it might not be
> +possible. This is the case if upstream does not distribute the source
> +as gzipped tar at all, or if upstream's tarball contains non-DFGS-free
> +material that you must remove before uploading.
> +             </p>
> +	     <p>
> +In these cases the developer must construct a suitable .orig.tar.gz
> +file himself. We refer to such a tarball as a "repackaged upstream
> +source". Note that this is different from a Debian-native package; a

Please rephrase this as "Note that a "repackaged upstream source" is not
the same thing as a Debian-native package. A ...

> +repackaged source still comes with Debian-specific changes in a
> +separate <tt>.diff.gz</tt> and still has a version number composed of
> +<tt>&lt;upstream-version&gt;</tt> and
> +<tt>&lt;debian-revision&gt;</tt>.
> +             </p>
> +	     <p>
> +There may be cases where it is desirable to repackage the source even
> +though upstream distributes a <tt>.tar.gz</tt> that could in principle
> +be used in its pristine form. The most obvious is if
> +<em>significant</em> space savings can be achieved by recompressing
> +the tar archive or by removing genuinely useless cruft from the
> +upstream archive. Use your own discretion here, but be prepared to
> +defend your decision if you repackage source that could have been
> +pristine.
> +             </p>
> +	     <p>
> +A repackaged .orig.tar.gz
> +             </p>
> +	     <p>	     
> +	     <enumlist>
> +	     <item>
> +<strong>must</strong> contain detailed, reproducible information how
> +the repackaged source was obtained in <file>README.debian</file> or a
> +similar file.

I do actually NOT think the README.debian file is suitable for this. This
file is commonly used for things that the user of the package will read in
order to configure it correctly. Source manipluation information should not
be placed there, just as INSTALL documentation should not be a part of the
binary package.

Please write README.Debian-source or similar instead. Maybe document this in
the rules file instead?

And I do not think "must" has anything to do with this document. :)

Anyway you certainly cleared a few things out for me so I will create
more pristine sources now. Thanks. :)

*SNIP*

Regards,

// Ola

-- 
 --------------------- Ola Lundqvist ---------------------------
/  opal@debian.org                     Annebergsslingan 37      \
|  opal@lysator.liu.se                 654 65 KARLSTAD          |
|  +46 (0)54-10 14 30                  +46 (0)70-332 1551       |
|  http://www.opal.dhs.org             UIN/icq: 4912500         |
\  gpg/f.p.: 7090 A92B 18FE 7994 0C36  4FE4 18A1 B1CF 0FE5 3DD9 /
 ---------------------------------------------------------------



Information forwarded to debian-bugs-dist@lists.debian.org, Adam Di Carlo <aph@debian.org>:
Bug#278524; Package developers-reference. Full text and rfc822 format available.

Acknowledgement sent to debian-devel <debian-devel@lists.debian.org>:
Extra info received and forwarded to list. Copy sent to Adam Di Carlo <aph@debian.org>. Full text and rfc822 format available.

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

From: frank@kuesterei.ch (Frank Küster)
To: 278524@bugs.debian.org
Cc: debian-devel <debian-devel@lists.debian.org>, debian-policy@lists.debian.org
Subject: Documentation on handling of orig.tar.gz files for Developer's Reference or for Debian Policy
Date: Mon, 01 Nov 2004 10:58:55 +0100
[I'm not subscribed to -policy, please respect M-F-t or Cc me]

Hi all,

early this year, some guidelines for the handling of orig.tar.gz files
for Debian packages were discussed on debian-devel
(http://lists.debian.org/debian-devel/2004/01/msg01796.html). I have
tried to write together what seemed to be a consensus on that, and
submitted it as a wishlist bug (#278524) to the Developer's
Reference. A new version of the added section, 6.1, is available
(slightly updated compared to the original patch) at

http://people.debian.org/~frank/ch-best-pkging-practices.en.html

There are some points, however, that are unclear, or where no
consensus was achieved. I would be glad to receive some feedback on the
following points:

1. Should this be included in the Developer's Reference, or shouldn't
   (parts of) it rather be included in Debian Policy? If you think it
   should be in Policy, would it be appropriate to include it in the
   Developer's Reference as long as Policy is frozen pre-sarge?

The main discussion on the list back then was about reasons for
repackaging, namely whether the need to add or change binary files is a
reason to create a new orig.tar.gz file. In the new section 6.1.3, I
have tried to summarise the different possibilities mentioned without
giving one of them preference. However, this is inconsistent with the
following sentence in 6.1.2 that I adopted from Henning for the
description of "repackaged upstream source":

,----
| A repackaged .orig.tar.gz [...] must not contain any file that does not
| come from the upstream author(s), or whose contents has been changed by
| you. 
`----

This poses the following questions:

2. Do you think that - although alternative methods exist - a binary
   file may be changed or added by creating a new orig.tar.gz file? Or
   do you think this must be done by adding a uuencode'd file (or
   similar) in diff.gz?

3. If you think a binary change is a reason for a new orig.tar.gz, do
   you think the sentence cited above should get an exception for binary
   files, or should it rather be dropped or rephrased completely? [Note
   also the footnote the sentence has]

4. What is the right place to document the changes made to the
   orig.tar.gz file? Some possible places would be

   - the get-orig-source target in debian/rules (see Policy 4.8)

   - a README.Debian-source in the debian directory (i.e. in the
     diff.gz) 

   - a README.Debian-source file added to the orig.tar.gz 


Personally, I think that the last possibility should be a
requirement. The main reason is that I think that our archive should be
a good source for Free Software even when one does not want to use the
Debian Operating System (and indeed we provide lots of mirrors for
software with no or only a couple of mirrors). It would be annoying if
one had to download the diff.gz just in order to learn what was changed
in the orig.tar.gz file.

Having the get-orig-source target is nice, but there might be cases
where this is impractical.


One final question: I'd like to have a footnote at the beginning of the
new 6.1.3, explaining a simple case where it is necessary to add or
change a binary file. I can imagine several, but I'd like to have one
that can be explained in one or two short sentences without lengthy
discussions about DFSG-freeness or non-automated generation of pdf files
or whatever. Suggestions?

Thanks for reading,
Frank

-- 
Frank Küster
Inst. f. Biochemie der Univ. Zürich
Debian Developer




Information forwarded to debian-bugs-dist@lists.debian.org, Adam Di Carlo <aph@debian.org>:
Bug#278524; Package developers-reference. Full text and rfc822 format available.

Acknowledgement sent to frank@kuesterei.ch (Frank Küster):
Extra info received and forwarded to list. Copy sent to Adam Di Carlo <aph@debian.org>. Full text and rfc822 format available.

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

From: frank@kuesterei.ch (Frank Küster)
To: 278524@bugs.debian.org
Cc: Ola Lundqvist <opal@debian.org>, Henning Makholm <henning@makholm.net>, Andreas Barth <aba@not.so.argh.org>
Subject: Re: Bug#278524: developers-reference: Please add documentation on handling of orig.tar.gz files
Date: Mon, 01 Nov 2004 10:58:46 +0100
Hello again,

Frank Küster <frank@kuesterei.ch> wrote:

> There's one point where I am not decided, and this is reflected by an
> alternative text that is in the patch as a comment: I am unsure about
> the right way to document the changes made. 

I will write a separate mail with Cc: to debian-devel and debian-policy
(and Mail-Followup-to: debian-devel, and no copies to you). In this mail
I will ask this question and, more imporantly, the question about
including changed binary files in a repackaged orig.tar.gz, to these
lists, hoping for some consensus. So far, let me thank you for your
input. I have put an updated copy of the generated html file to

http://people.debian.org/~frank/ch-best-pkging-practices.en.html

In particular, I have made the changes Ola requested, they seemed very
sensible to me. (By the way, I know Ole, but not Ola - are you a woman
or a man?)

Regards, Frank
-- 
Frank Küster
Inst. f. Biochemie der Univ. Zürich
Debian Developer




Message sent on to Frank Küster <frank@kuesterei.ch>:
Bug#278524. Full text and rfc822 format available.

Message #43 received at 278524-submitter@bugs.debian.org (full text, mbox):

From: Andreas Barth <aba@not.so.argh.org>
To: 278524-submitter@bugs.debian.org
Subject: developers-reference and orig.tar.gz - status?
Date: Sun, 7 Nov 2004 14:22:55 +0100
Hi Frank,

I've seen some discussion, but I didn't follow up the latest status. Is
there now a consensus and a final patch? If so, I'd like to commit it
soon.

Thanks,
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



Information forwarded to debian-bugs-dist@lists.debian.org, Adam Di Carlo <aph@debian.org>:
Bug#278524; Package developers-reference. Full text and rfc822 format available.

Acknowledgement sent to frank@kuesterei.ch (Frank Küster):
Extra info received and forwarded to list. Copy sent to Adam Di Carlo <aph@debian.org>. Full text and rfc822 format available.

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

From: frank@kuesterei.ch (Frank Küster)
To: Andreas Barth <aba@not.so.argh.org>
Cc: 278524@bugs.debian.org
Subject: Re: developers-reference and orig.tar.gz - status?
Date: Wed, 17 Nov 2004 10:55:06 +0100
[Message part 1 (text/plain, inline)]
Andreas Barth <aba@not.so.argh.org> schrieb:

> Hi Frank,
>
> I've seen some discussion, but I didn't follow up the latest status. Is
> there now a consensus

Not too many people were involved in the discussion. This could mean
that they don't care, or that they feel well represented by the ones
that take part.

Regarding the first two subsections (description of pristine and
repackaged orig.tar.gz) I think there was no disagreement left. The
third one (adding binary files) was more controversial, but the
discussion stopped rather suddenly. To me it seemed it stopped because
Manoj had the better arguments, nobody could find anything against his
opinion - this would qualify as consensus. 

The guy who "lost" in this argument may view things differently, but
personally I think we cannot take into account what is unsaid, and we (I
as the bug submitter and you as one of the maintainers) have to decide
ourselves. If we make a decisision that others do not agree with, they
can still file a bug.

> and a final patch? If so, I'd like to commit it
> soon.

Therefore, I would suggest to commit the following patch, which includes
all three subsections. I also have tried to incorporate all hints given
(in the BTS or on -devel) on unclear wording, typos etc.

Regards, Frank

[origtargz-handling.patch (text/x-patch, attachment)]
[Message part 3 (text/plain, inline)]

-- 
Frank Küster
Inst. f. Biochemie der Univ. Zürich
Debian Developer

Tags added: pending Request was from Andreas Barth <aba@not.so.argh.org> to control@bugs.debian.org. Full text and rfc822 format available.

Reply sent to Andreas Barth <aba@not.so.argh.org>:
You have taken responsibility. Full text and rfc822 format available.

Notification sent to Frank Küster <frank@kuesterei.ch>:
Bug acknowledged by developer. Full text and rfc822 format available.

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

From: Andreas Barth <aba@not.so.argh.org>
To: 278524-close@bugs.debian.org
Subject: Bug#278524: fixed in developers-reference 3.3.6
Date: Sun, 01 May 2005 16:32:16 -0400
Source: developers-reference
Source-Version: 3.3.6

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

developers-reference-fr_3.3.6_all.deb
  to pool/main/d/developers-reference/developers-reference-fr_3.3.6_all.deb
developers-reference_3.3.6.dsc
  to pool/main/d/developers-reference/developers-reference_3.3.6.dsc
developers-reference_3.3.6.tar.gz
  to pool/main/d/developers-reference/developers-reference_3.3.6.tar.gz
developers-reference_3.3.6_all.deb
  to pool/main/d/developers-reference/developers-reference_3.3.6_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 278524@bugs.debian.org,
and the maintainer will reopen the bug report if appropriate.

Debian distribution maintenance software
pp.
Andreas Barth <aba@not.so.argh.org> (supplier of updated developers-reference 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.7
Date: Sun, 23 Jan 2005 16:08:49 -0700
Source: developers-reference
Binary: developers-reference-fr developers-reference
Architecture: source all
Version: 3.3.6
Distribution: unstable
Urgency: low
Maintainer: Debian Documentation Project <debian-doc@lists.debian.org>
Changed-By: Andreas Barth <aba@not.so.argh.org>
Description: 
 developers-reference - guidelines and information for Debian developers
 developers-reference-fr - guidelines and information for Debian developers, in French
Closes: 263114 278524 284714 285381 285458 285687 290019 290583 290584 291698 292354 292946
Changes: 
 developers-reference (3.3.6) unstable; urgency=low
 .
   * Andreas Barth
     - closes: and NMUs/experimental uploads. Closes: #284714
     - madison is on merkel.
     - more gender-neutral. Closes: #290583, #290584, #263114
     - explain current incoming. Closes: #290019
     - remove broken sponsoring URL. Closes: #291698
     - add handling hints about orig.tar.gz. Thanks, Frank. Closes: #278524
     - duplicate bug reports should be merged. Closes: #285381
     - if you're on vacation, please check whether someone needs keysigning.
       Closes: #285458
     - freenode has developer cloacks. Closes: #285687
     - cleaned up uploaders / maintainer field
     - explain how dak detects NMUs. Closes: #292354
     - add "mass" to lots of bugs. Closes: #292946
     - sync NM rules with reality.
   * Frédéric Bothamy
     - French translation updated to version 3.3.6
Files: 
 23334cbdd685287ec32bab09b12f2532 695 doc optional developers-reference_3.3.6.dsc
 daaa72d5c9d0a62f76114cf131d1698f 265117 doc optional developers-reference_3.3.6.tar.gz
 d88dcf9aa3eaec593711ad5ae288c25e 580084 doc optional developers-reference_3.3.6_all.deb
 f4da357355e391e912d70a2057952d8a 227546 doc optional developers-reference-fr_3.3.6_all.deb

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

iEYEARECAAYFAkJ1OFoACgkQmdOZoew2oYW8ZQCfciMOW9zRZ+dWx98FxUwBAJSO
VoUAn0BjRHOr21BjdT3eoGSHeFwL9N77
=A5QN
-----END PGP SIGNATURE-----




Send a report that this bug log contains spam.


Debian bug tracking system administrator <owner@bugs.debian.org>. Last modified: Fri Apr 18 16:18:01 2014; Machine Name: buxtehude.debian.org

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