Bug#42554: A proposal for README.Debian
Stephane Bortzmeyer wrote:
> The current Policy manual says almost nothing about the README.Debian file. I
> suggest to add a section 6.8 (in the "Documentation" chapter) or something
> like that:
>
> 6.8 README.Debian
>
> Your package may contain a /usr/share/doc/package/README.Debian file.
I agree with everything you say up to here.
>From here on out, I think you have a serious problem. You are adding to
policy something we already do (include a README.Debian file), but you are
changing the whole purpose of it in the process! You'd do much better to
just document current practices in policy.
What README.Debian files are currently used for in my experience is:
- Document user-visible changes made to the package. This can be what
options were compiled in, paths that were changed, permissions difference,
whatever. The key is they are things you will want to know about when you
install the package, as an end user.
- Document common bugs and FAQ's about the package.
> It is mandatory to have one if you modified the source code of the upstream package.
The user really isn't interested to know that I modified an #ifdef in an
obscure .h file to make a package build with libc6.
Document souce changes that have a _user visible_ effect, sure. But not
every change to the source. Those are all documented in the .diff.
> - the changes you made for the Debian package. Remember that some upstream
> authors are very picky about such changes and that users have the right to be
> informed of the Debian peculiarities. Otherwise, they may fill in a bug report
> upstream for Debian changes, thus confusing the upstream maintainer. Yes, the
> '.diff' file exists but it's easier to read a three-lines summary than a diff
> file.
Yes upstream authors should be made aware of any changes you have to make.
But this is not the venue to use to communicate with upstream authors. They
have email addresses.
Once again, I agree, any "peculiarities" that are _user visible_ should be
documented here.
> - the rationale for choosing such or such options in the debian/rules when
> calling configure and/or make.
Same here.
> - 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 is the wrong place for such a thing. If you want it in a README sysle
file, use debian/README.source or something, which is available when the
source package is unpacked. This information does not need to be present in
binary packages.
Anyway, other posts on this threat have beat this into the ground talking
about the other source-dependancies idea.
--
see shy jo
Reply to: