Documentation on handling of orig.tar.gz files for Developer's Reference or for Debian Policy

[frank@kuesterei.ch (Frank Küster)]

[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