Re: Bug#42554: A proposal for README.Debian
>>>>> "Stephane" == Stephane Bortzmeyer <bortzmeyer@debian.org> writes:
Stephane> The current Policy manual says almost nothing about the
Stephane> README.Debian file. I suggest to add a section 6.8 (in
Stephane> the "Documentation" chapter) or something like that:
Stephane> 6.8 README.Debian
Stephane> Your package may contain a
Stephane> /usr/share/doc/package/README.Debian file. It is
Stephane> mandatory to have one if you modified the source code of
Stephane> the upstream package.
Some of us already have a README.Debian file that is used for other
purposes. Now you want to make one mandatory?
Stephane> This file should document:
Stephane> - the changes you made for the Debian package. Remember
Stephane> that some upstream authors are very picky about such
Stephane> changes and that users have the right to be informed of
Stephane> the Debian peculiarities. Otherwise, they may fill in a
Stephane> bug report upstream for Debian changes, thus confusing
Stephane> the upstream maintainer. Yes, the '.diff' file exists
Stephane> but it's easier to read a three-lines summary than a
Stephane> diff file.
As has been pointed out by others on this list, policy
already dictates that this information should be in the
/usr/share/doc/<package-name>/copyright file. See Section 6.5
"Copyright information."
Stephane> - the rationale for choosing such or such options in the
Stephane> debian/rules when calling configure and/or make.
>>>>> "aj" == Anthony Towns <aj@azure.humbug.org.au> writes:
aj> Why shouldn't this simply be in the debian/rules file where it's
aj> convenient, both to change when you change the configure and/or
aj> make options, and to read when you notice someone's setting
aj> weird options in the rules file?
I agree. It's best to keep both together.
Stephane> - the Debian packages you need to recompile this
Stephane> package. The Debian packaging system does not know about
Stephane> formal source dependencies. Therefore, if the source of
Stephane> a package does not compile, the user has to guess what
Stephane> you need. It is better to tell it explicitely.
Why does this have to be in the binary deb package? In my opinion, it
should be with sources where it is useful. In fact, this might have
already been mentioned by the policy manual:
------------------------------------------------------------------------
6.3. Additional documentation
-----------------------------
[...]
It is often a good idea to put text information files (`README's,
changelogs, and so forth) that come with the source package in
`/usr/share/doc/<package>' in the binary package. However, you don't
need to install the instructions for building and installing the
package, of course!
------------------------------------------------------------------------
I assume that this also applies to Debian requirements for building a
package for the same reasons.
Brian
Reply to: