Hi Russ, First, thanks for your great work on this bug.
On Tue, Jan 01, 2008 at 10:54:06PM -0800, Russ Allbery wrote: > This is the last Policy bug I had tagged as wording. It started with a > proposal for a README.source file documenting how to do things with a > package that uses a non-trivial source format, and then expanded into > standardizing debian/rules targets for doing various things. > > Having reviewed the entire bug thread, I think there are a few > misconceptions and a few different cases mingled together, so I'm going to > attempt a summary. > > The original concern was being able to unpack a Debian source package and > immediately start patching it, with a goal of creating a modified source > package (for local modifications, security fixes, RC bug fixes, or what > have you). I think that sums it up quite right, yeah :) > Among the source package formats in Debian, I know of two possible > situations: [...summary of patch systems snipped...] > Now, I think that everyone (possibly except Marco) agrees with the basic > idea of providing a README.source file explaining how to deal with a > package that has a non-trivial source layout. In particular, I think > someone needs to know how to do all of the following: > > 1. Generate the fully patched sources, the sources in the state in which > they'll be built, so that one can check to see if problems have been > patched, look at the source, and so forth. > > 2. Add a new patch to the build process (including any special techniques > to use to generate the patch if there's an easier tool than recursive > diff from an unmodified package and the like). > > 3. Remove an existing patch from the build process. > > 4. Ideally, explain how to upgrade the package to a new upstream version, > although this should probably be optional. > > However, when we get into standardizing targets, this gets a lot murkier. > I think the discussion above makes it clear that the only thing that we > can really address with a target is point 1 above. For all of the > systems, in the general case of modifications that overlap with existing > patches, I don't think we can provide targets that do 2. 3 and 4 are > obviously outside what a target can do. Yes, that seems correct. I hadn't thought of that problem, actually, but now that you mention it, I don't think there are ways of making that easy. In short, as you show, sticking to just adding one or more optional targets to debian/rules isn't going to cut it. > Accordingly, I think moving forward with specifying a README.source file > that explains the above three or four points is something we can reach > consensus on. I'm not as sure about standardizing a target for 1 (setup, > unpack, and patch are all currently in use), but I suppose that we could > standardize on patched. This does raise insta-buggy issues since existing > packages don't provide that target. > > However, I don't think it's going to work to say that after running some > target, people should be able to make modifications and run > dpkg-buildpackage and expect to have that work. In each case, it looks > like there are cases where that isn't going to work, and I don't think > it's viable to say that those patch systems can't be used. Makes sense. > So, finally, I propose the following patch: > > --- orig/policy.sgml > +++ mod/policy.sgml > @@ -1926,6 +1926,19 @@ > possible is a good idea. > </p> > </item> > + > + <tag><tt>patched</tt> (optional)</tag> > + <item> > + <p> > + This target performs whatever additional actions are > + required to make the source ready for editing (unpacking > + additional upstream archives, applying patches, etc.). > + It is recommended to be implemented for any package where > + <tt>dpkg-source -x</tt> does not result in source ready > + for additional modification. See > + <ref id="readmesource">. > + </p> > + </item> > </taglist> > > <p> > @@ -2076,6 +2089,50 @@ > the file to the list in <file>debian/files</file>.</p> > </sect> > > + <sect> > + <heading>Source package handling: > + <file>debian/README.source</file></heading> > + > + <p> > + If running <prgn>dpkg-source -x</prgn> on a source package > + doesn't produce the source of the package, ready for editing, > + and allow one to make changes and run > + <prng>dpkg-buildpackage</prgn to produce a modified package ---^ Seems you've missed a > there. > + without taking any additional steps, creating a > + <file>debian/README.source</file> documentation file is > + recommended. This file should explain how to do all of the > + following: > + <enumlist> > + <item>Generate the fully patched source, in a form ready for > + editing, that would be built to create Debian > + packages. Doing this with a <tt>patched</tt> target in > + <file>debian/rules</file> is recommended; see > + <ref id="debianrules">.</item> > + <item>Modify the source and save those modifications so that > + they will be applied when building the package.</item> > + <item>Remove existing source modifications that previously > + were applied.</item> > + <item>Optionally, document what steps are necessary to > + upgrade the Debian source package to a new upstream version, > + if applicable.</item> > + </enumlist> > + 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. > + </p> > + > + <p> > + <file>debian/README.source</file> may also include any other > + information that would be helpful to someone modifying the > + source package. Even if the package doesn't fit the above > + description, maintainers are encouraged to document in a > + <file>debian/README.source</file> file any source package with a > + particularly complex or unintuitive source layout or build > + system (for example, a package that builds the same source > + multiple times to generate different binary packages). > + </p> > + </sect> > </chapt> I guess it was obvious from my above comments, but I'll second this patch (or accept it as a replacement of my original one, or whatever procedure requires me to do now). Thanks again, -- <Lo-lan-do> Home is where you have to wash the dishes. -- #debian-devel, Freenode, 2004-09-22
signature.asc
Description: Digital signature