Bug#495233: debian-policy: README.source content should be more detailed
Le Fri, Aug 15, 2008 at 11:22:51AM -0300, Lucas Nussbaum a écrit : First, section 4.14 should list things that one does not need to describe in debian/README.source. For example, the use of one of the standard patch systems (quilt, dpatch, simple-patchsys) doesn't need to be documented, since every NMUer should be able to work with them. … Also, it would be interesting to extend the use of debian/README.source to other areas, such as: - whether the maintainer encourages commits for other people directly to the package's VCS. - the branch layout in the package's VCS. Dear all, more than three years later, the 3.0 (quilt) source format has eroded the use of patch systems. The use of debian/README.source to document them has also been questionned in http://bugs.debian.org/543417, but the less frequent they become, the more the documentation becomes relevant. Despite the following notion is still controversial, I think that little by little, when packages are managed in a VCS, the preferred form for modification is not the source package downloaded from our archive, but the VCS clone or checkout itself. I would therefore like to propose, in line with the original suggestion of Lucas, to add a paragraph to §4.14 so that it explicitely mentions the documentation of the VCS where the source package is developed. This could be something like the following. When the source package is developped with a version control system and its repository is publicly available, README.source may document information not available elsewhere such as whether the maintainer encourages commits, if the branch layout is not usual. With my experience limited to make standard packages in a team, I have no other addition or change to suggest for §4.14. Have a nice day, -- Charles Plessy Tsurumi, Kanagawa, Japan -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Bug#495233: debian-policy: README.source content should be more detailed
On Fri, Aug 15, 2008 at 03:17:44PM -0300, Lucas Nussbaum wrote: On 15/08/08 at 11:01 -0700, Russ Allbery wrote: Giacomo Catenazzi [EMAIL PROTECTED] writes: Lucas Nussbaum wrote: First, section 4.14 should list things that one does not need to describe in debian/README.source. For example, the use of one of the standard patch systems (quilt, dpatch, simple-patchsys) doesn't need to be documented, since every NMUer should be able to work with them. I don't agree. This was one of the things that came up specifically in the original discussion that led to the README.source compromise. If nothing else, README.source tells people that yes, this is bog-standard quilt or dpatch, so they don't have to figure out which it is and they don't have to wonder whether there's something weird at work. I would like this file to continue to contain pointers to the standard documentation for quilt or dpatch if those patch systems are used. We allowed for a pointer specifically so that all you have to do is include a line or two of reference. For example, I use: | 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. Please see: | | /usr/share/doc/quilt/README.source | | for more information on how to apply the patches, modify patches, or | remove a patch. quilt and dpatch could probably usefully recommend boilerplate text. Another example is build systems: cdbs is used by 20% of our packages, so I don't think that one need to document its use. I think the better way is do it similar to copyright: for common patch/build system we should include only a link to the relative document. Maybe on a common package (build essential or dpkg-dev) or on patch system package (but in this case we should push stronger the maintainer to include the relevant informations). Which is what Policy already says, and quilt, for example, provides such a document for README.source to link to. So I don't think Policy should be changed here. But that won't work if we want to include more info in README.source. What about moving to a machine-parseable format, such as: Patch-system: quilt Patch-system-doc: /usr/share/doc/quilt/README.source This does about the same as grepping the build-dep for quilt. Cheers, -- Bill. [EMAIL PROTECTED] Imagine a large red swirl here. -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Bug#495233: debian-policy: README.source content should be more detailed
On 19/08/08 at 17:19 +0200, Bill Allombert wrote: On Fri, Aug 15, 2008 at 03:17:44PM -0300, Lucas Nussbaum wrote: On 15/08/08 at 11:01 -0700, Russ Allbery wrote: Giacomo Catenazzi [EMAIL PROTECTED] writes: Lucas Nussbaum wrote: First, section 4.14 should list things that one does not need to describe in debian/README.source. For example, the use of one of the standard patch systems (quilt, dpatch, simple-patchsys) doesn't need to be documented, since every NMUer should be able to work with them. I don't agree. This was one of the things that came up specifically in the original discussion that led to the README.source compromise. If nothing else, README.source tells people that yes, this is bog-standard quilt or dpatch, so they don't have to figure out which it is and they don't have to wonder whether there's something weird at work. I would like this file to continue to contain pointers to the standard documentation for quilt or dpatch if those patch systems are used. We allowed for a pointer specifically so that all you have to do is include a line or two of reference. For example, I use: | 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. Please see: | | /usr/share/doc/quilt/README.source | | for more information on how to apply the patches, modify patches, or | remove a patch. quilt and dpatch could probably usefully recommend boilerplate text. Another example is build systems: cdbs is used by 20% of our packages, so I don't think that one need to document its use. I think the better way is do it similar to copyright: for common patch/build system we should include only a link to the relative document. Maybe on a common package (build essential or dpkg-dev) or on patch system package (but in this case we should push stronger the maintainer to include the relevant informations). Which is what Policy already says, and quilt, for example, provides such a document for README.source to link to. So I don't think Policy should be changed here. But that won't work if we want to include more info in README.source. What about moving to a machine-parseable format, such as: Patch-system: quilt Patch-system-doc: /usr/share/doc/quilt/README.source This does about the same as grepping the build-dep for quilt. No, a build-dependency such as gnome-pkg-tools or ruby-pkg-tools could depend on quilt itself. For example, ruby-pkg-tools depends on cdbs, so each package doesn't depend on cdbs directly. -- | Lucas Nussbaum | [EMAIL PROTECTED] http://www.lucas-nussbaum.net/ | | jabber: [EMAIL PROTECTED] GPG: 1024D/023B3F4F | -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Bug#495233: debian-policy: README.source content should be more detailed
On 15/08/08 at 16:35 -0700, Russ Allbery wrote: Lucas Nussbaum [EMAIL PROTECTED] writes: On 15/08/08 at 11:01 -0700, Russ Allbery wrote: Giacomo Catenazzi [EMAIL PROTECTED] writes: I think the better way is do it similar to copyright: for common patch/build system we should include only a link to the relative document. Maybe on a common package (build essential or dpkg-dev) or on patch system package (but in this case we should push stronger the maintainer to include the relevant informations). Which is what Policy already says, and quilt, for example, provides such a document for README.source to link to. So I don't think Policy should be changed here. But that won't work if we want to include more info in README.source. Why not? I would think you could include whatever information you want before or after the pointer to the standard quilt documentation. I thought you meant link as in symlink. What about moving to a machine-parseable format, such as: Patch-system: quilt Patch-system-doc: /usr/share/doc/quilt/README.source I think that's kind of pointless for human-readable, human-targetted documention. Why would machines need to parse README.source? Actually, I find it easier to read that than a 4-5 lines blurb that contains exactly the same information. Regarding programs parsing it, For example, apt-get source could display a message about the patch system in use. Or debcheckout could make use of the branch layout somehow. -- | Lucas Nussbaum | [EMAIL PROTECTED] http://www.lucas-nussbaum.net/ | | jabber: [EMAIL PROTECTED] GPG: 1024D/023B3F4F | -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Bug#495233: debian-policy: README.source content should be more detailed
Package: debian-policy Version: 3.8.0.1 Hi, I really like the idea of documenting special things about a source package in debian/README.source. However, I think that section 4.14 could be improved a lot. First, section 4.14 should list things that one does not need to describe in debian/README.source. For example, the use of one of the standard patch systems (quilt, dpatch, simple-patchsys) doesn't need to be documented, since every NMUer should be able to work with them. Another example is build systems: cdbs is used by 20% of our packages, so I don't think that one need to document its use. If you look at the packages currently providing a debian/README.source (see gluck:~lucas/readme.source for a list), it seems that debian/README.source is used as a way to generate a large number of different howtos for patch systems. Having a common way to specify that one should look at another file if looking for documentation about something. Also, it would be interesting to extend the use of debian/README.source to other areas, such as: - whether the maintainer encourages commits for other people directly to the package's VCS. - the branch layout in the package's VCS. Maybe we could have a machine-parseable format to specify those, too. -- | Lucas Nussbaum | [EMAIL PROTECTED] http://www.lucas-nussbaum.net/ | | jabber: [EMAIL PROTECTED] GPG: 1024D/023B3F4F | -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Bug#495233: debian-policy: README.source content should be more detailed
Lucas Nussbaum wrote: First, section 4.14 should list things that one does not need to describe in debian/README.source. For example, the use of one of the standard patch systems (quilt, dpatch, simple-patchsys) doesn't need to be documented, since every NMUer should be able to work with them. Another example is build systems: cdbs is used by 20% of our packages, so I don't think that one need to document its use. I think the better way is do it similar to copyright: for common patch/build system we should include only a link to the relative document. Maybe on a common package (build essential or dpkg-dev) or on patch system package (but in this case we should push stronger the maintainer to include the relevant informations). BTW debian/README.source is not only for the MNUer, but also for our users, so I prefer redundant documentation. Also, it would be interesting to extend the use of debian/README.source to other areas, such as: - whether the maintainer encourages commits for other people directly to the package's VCS. - the branch layout in the package's VCS. I agree with that. PS: you should provide a patch! ciao cate -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Bug#495233: debian-policy: README.source content should be more detailed
Giacomo Catenazzi [EMAIL PROTECTED] writes: Lucas Nussbaum wrote: First, section 4.14 should list things that one does not need to describe in debian/README.source. For example, the use of one of the standard patch systems (quilt, dpatch, simple-patchsys) doesn't need to be documented, since every NMUer should be able to work with them. I don't agree. This was one of the things that came up specifically in the original discussion that led to the README.source compromise. If nothing else, README.source tells people that yes, this is bog-standard quilt or dpatch, so they don't have to figure out which it is and they don't have to wonder whether there's something weird at work. I would like this file to continue to contain pointers to the standard documentation for quilt or dpatch if those patch systems are used. We allowed for a pointer specifically so that all you have to do is include a line or two of reference. For example, I use: | 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. Please see: | | /usr/share/doc/quilt/README.source | | for more information on how to apply the patches, modify patches, or | remove a patch. quilt and dpatch could probably usefully recommend boilerplate text. Another example is build systems: cdbs is used by 20% of our packages, so I don't think that one need to document its use. I think the better way is do it similar to copyright: for common patch/build system we should include only a link to the relative document. Maybe on a common package (build essential or dpkg-dev) or on patch system package (but in this case we should push stronger the maintainer to include the relevant informations). Which is what Policy already says, and quilt, for example, provides such a document for README.source to link to. So I don't think Policy should be changed here. Also, it would be interesting to extend the use of debian/README.source to other areas, such as: - whether the maintainer encourages commits for other people directly to the package's VCS. - the branch layout in the package's VCS. There was some discussion of this on vcs-pkg, and I'm inclined to agree. The one potential argument against doing this is that README.source was intended to document the source package, and those aren't aspects of the source package, but I think the benefit outweighs a division of topic here and it's reasonable to put in this file anything that's relevant to someone wanting to modify it. -- Russ Allbery ([EMAIL PROTECTED]) http://www.eyrie.org/~eagle/ -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Bug#495233: debian-policy: README.source content should be more detailed
Lucas Nussbaum [EMAIL PROTECTED] writes: On 15/08/08 at 11:01 -0700, Russ Allbery wrote: Giacomo Catenazzi [EMAIL PROTECTED] writes: I think the better way is do it similar to copyright: for common patch/build system we should include only a link to the relative document. Maybe on a common package (build essential or dpkg-dev) or on patch system package (but in this case we should push stronger the maintainer to include the relevant informations). Which is what Policy already says, and quilt, for example, provides such a document for README.source to link to. So I don't think Policy should be changed here. But that won't work if we want to include more info in README.source. Why not? I would think you could include whatever information you want before or after the pointer to the standard quilt documentation. What about moving to a machine-parseable format, such as: Patch-system: quilt Patch-system-doc: /usr/share/doc/quilt/README.source I think that's kind of pointless for human-readable, human-targetted documention. Why would machines need to parse README.source? -- Russ Allbery ([EMAIL PROTECTED]) http://www.eyrie.org/~eagle/ -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Bug#495233: debian-policy: README.source content should be more detailed
On 15/08/08 at 11:01 -0700, Russ Allbery wrote: Giacomo Catenazzi [EMAIL PROTECTED] writes: Lucas Nussbaum wrote: First, section 4.14 should list things that one does not need to describe in debian/README.source. For example, the use of one of the standard patch systems (quilt, dpatch, simple-patchsys) doesn't need to be documented, since every NMUer should be able to work with them. I don't agree. This was one of the things that came up specifically in the original discussion that led to the README.source compromise. If nothing else, README.source tells people that yes, this is bog-standard quilt or dpatch, so they don't have to figure out which it is and they don't have to wonder whether there's something weird at work. I would like this file to continue to contain pointers to the standard documentation for quilt or dpatch if those patch systems are used. We allowed for a pointer specifically so that all you have to do is include a line or two of reference. For example, I use: | 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. Please see: | | /usr/share/doc/quilt/README.source | | for more information on how to apply the patches, modify patches, or | remove a patch. quilt and dpatch could probably usefully recommend boilerplate text. Another example is build systems: cdbs is used by 20% of our packages, so I don't think that one need to document its use. I think the better way is do it similar to copyright: for common patch/build system we should include only a link to the relative document. Maybe on a common package (build essential or dpkg-dev) or on patch system package (but in this case we should push stronger the maintainer to include the relevant informations). Which is what Policy already says, and quilt, for example, provides such a document for README.source to link to. So I don't think Policy should be changed here. But that won't work if we want to include more info in README.source. What about moving to a machine-parseable format, such as: Patch-system: quilt Patch-system-doc: /usr/share/doc/quilt/README.source -- | Lucas Nussbaum | [EMAIL PROTECTED] http://www.lucas-nussbaum.net/ | | jabber: [EMAIL PROTECTED] GPG: 1024D/023B3F4F | -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
