Bug#543417: README.source patch system documentation requirements considered harmful
Wouter Verhelst wrote: Anyone who hasn't seen this particular package yet, will be helped by a three-page README.source explaining how the source is laid out. Yes.. but at the cost of making README.source useless for the vastly more common case. We would all like better documentation of Debian development practices, but inserting boilerplate tutorials or single-line references inside source packages that are actually quite ordinary is damaging to the entire concept, as outlined my myself and others in this bug report. Please, counter this claim so we can move forward - this is what this bug is about, not whether developers would be helped by the documentation. I'm sure they would. Regards, -- ,''`. : :' : Chris Lamb `. `'` la...@debian.org `- signature.asc Description: PGP signature
Bug#543417: README.source patch system documentation requirements considered harmful
* Chris Lamb la...@debian.org [090908 02:02]: Such phrasing will result in README.source files saying This package uses quilt, as documented in /usr/share/doc/quilt/README.source Whilst I quite like the idea of allowing source documentation to be satisfied by build dependencies, a single-line README.source still has all the drawbacks I originally filed this bug about. That is to say, the existence of your README.source file would still be a false-positive when looking at the package with respect to whether it is esoteric in some way. Raphael Geissert also argues this in #73. I think having short README.source is better than having none. If there is a short one in normal cases, people can always look at it and see at one glance whether it is what they expect or if it needs special consideration. Some bonus point is that there is a proper transition path from the old way of not having such a file. Becaus if there is a short file that says nothing special here that is a defined state and you know someone added it. If there is no file you do not know if that means nothing special here, ignore debian/patches as it is preapplied in .diff.gz or nothing special here, standard quilt patching done at build time or this package may do something special but noone has yet looked at it. Hochachtungsvoll, Bernhard R. Link -- To UNSUBSCRIBE, email to debian-policy-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#543417: README.source patch system documentation requirements considered harmful
On Tue, 08 Sep 2009, Bernhard R. Link wrote: I think having short README.source is better than having none. If there is a short one in normal cases, people can always look at it and see at one glance whether it is what they expect or if it needs special consideration. My main concern is maintainer time spent adding and maintaining the file in many packages outstripping time saved by (as-of-yet) non-maintainers. A secondary concern is reader fatigue, where the file doesn't document anything that someone would normally already be aware of, so people ignore it in general. If we had a generic set of packaging types that we could agree didn't need to be documented in README.source (perhaps in devref, with pointers to the actual documentation?), the README.source could be reserved for things which actually were unusual, and would obviate most of the concerns raised. Don Armstrong -- THERE IS NO GRAVITY THE WORLD SUCKS -- Vietnam War Penquin Lighter http://gallery.donarmstrong.com/clippings/vietnam_there_is_no_gravity.jpg http://www.donarmstrong.com http://rzlab.ucr.edu -- To UNSUBSCRIBE, email to debian-policy-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#543417: README.source patch system documentation requirements considered harmful
Don Armstrong d...@debian.org writes: If we had a generic set of packaging types that we could agree didn't need to be documented in README.source (perhaps in devref, with pointers to the actual documentation?), the README.source could be reserved for things which actually were unusual, and would obviate most of the concerns raised. Yeah, that's where I'm coming from as well. After now having some experience with this policy, it's not feeling particularly useful to have people copy over some boilerplate if they're using quilt or dpatch in the normal and expected way. -- Russ Allbery (r...@debian.org) http://www.eyrie.org/~eagle/ -- To UNSUBSCRIBE, email to debian-policy-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#543417: README.source patch system documentation requirements considered harmful
On Tue, 08 Sep 2009 10:31:34 -0700, Russ Allbery wrote: If we had a generic set of packaging types that we could agree didn't need to be documented in README.source (perhaps in devref, with pointers to the actual documentation?), the README.source could be reserved for things which actually were unusual, and would obviate most of the concerns raised. Yeah, that's where I'm coming from as well. After now having some experience with this policy, it's not feeling particularly useful to have people copy over some boilerplate if they're using quilt or dpatch in the normal and expected way. Count me in; these boilerplate README.source copies are tiresome for me, both for writi^Wcopying and reading (or ignoring). I also share the concern that they actually devaluate the files that contain real information (as opposed to pointing to well-known or easy-to-find docs). Cheers, gregor -- .''`. http://info.comodo.priv.at/ -- GPG Key IDs: 0x00F3CFE4, 0x8649AA06 : :' : Debian GNU/Linux user, admin, developer - http://www.debian.org/ `. `' Member of VIBE!AT, SPI Inc., fellow of FSFE | http://got.to/quote/ `-BOFH excuse #96: Vendor no longer supports the product signature.asc Description: Digital signature
Bug#543417: README.source patch system documentation requirements considered harmful
On Tue, Sep 08, 2009 at 12:48:25AM +0100, Chris Lamb wrote: Wouter Verhelst wrote: I would instead suggest changing the next paragraph to something like the following: ``In case a package uses a build system for which documentation sufficient to satisfy this requirement exists in a file installed by one of the package's build dependencies, this file should be referred to from the README.source file, rather than copied into it.'' [..] Such phrasing will result in README.source files saying This package uses quilt, as documented in /usr/share/doc/quilt/README.source Whilst I quite like the idea of allowing source documentation to be satisfied by build dependencies, a single-line README.source still has all the drawbacks I originally filed this bug about. That is to say, the existence of your README.source file would still be a false-positive when looking at the package with respect to whether it is esoteric in some way. Raphael Geissert also argues this in #73. But would such a pointer be valuable enough to mitigate these concerns? For a newbie, the answer might very well be yes. However, this seems like a weak and relatively rare case to optimise for, compounded by the high cost of excessive false-positives. It is valuable, because there are various way to use dpatch, quilt etc. in packaging, some of them let the source ready after unpacking, some of them not. A statement the package is following a specific interface is far reliable than just assuming that a build-dependency imply an interface which is not true. Cheers, -- Bill. ballo...@debian.org Imagine a large red swirl here. -- To UNSUBSCRIBE, email to debian-policy-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#543417: README.source patch system documentation requirements considered harmful
Wouter Verhelst wrote: I would instead suggest changing the next paragraph to something like the following: ``In case a package uses a build system for which documentation sufficient to satisfy this requirement exists in a file installed by one of the package's build dependencies, this file should be referred to from the README.source file, rather than copied into it.'' [..] Such phrasing will result in README.source files saying This package uses quilt, as documented in /usr/share/doc/quilt/README.source Whilst I quite like the idea of allowing source documentation to be satisfied by build dependencies, a single-line README.source still has all the drawbacks I originally filed this bug about. That is to say, the existence of your README.source file would still be a false-positive when looking at the package with respect to whether it is esoteric in some way. Raphael Geissert also argues this in #73. But would such a pointer be valuable enough to mitigate these concerns? For a newbie, the answer might very well be yes. However, this seems like a weak and relatively rare case to optimise for, compounded by the high cost of excessive false-positives. Regards, -- ,''`. : :' : Chris Lamb `. `'` la...@debian.org `- signature.asc Description: PGP signature
Bug#543417: README.source patch system documentation requirements considered harmful
Bill Allombert wrote: 1) We should move to new source package format (3.0 etc) that remove the need for patch system altogether. Oh, yes please. But, as I currently understand it, existing packages will not magically start using this format, and thus we are likely to find ourselves growing a large number of these distracting files, even beyond 100% coverage of the 3.0 formats. Besides, it might also help to clarify the situation for old-style packages using patch systems, simply as a means of better defining positive uses of README.source to move forward with. As two concrete examples, a maintainer using the quilt 3.0 format may still include a README.source that directs the reader towards the presence of patches and other miscellania. In addition, I have seen README.source files that give crash courses on how to use pbuilder in a generic fashion. I would consider this to be rather inappropriate, regardless of the package format. 3) If a package is lacking debian/README.source, then one should expect that the source is ready to be used. If it not the case, even an empty debian/README.source is better than none. I believe our disagreement here is that I feel curbing the proliferation of distracting README.source files is more important than maintaining a no README.source = package is ready invariant. However, this invariant doesn't seem particularly useful as we still have to rely on heuristics to prepare a package (whatever that means). As an illustration of its current deficiencies, a static analysis tool running across the archive still has to guess whether to apply patches, extract embedded-tarballs and such forth - the presence or lack of a README.source by your specification is not helpful. You can replace static analysis tool with NMUer/porter without major issue here too. Regards, -- ,''`. : :' : Chris Lamb `. `'` la...@debian.org `- signature.asc Description: PGP signature
Bug#543417: README.source patch system documentation requirements considered harmful
On Tue, 25 Aug 2009, Cyril Brulebois wrote: Raphael Hertzog hert...@debian.org (25/08/2009): That's my point. Without README.source (assuming the rules are changed to not force the creation of that file for common patch systems), seeing debian/patches/ is not enough to know if the patches are already applied or not. Fortunately, dpkg-source is there for that: | $ LC_ALL=C dpkg-source -x ../python-networkx_0.99-2.dsc | dpkg-source: warning: extracting unsigned source package (../python-networkx_0.99-2.dsc) | dpkg-source: info: extracting python-networkx in python-networkx-0.99 | dpkg-source: info: unpacking python-networkx_0.99.orig.tar.gz | dpkg-source: info: unpacking python-networkx_0.99-2.debian.tar.gz | dpkg-source: info: applying all patches with quilt push -a -q | Applying patch 10_doc_relocation | Now at patch 10_doc_relocation Indeed, so we can know safely ignore Bill's concern AFAIK (provided that I have correctly understood what he meant). Cheers, -- Raphaël Hertzog -- To UNSUBSCRIBE, email to debian-policy-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#543417: README.source patch system documentation requirements considered harmful
On Mon, Aug 24, 2009 at 10:33:14PM +0100, Chris Lamb wrote: Package: debian-policy Version: 3.8.3.0 Hi Policy hackers. I feel there is a problem with §4.14 (Source package handling: debian/README.source) that is a little harmful at present. Basically, I feel that assuming that all packages that use a patch system require a README.source is damaging the concept of README.source - as the archive grows more boilerplate descriptions on how to invoke quilt et al, I fear maintainers will simply not bother to consult this file when examining a package. I've been walking over README.source files a while ago, and given the proliferation of just copies of /usr/share/doc/quilt/README.source (et al), I understand your concerns and share them. I was actually planning to come up with some proposal or other once I'd finished looking at the README.source files, but whatever :-) This is particularly unfortunate as, not only can the file be extremely useful, I fear it will fuel a cycle of maintainers not updating the file with information as it does not get read anymore. Besides, the concept of boilerplate is hardly anthemic in Debian. If the motivation behind README.source is to highlight non-trivial packaging, then many packages can be presented that are trivial dispite using a patch system. My own conclusion is that the adoption of dpatch or quilt is so common that the skills for it may be assumed. To get things rolling, I propose that we temper: | This explanation should include specific commands and mention any | additional required Debian packages. It should not assume familiarity | with any specific Debian packaging system or patch management tools. ... with something subjective like any non-standard Debian packaging system. This would still ask maintainers to document the parts of their packages that would be unfamiliar to most developers, whilst avoiding maintainers including essays on how to invoke pbuilder and other nonsense. Whilst using a subjective like this isn't desirable, it does avoid having to enumerate specific programs that are exempt from explanation, which doesn't really smell right for the Policy. Precicely because you're doing subjective things here, I'm not convinced that using this wording is a good plan. Thoughts? I would instead suggest changing the next paragraph to something like the following: ``In case a package uses a build system for which documentation sufficient to satisfy this requirement exists in a file installed by one of the package's build dependencies, this file should be referred to from the README.source file, rather than copied into it.'' currently, this paragraph says: 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. Such phrasing will result in README.source files saying This package uses quilt, as documented in /usr/share/doc/quilt/README.source which can be safely ignored if the person doing the NMU is already familiar with quilt. However, if the package's README.source says This package uses quilt, mostly as documented in /usr/share/doc/quilt/README.source except that we do foo in place of bar Then this will easily trigger alarm bells to anyone doing an NMU that something out of the ordinary is happening here, and that they need to look out for that. -- The biometric identification system at the gates of the CIA headquarters works because there's a guard with a large gun making sure no one is trying to fool the system. http://www.schneier.com/blog/archives/2009/01/biometrics.html signature.asc Description: Digital signature
Bug#543417: README.source patch system documentation requirements considered harmful
Raphael Geissert geiss...@debian.org writes: Bill Allombert wrote: 3) If a package is lacking debian/README.source, then one should expect that the source is ready to be used. If it not the case, even an empty debian/README.source is better than none. What would an empty README.source file mean? Cheers, There is something special about the source. It is not just a plain 1.0, 3.0 or 3.0 (quilt) source where you can just edit files at will. But since I'm too lazy to document what is different you need to dig into the rules file to understand what is going on. (not my proposal but my understanding of it) MfG Goswin -- To UNSUBSCRIBE, email to debian-policy-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#543417: README.source patch system documentation requirements considered harmful
On Mon, 24 Aug 2009, Russ Allbery wrote: I'm increasingly inclined to agree with this, but I'd like to specifically spell out what the exceptions are. I think the important exception would be that packages that use quilt or dpatch in the default mode, applying all patches in debian/patches/series debian/patches/00list before the build and removing them on clean, aren't required to have a README.source. That should get most of the cases where this is simple boilerplate, while still preserving the requirement for uses of quilt or dpatch in a non-standard way. Ack. I was not really complaining of the README.source requirement for my own packages since their quilt usage meant that once 3.0 (quilt) is accepted, I can simply drop that file at that point. And given that planned move I wonder if only quilt should get the exception (that would make one more incentive to standardize on a single patch system). I don't know if we should include CDBS's basic patch system as well. While easy to understand and use, we should aim at standardization so I prefer not listing more but rather less. Cheers, -- Raphaël Hertzog -- To UNSUBSCRIBE, email to debian-policy-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#543417: README.source patch system documentation requirements considered harmful
Russ Allbery wrote: I don't know if we should include CDBS's basic patch system as well. If you create a list of what doesn't need a README.source, sure. Emilio signature.asc Description: OpenPGP digital signature
Bug#543417: README.source patch system documentation requirements considered harmful
Bill Allombert bill.allomb...@math.u-bordeaux1.fr (25/08/2009):
1) We should move to new source package format (3.0 etc) that remove
the need for patch system altogether.
1) That's not ready yet.
2) Documentation for debian/README.source for dpatch and quilt is
useful, and it can be simply supplied in
/usr/share/doc/{dpatch,quilt}. Then debian/README.source only need
to say that we use dpatch as documented in
/usr/share/doc/dpatch/README.source.gz.
2) That's what we're talking about.
3) If a package is lacking debian/README.source, then one should
expect that the source is ready to be used. If it not the case, even
an empty debian/README.source is better than none.
3) That's called noise.
Mraw,
KiBi.
signature.asc
Description: Digital signature
Bug#543417: README.source patch system documentation requirements considered harmful
On Tue, 25 Aug 2009, Cyril Brulebois wrote: Bill Allombert bill.allomb...@math.u-bordeaux1.fr (25/08/2009): 1) We should move to new source package format (3.0 etc) that remove the need for patch system altogether. 1) That's not ready yet. That's not true. It's not deployed on ftp-master but all the code needed exists. But I can't do much more to convince ftpmasters to apply the patch... I already offered to do all the work that merging my patch would create them. 3) If a package is lacking debian/README.source, then one should expect that the source is ready to be used. If it not the case, even an empty debian/README.source is better than none. 3) That's called noise. I can certainly understand the point of view of Bill. It's not noise if you assume that you should not need to do anything before being able to work on the package... and if you do, you should find the required hint in README.source. The existence of the file (even if empty) proves that the package uses some patch system and that he should investigate a bit more. That said, checking the build dependencies or debian/rules is quite quick and gives you the same information in most cases when the package uses common patch systems in a usual ways. Cheers, -- Raphaël Hertzog -- To UNSUBSCRIBE, email to debian-policy-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#543417: README.source patch system documentation requirements considered harmful
On Tue, 25 Aug 2009, Cyril Brulebois wrote: I can certainly understand the point of view of Bill. It's not noise if you assume that you should not need to do anything before being able to work on the package... and if you do, you should find the required hint in README.source. The existence of the file (even if empty) proves that the package uses some patch system and that he should investigate a bit more. The existence of a debian/patches directory proves that the package uses some patch system and that he should investigate more. But this assertion is not true once new source packages are “ready”. :) Some forward-looking can't hurt when we design policy. Cheers, -- Raphaël Hertzog -- To UNSUBSCRIBE, email to debian-policy-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#543417: README.source patch system documentation requirements considered harmful
Raphael Hertzog hert...@debian.org (25/08/2009): The existence of a debian/patches directory proves that the package uses some patch system and that he should investigate more. But this assertion is not true once new source packages are “ready”. :) Some forward-looking can't hurt when we design policy. And fortunately, Chris's concern will go away when that's the case, since AFAICT the patches are going to be applied (according to my reading of dpkg-source(1)), and there will be no reason to be bothered with README.source at all. Thanks for playing, though. Mraw, KiBi. signature.asc Description: Digital signature
Bug#543417: README.source patch system documentation requirements considered harmful
Bill Allombert wrote:
1) We should move to new source package format (3.0 etc) that remove the
need for patch system altogether.
Ehem, it actually uses the patch system, difference is that it is no longer
under the control of the rules file.
2) Documentation for debian/README.source for dpatch and quilt is useful,
and it can be simply supplied in /usr/share/doc/{dpatch,quilt}. Then
debian/README.source only need to say that we use dpatch as documented
in /usr/share/doc/dpatch/README.source.gz.
-1, a README.source pointing to dpatch's README.source is useless and is a
waste of time for the maintainer, the sponsor (in case the maintainer needs
one), and the NMUer or anyone else who takes a look at the source package.
If it is as simple as pointing to the patch system's README.source any
competent person should be able to take a look at /usr/share/doc/patch
sys/ if she or he doesn't already know how it works.
3) If a package is lacking debian/README.source, then one should expect
that the source is ready to be used. If it not the case, even an empty
debian/README.source is better than none.
What would an empty README.source file mean?
Cheers,
--
Raphael Geissert - Debian Developer
www.debian.org - get.debian.net
--
To UNSUBSCRIBE, email to debian-policy-requ...@lists.debian.org
with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#543417: README.source patch system documentation requirements considered harmful
On Tue, 25 Aug 2009, Cyril Brulebois wrote: Raphael Hertzog hert...@debian.org (25/08/2009): The existence of a debian/patches directory proves that the package uses some patch system and that he should investigate more. But this assertion is not true once new source packages are “ready”. :) Some forward-looking can't hurt when we design policy. And fortunately, Chris's concern will go away when that's the case, since AFAICT the patches are going to be applied (according to my reading of dpkg-source(1)), and there will be no reason to be bothered with README.source at all. That's my point. Without README.source (assuming the rules are changed to not force the creation of that file for common patch systems), seeing debian/patches/ is not enough to know if the patches are already applied or not. With the current rule in policy, only 3.0 (quilt) source package would not have a README.source and the lack of README.source fact can be used to decide that no further investigation is required. Thanks for playing, though. Thanks for trying to understand other's people point of view. :) That said, I don't care much about this specific argument but I like to highlight the fact that you should try to understand the point of view of the other proponents if you ever want to reach some (other) decision that satisfies everybody. Cheers, -- Raphaël Hertzog -- To UNSUBSCRIBE, email to debian-policy-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#543417: README.source patch system documentation requirements considered harmful
Raphael Hertzog hert...@debian.org (25/08/2009): The existence of a debian/patches directory proves that the package uses some patch system and that he should investigate more. But this assertion is not true once new source packages are “ready”. :) Some forward-looking can't hurt when we design policy. Oh, and I failed to catch that, which was too obvious: I said that debian/patches is a signal of possible patch(es| system) and that one should investigate. So your asserting my assertion is not true once new source packages are ready is false. And fortunately, Chris's concern will go away when that's the case, since AFAICT the patches are going to be applied (according to my reading of dpkg-source(1)), and there will be no reason to be bothered with README.source at all. Sorry, sure, I should have mentioned “for the 3.0 (quilt) source packages”. And old source packages still will contain debian/patches, and people might still understand from that directory that patches may exist. That's my point. Without README.source (assuming the rules are changed to not force the creation of that file for common patch systems), seeing debian/patches/ is not enough to know if the patches are already applied or not. Fortunately, dpkg-source is there for that: | $ LC_ALL=C dpkg-source -x ../python-networkx_0.99-2.dsc | dpkg-source: warning: extracting unsigned source package (../python-networkx_0.99-2.dsc) | dpkg-source: info: extracting python-networkx in python-networkx-0.99 | dpkg-source: info: unpacking python-networkx_0.99.orig.tar.gz | dpkg-source: info: unpacking python-networkx_0.99-2.debian.tar.gz | dpkg-source: info: applying all patches with quilt push -a -q | Applying patch 10_doc_relocation | Now at patch 10_doc_relocation With the current rule in policy, only 3.0 (quilt) source package would not have a README.source and the lack of README.source fact can be used to decide that no further investigation is required. No. *Suggesting* to have a README.source when a patch system is used doesn't mean that you can infer that no patch system is used if there's no README.source. On the contrary, having a debian/patches directory is a fairly good indicator that there are patches. Whether they automatically got applied when unpacking can be seen when… unpacking, see above. Thanks for playing, though. Thanks for trying to understand other's people point of view. :) No problem. That said, I don't care much about this specific argument but I like to highlight the fact that you should try to understand the point of view of the other proponents if you ever want to reach some (other) decision that satisfies everybody. I might have troubles trying to follow your logical mistakes. Sorry for that. Mraw, KiBi. signature.asc Description: Digital signature
Bug#543417: README.source patch system documentation requirements considered harmful
Package: debian-policy Version: 3.8.3.0 Hi Policy hackers. I feel there is a problem with §4.14 (Source package handling: debian/README.source) that is a little harmful at present. Basically, I feel that assuming that all packages that use a patch system require a README.source is damaging the concept of README.source - as the archive grows more boilerplate descriptions on how to invoke quilt et al, I fear maintainers will simply not bother to consult this file when examining a package. This is particularly unfortunate as, not only can the file be extremely useful, I fear it will fuel a cycle of maintainers not updating the file with information as it does not get read anymore. Besides, the concept of boilerplate is hardly anthemic in Debian. If the motivation behind README.source is to highlight non-trivial packaging, then many packages can be presented that are trivial dispite using a patch system. My own conclusion is that the adoption of dpatch or quilt is so common that the skills for it may be assumed. To get things rolling, I propose that we temper: | This explanation should include specific commands and mention any | additional required Debian packages. It should not assume familiarity | with any specific Debian packaging system or patch management tools. .. with something subjective like any non-standard Debian packaging system. This would still ask maintainers to document the parts of their packages that would be unfamiliar to most developers, whilst avoiding maintainers including essays on how to invoke pbuilder and other nonsense. Whilst using a subjective like this isn't desirable, it does avoid having to enumerate specific programs that are exempt from explanation, which doesn't really smell right for the Policy. Thoughts? Regards, -- ,''`. : :' : Chris Lamb `. `'` la...@debian.org `- signature.asc Description: PGP signature
Bug#543417: README.source patch system documentation requirements considered harmful
Chris Lamb wrote: Package: debian-policy Version: 3.8.3.0 Hi Policy hackers. I feel there is a problem with §4.14 (Source package handling: debian/README.source) that is a little harmful at present. Basically, I feel that assuming that all packages that use a patch system require a README.source is damaging the concept of README.source - as the archive grows more boilerplate descriptions on how to invoke quilt et al, I fear maintainers will simply not bother to consult this file when examining a package. Full ack. I've so far ignored it (unless forced by my sponsor) since it's just a recommendation, because I think a package that simply uses one of the common patch systems doesn't need any explanation in README.source. Cheers, Emilio signature.asc Description: OpenPGP digital signature
Bug#543417: README.source patch system documentation requirements considered harmful
Emilio Pozuelo Monfort poch...@gmail.com (24/08/2009): Basically, I feel that assuming that all packages that use a patch system require a README.source is damaging the concept of README.source - as the archive grows more boilerplate descriptions on how to invoke quilt et al, I fear maintainers will simply not bother to consult this file when examining a package. Full ack. I've so far ignored it (unless forced by my sponsor) since it's just a recommendation, because I think a package that simply uses one of the common patch systems doesn't need any explanation in README.source. Seconded. Mraw, KiBi. signature.asc Description: Digital signature
Bug#543417: README.source patch system documentation requirements considered harmful
Chris Lamb la...@debian.org writes: If the motivation behind README.source is to highlight non-trivial packaging, then many packages can be presented that are trivial dispite using a patch system. My own conclusion is that the adoption of dpatch or quilt is so common that the skills for it may be assumed. To get things rolling, I propose that we temper: | This explanation should include specific commands and mention any | additional required Debian packages. It should not assume familiarity | with any specific Debian packaging system or patch management tools. .. with something subjective like any non-standard Debian packaging system. This would still ask maintainers to document the parts of their packages that would be unfamiliar to most developers, whilst avoiding maintainers including essays on how to invoke pbuilder and other nonsense. Whilst using a subjective like this isn't desirable, it does avoid having to enumerate specific programs that are exempt from explanation, which doesn't really smell right for the Policy. I'm increasingly inclined to agree with this, but I'd like to specifically spell out what the exceptions are. I think the important exception would be that packages that use quilt or dpatch in the default mode, applying all patches in debian/patches/series debian/patches/00list before the build and removing them on clean, aren't required to have a README.source. That should get most of the cases where this is simple boilerplate, while still preserving the requirement for uses of quilt or dpatch in a non-standard way. The implication is that people will have to know how quilt and dpatch work, but anything else has to be explained. I think anyone doing substantial Debian work has probably encountered quilt and dpatch at some point anyway and is at least vaguely familiar, so I think that preserves the original goal. I don't know if we should include CDBS's basic patch system as well. -- Russ Allbery (r...@debian.org) http://www.eyrie.org/~eagle/ -- To UNSUBSCRIBE, email to debian-policy-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#543417: README.source patch system documentation requirements considered harmful
On Mon, 2009-08-24 at 15:46 -0700, Russ Allbery wrote: Chris Lamb la...@debian.org writes: If the motivation behind README.source is to highlight non-trivial packaging, then many packages can be presented that are trivial dispite using a patch system. My own conclusion is that the adoption of dpatch or quilt is so common that the skills for it may be assumed. To get things rolling, I propose that we temper: | This explanation should include specific commands and mention any | additional required Debian packages. It should not assume familiarity | with any specific Debian packaging system or patch management tools. .. with something subjective like any non-standard Debian packaging system. This would still ask maintainers to document the parts of their packages that would be unfamiliar to most developers, whilst avoiding maintainers including essays on how to invoke pbuilder and other nonsense. Whilst using a subjective like this isn't desirable, it does avoid having to enumerate specific programs that are exempt from explanation, which doesn't really smell right for the Policy. I'm increasingly inclined to agree with this, but I'd like to specifically spell out what the exceptions are. I think the important exception would be that packages that use quilt or dpatch in the default mode, applying all patches in debian/patches/series debian/patches/00list before the build and removing them on clean, aren't required to have a README.source. That should get most of the cases where this is simple boilerplate, while still preserving the requirement for uses of quilt or dpatch in a non-standard way. The implication is that people will have to know how quilt and dpatch work, but anything else has to be explained. I think anyone doing substantial Debian work has probably encountered quilt and dpatch at some point anyway and is at least vaguely familiar, so I think that preserves the original goal. I don't know if we should include CDBS's basic patch system as well. I'm inclined to agree with Lamby also. Although specifying a worthwhile list of exceptions does seem likely to become a slippery slope. Should we also be excluding packaging done through VCS branches from this requirement, for example? Regards, Andrew. http://andrew.mcmillan.net.nz/ Porirua, New Zealand Twitter: _karora Phone: +64(272)DEBIAN You have an ability to sense and know higher truth. signature.asc Description: This is a digitally signed message part
Bug#543417: README.source patch system documentation requirements considered harmful
Hi,
Chris Lamb wrote:
Basically, I feel that assuming that all packages that use a patch system
require a README.source is damaging the concept of README.source
Seconded.
On Monday 24 August 2009 17:46:25 Russ Allbery wrote:
[...]
I'm increasingly inclined to agree with this, but I'd like to specifically
spell out what the exceptions are. I think the important exception would
be that packages that use quilt or dpatch in the default mode, applying
all patches in debian/patches/series debian/patches/00list before the
build and removing them on clean, aren't required to have a README.source.
Some exceptions are indeed required, but like Andrew already said it should be
done with care. Some wording more generic than just standard quilt and
dpatch using lists of patches. I think everyone is used to dpatch and quilt
with lists of patches in debian/patches/{series,00list} and cdbs' simple
patch system, but anything else like dpatch with a lists of patches hardcoded
in the rules file should at least point that out.
I've seen one package using dpatch which was NMUed twice by two different
people whose patches never got applied because they didn't add them to the
patches list hardcoded in the rules file.
Cheers,
--
Raphael Geissert - Debian Developer
www.debian.org - get.debian.net
--
To UNSUBSCRIBE, email to debian-policy-requ...@lists.debian.org
with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#543417: README.source patch system documentation requirements considered harmful
Raphael Geissert geiss...@debian.org writes:
Some exceptions are indeed required, but like Andrew already said it
should be done with care. Some wording more generic than just standard
quilt and dpatch using lists of patches. I think everyone is used to
dpatch and quilt with lists of patches in debian/patches/{series,00list}
and cdbs' simple patch system, but anything else like dpatch with a
lists of patches hardcoded in the rules file should at least point that
out. I've seen one package using dpatch which was NMUed twice by two
different people whose patches never got applied because they didn't add
them to the patches list hardcoded in the rules file.
Yeah, exactly. I want to make sure that something like that is still
documented, and I'd like to see any new patch helper be documented until
it's achieved enough archive usage that the security and release teams are
already familiar with it and see it all the time, which I think is true of
both quilt and dpatch.
I do think the specific *tools* quilt and dpatch (and maybe CDBS
simple-patchsys) are what should get the exception, not just the general
process that they use, since the point of the documentation is to make
sure people know how to use the specific tools required.
--
Russ Allbery (r...@debian.org) http://www.eyrie.org/~eagle/
--
To UNSUBSCRIBE, email to debian-policy-requ...@lists.debian.org
with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
