Bug#42554: A proposal for README.Debian
Has this proposal been effectively rejected? Julian =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- Julian Gilbey, Dept of Maths, QMW, Univ. of London. [EMAIL PROTECTED] Debian GNU/Linux Developer, see http://www.debian.org/~jdg
Bug#42554: A proposal for README.Debian
Package: debian-policy Version: 3.0.1.0 Severity: wishlist [Cc: me if you reply, I'm not on debian-policy.] 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. It is mandatory to have one if you modified the source code of the upstream package. This file should document: - 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. - the rationale for choosing such or such options in the debian/rules when calling configure and/or make. - 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.
Bug#42554: A proposal for README.Debian
On Fri, Aug 06, 1999 at 11:59:38AM +0200, 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 Something to this effect should definitely be added. It might even be worth mentioning that a TODO.Debian can be helpful too. So on the presumption I can second this with a mild difference of opinion, I'd like to do that. 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. I'd prefer to just say it should document these changes, rather than make it mandatory. :-/ - the rationale for choosing such or such options in the debian/rules when calling configure and/or make. Why shouldn't this simply be in the debian/rules file where it's convenient, both to change when you change the configure and/or make options, and to read when you notice someone's setting weird options in the rules file? - 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. There's an existing proposal to have proper build dependencies, so this is hopefully redundant. Cheers, aj -- Anthony Towns [EMAIL PROTECTED] http://azure.humbug.org.au/~aj/ I don't speak for anyone save myself. PGP encrypted mail preferred. ``The thing is: trying to be too generic is EVIL. It's stupid, it results in slower code, and it results in more bugs.'' -- Linus Torvalds pgp9FHW7jebIq.pgp Description: PGP signature
Bug#42554: A proposal for README.Debian
On Friday 6 August 1999, at 22 h 21, the keyboard of Anthony Towns aj@azure.humbug.org.au wrote: I'd prefer to just say it should document these changes, rather than make it mandatory. :-/ I was thinking about the huge flame-war, both on debian-devel and on the News, triggered by a paranoiac upstream maintainer who claimed loudly everywhere that Debian was making undocumented changes to its Sacred Program. - the rationale for choosing such or such options in the debian/rules when calling configure and/or make. Why shouldn't this simply be in the debian/rules file where it's convenient, Hmmm, because debian/rules is read by people who want to recompile (possibly with different options) and README.debian by ordinary system administrators, who just want to know? Remember that debian/rules is not in the binary package. There's an existing proposal to have proper build dependencies, so this is hopefully redundant. I don't think we should write the Policy by taking into account changes which will be integrated in the next twenty years. Seeing the buglist of dpkg, I seriously doubt that source dependencies will be implemented soon. While a change in the Policy's Documentation section is much lighter.
Bug#42554: A proposal for README.Debian
On Fri, Aug 06, 1999 at 11:59:38AM +0200, Stephane Bortzmeyer wrote: - the changes you made for the Debian package. How does this relate to the second paragraph of section 6.5 Copyright information? 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. - the Debian packages you need to recompile this package. The Debian packaging system does not know about formal source dependencies. It will, soon. I don't think it is necessary to have the information duplicated in README.Debian. -- %%% Antti-Juhani Kaijanaho % [EMAIL PROTECTED] % http://www.iki.fi/gaia/ %%% ... memory leaks are quite acceptable in many applications ... (Bjarne Stroustrup, The Design and Evolution of C++, page 220)
Bug#42554: A proposal for README.Debian
Please, write shorter lines! On Fri, Aug 06, 1999 at 02:40:06PM +0200, Stephane Bortzmeyer wrote: I don't think we should write the Policy by taking into account changes which will be integrated in the next twenty years. Build-time dependencies can be implemented right now, as soon as we agree on the interface. There is an active policy proposal on this, go join the discussion. Seeing the buglist of dpkg, I seriously doubt that source dependencies will be implemented soon. You don't seem to understand the fact that build-time dependencies require only minimal changes to dpkg - and all this to scripts, the dpkg executable need not be changed. I have already produced a patch based on an earlier version of the interface draft. And actually, build-time dependencies are already implemented in the sbuild daemon. While a change in the Policy's Documentation section is much lighter. It's about as light as my build-time dependency proposal. -- %%% Antti-Juhani Kaijanaho % [EMAIL PROTECTED] % http://www.iki.fi/gaia/ %%% ... memory leaks are quite acceptable in many applications ... (Bjarne Stroustrup, The Design and Evolution of C++, page 220)
Bug#42554: A proposal for README.Debian
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
Bug#42554: A proposal for README.Debian
On Fri, Aug 06, 1999 at 02:40:06PM +0200, Stephane Bortzmeyer wrote: - the rationale for choosing such or such options in the debian/rules when calling configure and/or make. Why shouldn't this simply be in the debian/rules file where it's convenient, Hmmm, because debian/rules is read by people who want to recompile (possibly with different options) and README.debian by ordinary system administrators, who just want to know? Remember that debian/rules is not in the binary package. Oh. I just didn't see any reason why a sysadmin would particularly care unless they were about to recompile it. I guess I just don't see what relevance compile options have without the code that they're compiling. At least in the common case. There's an existing proposal to have proper build dependencies, so this is hopefully redundant. I don't think we should write the Policy by taking into account changes which will be integrated in the next twenty years. Seeing the buglist of dpkg, I seriously doubt that source dependencies will be implemented soon. While a change in the Policy's Documentation section is much lighter. I haven't been following too closely, but it looked like they were about ready to go, modulo some minor disagreements (with code and all). But yeah, if they're not, this isn't a bad alternative. (although having your rules file check for it and die with an informative error message seems more convenient. *shrug*) Cheers, aj -- Anthony Towns [EMAIL PROTECTED] http://azure.humbug.org.au/~aj/ I don't speak for anyone save myself. PGP encrypted mail preferred. ``The thing is: trying to be too generic is EVIL. It's stupid, it results in slower code, and it results in more bugs.'' -- Linus Torvalds pgpAEs8gihwMT.pgp Description: PGP signature
Bug#42554: A proposal for README.Debian
On Friday 6 August 1999, at 15 h 59, the keyboard of Antti-Juhani Kaijanaho [EMAIL PROTECTED] wrote: How does this relate to the second paragraph of section 6.5 Copyright information? I've missed this line, sorry. Isn't it strange to have technical information like this one in a copyright file? Who will have the idea to read here? system does not know about formal source dependencies. It will, soon. Yeah, yeah, sure. You'll patch dpkg-dev yourself?
Re: Bug#42554: A proposal for README.Debian
Stephane == Stephane Bortzmeyer [EMAIL PROTECTED] 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
Bug#42554: A proposal for README.Debian
On Fri, Aug 06, 1999 at 03:04:13PM +0200, Stephane Bortzmeyer wrote: I've missed this line, sorry. Isn't it strange to have technical information like this one in a copyright file? Not at all. Changes made to a program are very much an issue of copyright. Who will have the idea to read here? Everybody who knows Debian policy. -- %%% Antti-Juhani Kaijanaho % [EMAIL PROTECTED] % http://www.iki.fi/gaia/ %%% ... memory leaks are quite acceptable in many applications ... (Bjarne Stroustrup, The Design and Evolution of C++, page 220)
Bug#42554: A proposal for README.Debian
On Friday 6 August 1999, at 23 h 2, the keyboard of Anthony Towns aj@azure.humbug.org.au wrote: Oh. I just didn't see any reason why a sysadmin would particularly care unless they were about to recompile it. I agree with Richard Braakman: you have two sort of compile options. Those who were necessary to build but have no visible influence for the user of a binary package (--include=/foo/bar) and those who do have an influence and are of interest to all users (not only the sysadmin, BTW), like -DCRLF in netatalk.
Bug#42554: A proposal for README.Debian
On Fri, Aug 06, 1999 at 03:24:26PM +0200, Stephane Bortzmeyer wrote: Oh. I just didn't see any reason why a sysadmin would particularly care unless they were about to recompile it. I agree with Richard Braakman: you have two sort of compile options. Those who were necessary to build but have no visible influence for the user of a binary package (--include=/foo/bar) and those who do have an influence and are of interest to all users (not only the sysadmin, BTW), like -DCRLF in netatalk. Ah, yes, I see. Probably some different wording would be better (user visible like Richard suggests maybe), but this would be very nice. Cheers, aj -- Anthony Towns [EMAIL PROTECTED] http://azure.humbug.org.au/~aj/ I don't speak for anyone save myself. PGP encrypted mail preferred. ``The thing is: trying to be too generic is EVIL. It's stupid, it results in slower code, and it results in more bugs.'' -- Linus Torvalds
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
