Bug#42554: A proposal for README.Debian

[Richard Braakman <dark@xs4all.nl>]

Stephane Bortzmeyer wrote:
> Your package may contain a /usr/share/doc/package/README.Debian
> file. It is mandatory to have one if you modified the source code of
> the upstream package.

Ah... I smell a Lintian check :-)

I second this proposal, by the way.  It looks interesting.

> This file should document:
> 
> - the changes you made for the Debian package. [...]

Currently, this description must go in the copyright file, where it
doesn't really seem to belong.  I suggest an amendment to this proposal,
to change section 6.5 ("Copyright information") as well:

     In addition, the copyright file must say where the upstream sources
-    (if any) were obtained, and explain briefly what modifications were
-    made in the Debian version of the package compared to the upstream
-    one. It must name the original authors of the package and the Debian
-    maintainer(s) who were involved with its creation.
+    (if any) were obtained,, and it must name the original authors of
+    the package and the Debian maintainer(s) who were involved with
+    its creation.

> - the rationale for choosing such or such options in the debian/rules when 
> calling configure and/or make.

Careful here.  This could be a lot of needless detail, much of which
should be in the form of comments in the debian/rules file instead.
(I don't really want to explain why I set --include=/usr/include when
configuring lesstif, particularly since I don't really know myself :).

There should be a description, however, of the configuration choices
that were made that are visible to the user.

> - the Debian packages you need to recompile this package. The Debian
> packaging system does not know about formal source dependencies.
> Therefore, if the source of a package does not compile, the user has
> to guess what you need. It is better to tell it explicitely.

This belongs in the source package, I think.  There's no need for it
in a binary package.  The first thing you need when recompiling a
package is the source package itself, which can then list further
dependencies.

Also, there's finally a proposal in the works for describing source
dependencies in a formal way.  Let's not do it in two different ways.

Richard Braakman