Re: New README.source documentation for Debian packages
also sprach Russ Allbery [EMAIL PROTECTED] [2008.04.29.0113 +0200]: Here is a sample of the sort of documentation that would satisfy this recommendation, written for a package that's using quilt: Might I suggest that for such cases, a common file explaining how to use quilt can be used or better yet: referred to? -- .''`. martin f. krafft [EMAIL PROTECTED] : :' : proud Debian developer, author, administrator, and user `. `'` http://people.debian.org/~madduck - http://debiansystem.info `- Debian - when you have better things to do than fixing systems military intelligence is a contradiction in terms. -- groucho marx digital_signature_gpg.asc Description: Digital signature (see http://martin-krafft.net/gpg/)
Re: New README.source documentation for Debian packages
On Tue, Apr 29, 2008 at 03:00:40PM +0200, martin f krafft wrote: also sprach Russ Allbery [EMAIL PROTECTED] [2008.04.29.0113 +0200]: Here is a sample of the sort of documentation that would satisfy this recommendation, written for a package that's using quilt: Might I suggest that for such cases, a common file explaining how to use quilt can be used or better yet: referred to? Full ACK. Why reading the (nice!) proposal I was indeed worrying about the duplication of information on how to use some common tools and, more worrisome, the fact that when the tool changes we will end up with inconsistent/incorrect information in a lot of packages. With the huge amount of packages we have we should factorize as much information as possible after all. Unrelated: I guess that we will then have to bug (nicely) quite a few source packages which are currently using debian/README.Debian-source, haven't we? Cheers. -- Stefano Zacchiroli -*- PhD in Computer Science ... now what? [EMAIL PROTECTED],cs.unibo.it,debian.org} -%- http://upsilon.cc/zack/ (15:56:48) Zack: e la demo dema ?/\All one has to do is hit the (15:57:15) Bac: no, la demo scema\/right keys at the right time signature.asc Description: Digital signature
Re: New README.source documentation for Debian packages
martin f krafft wrote: also sprach Russ Allbery [EMAIL PROTECTED] [2008.04.29.0113 +0200]: Here is a sample of the sort of documentation that would satisfy this recommendation, written for a package that's using quilt: Might I suggest that for such cases, a common file explaining how to use quilt can be used or better yet: referred to? Full ACK. I'd also like to see one for dpatch. Possibly something that can just be symlinked too. -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Re: New README.source documentation for Debian packages
Am Montag, den 28.04.2008, 16:13 -0700 schrieb Russ Allbery: After extensive discussion in Bug#250202 and elsewhere on how to handle the increasing variety of different build and patch systems in Debian, the consensus on the debian-policy list is to recommend adding a new documentation file, debian/README.source, to any Debian source package with a complex build system. The precise definition of complex is a package where one one cannot unpack the source package with dpkg-source -x and immediately get the source that would be built without running further commands or where additional steps must be taken to incorporate changes beyond just modifying files. [..] ---8--- This package uses quilt to manage all modifications to the upstream source. Changes are stored in the source package as diffs in debian/patches and applied during the build. To get the fully patched source after unpacking the source package, cd to the root level of the source package and run: quilt push -a [snip] This is some kind of stupid! You expect every package, that uses quilt or dpatch to ship the same quilt/dpatch documentation? Why doesn't a short howto shipped with _dpatch_ or _quilt_ doesn't fulfill the approach [1], that you need to ship the same documentation with hundreds or thousands of packages (I don't remember the exact count of packages using dpatch/quilt)? I'm sorry, but are you kidding me? Even the approach to create templates to let people just copy the file leads me to the same solution: Simply ship these file with dpatch or quilt (or the other systems) and not with the package sources. README.source should only contain things, you *cannot* expect from the tools used. I mean, I understand if you don't want to read long documentation just to understand, how a patch system works, that you normally don't use. But this problem can be easily solved by shipping the content you proposed for README.source with dpatch or quilt. *Only* if the build system differs, people should put additional comments into README.source. I could at least agree to force people to make a comment like [..] This package use (quilt|dpatch). ... ... read /usr/share/doc/(dpatch|quilt)/README.source [..]. or similar to this file *if* they use additional tools, so other maintainers don't need to waste time to find out, which systems are used. But to be honest, even this sentence is IMHO a waste of time, because maintainers should be able to figure this out within a minute if there is nothing unusual. I cannot agree to this proposal. It just increases the package sources by shipping the same text in several package sources for exactly no profit. You can make this whole thing much easier by filing 2 (or a few more) serious reports against dpatch and quilt (and other tools you consider) to ship these files and then we also don't need a mass-bug filing after Lenny. [1] If you want to work with quilt or dpatch, it must be installed, so also every documentation shipped with these packages is available. Regards, Daniel -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Re: New README.source documentation for Debian packages
also sprach Benjamin Seidenberg [EMAIL PROTECTED] [2008.04.29.1535 +0200]: Full ACK. I'd also like to see one for dpatch. Possibly something that can just be symlinked too. Not sure about just symlinking. I'd rather say it should be: To use this package, you need to install dpatch. Once installed, please see /usr/share/doc/dpatch/... -- .''`. martin f. krafft [EMAIL PROTECTED] : :' : proud Debian developer, author, administrator, and user `. `'` http://people.debian.org/~madduck - http://debiansystem.info `- Debian - when you have better things to do than fixing systems unix, because rebooting is for adding new hardware. digital_signature_gpg.asc Description: Digital signature (see http://martin-krafft.net/gpg/)
Re: New README.source documentation for Debian packages
Daniel Leidert [EMAIL PROTECTED] writes: This is some kind of stupid! You expect every package, that uses quilt or dpatch to ship the same quilt/dpatch documentation? You did read the part of the proposal saying: This explanation may refer to a documentation file installed by one of the package's build dependencies provided that the referenced documentation clearly explains these tasks and is not a general reference manual. When dpatch provides the standard explanation a dpatch using package could just point to this explanation. //Makholm -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Re: New README.source documentation for Debian packages
On Tuesday 29 April 2008 10:31, martin f krafft wrote: also sprach Benjamin Seidenberg [EMAIL PROTECTED] [2008.04.29.1535 +0200]: Full ACK. I'd also like to see one for dpatch. Possibly something that can just be symlinked too. Not sure about just symlinking. I'd rather say it should be: To use this package, you need to install dpatch. Once installed, please see /usr/share/doc/dpatch/... For common patch systems like dpatch or quilt, I guess I don't see what I learn from this that I can't already learn from a quick glance at the build-dep line in debian/control. For obscure/unique systems, I think it's sensible, but I didn't think this proposal was meant to address neophyte packagers, but people like the security team that are familiar with common/standard tools. Scott K -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Re: New README.source documentation for Debian packages
Am Dienstag, den 29.04.2008, 14:47 + schrieb Peter Makholm: Daniel Leidert [EMAIL PROTECTED] writes: This is some kind of stupid! You expect every package, that uses quilt or dpatch to ship the same quilt/dpatch documentation? You did read the part of the proposal saying: This explanation may refer to a documentation file installed by one of the package's build dependencies provided that the referenced documentation clearly explains these tasks and is not a general reference manual. When dpatch provides the standard explanation a dpatch using package could just point to this explanation. In this case I'm sorry. I really just read them very, very fast. Now being forced to read them slowly again I have to repeat: Sorry for my noise. It doesn't seem to be expected to ship the same howto with every package, which was what I complained about. Regards, Daniel -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Re: New README.source documentation for Debian packages
On Tue, 29 Apr 2008 16:31:30 +0200, martin f krafft [EMAIL PROTECTED] said: also sprach Benjamin Seidenberg [EMAIL PROTECTED] [2008.04.29.1535 +0200]: Full ACK. I'd also like to see one for dpatch. Possibly something that can just be symlinked too. Not sure about just symlinking. I'd rather say it should be: To use this package, you need to install dpatch. dpatch would be a build-dep, so that would be redundant. And if that isn't enough, most people should be bright enough to figure it out once you start telling them to look at /usr/share/doc/dpatch/... ;) Once installed, please see /usr/share/doc/dpatch/... Yes, I think it would be better to just have the README.source tell people to look at /usr/share/doc/dpatch/... This way, it's easy to add any additional information that you might want to have. -- Hubert Chathi [EMAIL PROTECTED] -- Jabber: [EMAIL PROTECTED] PGP/GnuPG key: 1024D/124B61FA http://www.uhoreg.ca/ Fingerprint: 96C5 012F 5F74 A5F7 1FF7 5291 AF29 C719 124B 61FA -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Re: New README.source documentation for Debian packages
martin f krafft [EMAIL PROTECTED] writes: also sprach Russ Allbery [EMAIL PROTECTED] [2008.04.29.0113 +0200]: Here is a sample of the sort of documentation that would satisfy this recommendation, written for a package that's using quilt: Might I suggest that for such cases, a common file explaining how to use quilt can be used or better yet: referred to? I'm guessing that you missed that this is exactly what the proposal allows for. You may want to read it again. :) -- Russ Allbery ([EMAIL PROTECTED]) http://www.eyrie.org/~eagle/ -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Re: New README.source documentation for Debian packages
Daniel Leidert [EMAIL PROTECTED] writes: *Only* if the build system differs, people should put additional comments into README.source. I could at least agree to force people to make a comment like [..] This package use (quilt|dpatch). ... ... read /usr/share/doc/(dpatch|quilt)/README.source [..]. or similar to this file *if* they use additional tools, so other maintainers don't need to waste time to find out, which systems are used. But to be honest, even this sentence is IMHO a waste of time, because maintainers should be able to figure this out within a minute if there is nothing unusual. The reason why the proposal calls for creating such a one-line file even for common patch systems such as quilt or dpatch is that people disagree about what constitutes common (what about dbs? yada?) and it's better to have a consistent rule that one can easily follow. It's also slightly faster to verify this way, not that the package is using quilt, but that it's using quilt in the completely standard way (I've seen some packages that use quilt but don't put the series file in debian/patches, for instance, or expect different quilt options than the ones most packages use). This makes all the possible variations explicit. -- Russ Allbery ([EMAIL PROTECTED]) http://www.eyrie.org/~eagle/ -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Re: New README.source documentation for Debian packages
also sprach Russ Allbery [EMAIL PROTECTED] [2008.04.29.1846 +0200]: I'm guessing that you missed that this is exactly what the proposal allows for. You may want to read it again. :) So it seems. The sample you quoted is surely misleading, in that case. I saw it and my redundancy detection mechanisms went haywire. -- .''`. martin f. krafft [EMAIL PROTECTED] : :' : proud Debian developer, author, administrator, and user `. `'` http://people.debian.org/~madduck - http://debiansystem.info `- Debian - when you have better things to do than fixing systems doesn't he know who i think i am? -- phil collins digital_signature_gpg.asc Description: Digital signature (see http://martin-krafft.net/gpg/)
Re: New README.source documentation for Debian packages
martin f krafft [EMAIL PROTECTED] writes: also sprach Russ Allbery [EMAIL PROTECTED] [2008.04.29.1846 +0200]: I'm guessing that you missed that this is exactly what the proposal allows for. You may want to read it again. :) So it seems. The sample you quoted is surely misleading, in that case. I saw it and my redundancy detection mechanisms went haywire. I should have explicitly noted in my message that I filed the included example as a wishlist bug against quilt to include in quilt itself. -- Russ Allbery ([EMAIL PROTECTED]) http://www.eyrie.org/~eagle/ -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Re: New README.source documentation for Debian packages
On Tue, Apr 29, 2008 at 11:15:08AM -0400, Scott Kitterman wrote: On Tuesday 29 April 2008 10:31, martin f krafft wrote: Not sure about just symlinking. I'd rather say it should be: To use this package, you need to install dpatch. Once installed, please see /usr/share/doc/dpatch/... For common patch systems like dpatch or quilt, I guess I don't see what I learn from this that I can't already learn from a quick glance at the build-dep line in debian/control. Using dpatch doesn't _guarantee_ the relevant debian/rules target is patch though. Hamish -- Hamish Moffatt VK3SB [EMAIL PROTECTED] [EMAIL PROTECTED] -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Re: New README.source documentation for Debian packages
Russ Allbery [EMAIL PROTECTED] writes: This new recommendation is *not* RC for lenny, only a recommendation. However, it is still a recommendation that most affected packages don't currently follow, so I wanted to give the development community a heads-up on this change. Can this be savely ignored when it is planed to switch over to the 3.0 (quilt) format as soon as it is allowed and thereby replacing the current patch system? MfG Goswin -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Re: New README.source documentation for Debian packages
Goswin von Brederlow [EMAIL PROTECTED] writes: Russ Allbery [EMAIL PROTECTED] writes: This new recommendation is *not* RC for lenny, only a recommendation. However, it is still a recommendation that most affected packages don't currently follow, so I wanted to give the development community a heads-up on this change. Can this be savely ignored when it is planed to switch over to the 3.0 (quilt) format as soon as it is allowed and thereby replacing the current patch system? Switching to the 3.0 (quilt) format will satisfy the requirement that one can simply run dpkg-source -x on the source package, make changes, and run dpkg-buildpackage, which means that, according to this new Policy, no additional documentation is required. So the short version is yes, unless the transition to that format is expected to take some time. If your package build system is particularly complicated, or if you have to do another upload for lenny anyway, it may be nice for the security team to include a README.source for the existing package layout for lenny, but this is certainly *not* required and we are not expecting maintainers to address this issue for lenny. Due largely to lack of manpower, Policy changes are a bit desynchronized from our release cycle right now. In order for this to really be something for lenny, the Policy update would have had to have been published about six months ago; now, it's really too late to expect lenny to be affected by this change. -- Russ Allbery ([EMAIL PROTECTED]) http://www.eyrie.org/~eagle/ -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Re: New README.source documentation for Debian packages
Russ Allbery [EMAIL PROTECTED] writes: Goswin von Brederlow [EMAIL PROTECTED] writes: Russ Allbery [EMAIL PROTECTED] writes: This new recommendation is *not* RC for lenny, only a recommendation. However, it is still a recommendation that most affected packages don't currently follow, so I wanted to give the development community a heads-up on this change. Can this be savely ignored when it is planed to switch over to the 3.0 (quilt) format as soon as it is allowed and thereby replacing the current patch system? Switching to the 3.0 (quilt) format will satisfy the requirement that one can simply run dpkg-source -x on the source package, make changes, and run dpkg-buildpackage, which means that, according to this new Policy, no additional documentation is required. So the short version is yes, unless the transition to that format is expected to take some time. If your package build system is particularly complicated, or if you have to do another upload for lenny anyway, it may be nice for the security team to include a README.source for the existing package layout for lenny, but this is certainly *not* required and we are not expecting maintainers to address this issue for lenny. Due largely to lack of manpower, Policy changes are a bit desynchronized from our release cycle right now. In order for this to really be something for lenny, the Policy update would have had to have been published about six months ago; now, it's really too late to expect lenny to be affected by this change. Ok, lets hope ftpmaster will allow 3.0 format soon after lenny then. Meanwhile I will stick with adding a README.source if I need an upload but not upload just to add it. MfG Goswin -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
